OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /** | 5 /** |
6 * Concurrent programming using _isolates_: | 6 * Concurrent programming using _isolates_: |
7 * independent workers that are similar to threads | 7 * independent workers that are similar to threads |
8 * but don't share memory, | 8 * but don't share memory, |
9 * communicating only via messages. | 9 * communicating only via messages. |
10 */ | 10 */ |
(...skipping 191 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
202 external static Future<Isolate> spawnUri( | 202 external static Future<Isolate> spawnUri( |
203 Uri uri, | 203 Uri uri, |
204 List<String> args, | 204 List<String> args, |
205 var message, | 205 var message, |
206 {bool paused: false, | 206 {bool paused: false, |
207 Uri packageRoot}); | 207 Uri packageRoot}); |
208 | 208 |
209 /** | 209 /** |
210 * Requests the isolate to pause. | 210 * Requests the isolate to pause. |
211 * | 211 * |
212 * WARNING: This method is experimental and not handled on every platform yet. | |
213 * | |
214 * The isolate should stop handling events by pausing its event queue. | 212 * The isolate should stop handling events by pausing its event queue. |
215 * The request will eventually make the isolate stop doing anything. | 213 * The request will eventually make the isolate stop doing anything. |
216 * It will be handled before any other messages that are later sent to the | 214 * It will be handled before any other messages that are later sent to the |
217 * isolate from the current isolate, but no other guarantees are provided. | 215 * isolate from the current isolate, but no other guarantees are provided. |
218 * | 216 * |
219 * The event loop may be paused before previously sent, but not yet exeuted, | 217 * The event loop may be paused before previously sent, but not yet exeuted, |
220 * messages have been reached. | 218 * messages have been reached. |
221 * | 219 * |
222 * If [resumeCapability] is provided, it is used to identity the pause, | 220 * If [resumeCapability] is provided, it is used to identity the pause, |
223 * and must be used again to end the pause using [resume]. | 221 * and must be used again to end the pause using [resume]. |
(...skipping 12 matching lines...) Expand all Loading... |
236 _pause(resumeCapability); | 234 _pause(resumeCapability); |
237 return resumeCapability; | 235 return resumeCapability; |
238 } | 236 } |
239 | 237 |
240 /** Internal implementation of [pause]. */ | 238 /** Internal implementation of [pause]. */ |
241 external void _pause(Capability resumeCapability); | 239 external void _pause(Capability resumeCapability); |
242 | 240 |
243 /** | 241 /** |
244 * Resumes a paused isolate. | 242 * Resumes a paused isolate. |
245 * | 243 * |
246 * WARNING: This method is experimental and not handled on every platform yet. | |
247 * | |
248 * Sends a message to an isolate requesting that it ends a pause | 244 * Sends a message to an isolate requesting that it ends a pause |
249 * that was requested using the [resumeCapability]. | 245 * that was requested using the [resumeCapability]. |
250 * | 246 * |
251 * When all active pause requests have been cancelled, the isolate | 247 * When all active pause requests have been cancelled, the isolate |
252 * will continue handling normal messages. | 248 * will continue handling normal messages. |
253 * | 249 * |
254 * The capability must be one returned by a call to [pause] on this | 250 * The capability must be one returned by a call to [pause] on this |
255 * isolate, otherwise the resume call does nothing. | 251 * isolate, otherwise the resume call does nothing. |
256 */ | 252 */ |
257 external void resume(Capability resumeCapability); | 253 external void resume(Capability resumeCapability); |
258 | 254 |
259 /** | 255 /** |
260 * Asks the isolate to send [response] on [responsePort] when it terminates. | 256 * Asks the isolate to send [response] on [responsePort] when it terminates. |
261 * | 257 * |
262 * WARNING: This method is experimental and not handled on every platform yet. | |
263 * | |
264 * The isolate will send a `response` message on `responsePort` as the last | 258 * The isolate will send a `response` message on `responsePort` as the last |
265 * thing before it terminates. It will run no further code after the message | 259 * thing before it terminates. It will run no further code after the message |
266 * has been sent. | 260 * has been sent. |
267 * | 261 * |
268 * Adding the same port more than once will only cause it to receive one | 262 * Adding the same port more than once will only cause it to receive one |
269 * message, using the last response value that was added. | 263 * message, using the last response value that was added. |
270 * | 264 * |
271 * If the isolate is already dead, no message will be sent. | 265 * If the isolate is already dead, no message will be sent. |
272 * If `response` cannot be sent to the isolate, then the request is ignored. | 266 * If `response` cannot be sent to the isolate, then the request is ignored. |
273 * It is recommended to only use simple values that can be sent to all | 267 * It is recommended to only use simple values that can be sent to all |
274 * isolates, like `null`, booleans, numbers or strings. | 268 * isolates, like `null`, booleans, numbers or strings. |
275 */ | 269 */ |
276 /* TODO(lrn): Can we do better? Can the system recognize this message and | 270 /* TODO(lrn): Can we do better? Can the system recognize this message and |
277 * send a reply if the receiving isolate is dead? | 271 * send a reply if the receiving isolate is dead? |
278 */ | 272 */ |
279 external void addOnExitListener(SendPort responsePort, {Object response}); | 273 external void addOnExitListener(SendPort responsePort, {Object response}); |
280 | 274 |
281 /** | 275 /** |
282 * Stop listening on exit messages from the isolate. | 276 * Stop listening on exit messages from the isolate. |
283 * | 277 * |
284 * WARNING: This method is experimental and not handled on every platform yet. | |
285 * | |
286 * If a call has previously been made to [addOnExitListener] with the same | 278 * If a call has previously been made to [addOnExitListener] with the same |
287 * send-port, this will unregister the port, and it will no longer receive | 279 * send-port, this will unregister the port, and it will no longer receive |
288 * a message when the isolate terminates. | 280 * a message when the isolate terminates. |
289 * A response may still be sent until this operation is fully processed by | 281 * A response may still be sent until this operation is fully processed by |
290 * the isolate. | 282 * the isolate. |
291 */ | 283 */ |
292 external void removeOnExitListener(SendPort responsePort); | 284 external void removeOnExitListener(SendPort responsePort); |
293 | 285 |
294 /** | 286 /** |
295 * Set whether uncaught errors will terminate the isolate. | 287 * Set whether uncaught errors will terminate the isolate. |
296 * | 288 * |
297 * WARNING: This method is experimental and not handled on every platform yet. | |
298 * | |
299 * If errors are fatal, any uncaught error will terminate the isolate | 289 * If errors are fatal, any uncaught error will terminate the isolate |
300 * event loop and shut down the isolate. | 290 * event loop and shut down the isolate. |
301 * | 291 * |
302 * This call requires the [terminateCapability] for the isolate. | 292 * This call requires the [terminateCapability] for the isolate. |
303 * If the capability is not correct, no change is made. | 293 * If the capability is not correct, no change is made. |
304 */ | 294 */ |
305 external void setErrorsFatal(bool errorsAreFatal); | 295 external void setErrorsFatal(bool errorsAreFatal); |
306 | 296 |
307 /** | 297 /** |
308 * Requests the isolate to shut down. | 298 * Requests the isolate to shut down. |
309 * | 299 * |
310 * WARNING: This method is experimental and not handled on every platform yet. | |
311 * | |
312 * The isolate is requested to terminate itself. | 300 * The isolate is requested to terminate itself. |
313 * The [priority] argument specifies when this must happen. | 301 * The [priority] argument specifies when this must happen. |
314 * | 302 * |
315 * The [priority] must be one of [IMMEDIATE] or [BEFORE_NEXT_EVENT]. | 303 * The [priority] must be one of [IMMEDIATE] or [BEFORE_NEXT_EVENT]. |
316 * The shutdown is performed at different times depending on the priority: | 304 * The shutdown is performed at different times depending on the priority: |
317 * | 305 * |
318 * * `IMMEDIATE`: The the isolate shuts down as soon as possible. | 306 * * `IMMEDIATE`: The the isolate shuts down as soon as possible. |
319 * Control messages are handled in order, so all previously sent control | 307 * Control messages are handled in order, so all previously sent control |
320 * events from this isolate will all have been processed. | 308 * events from this isolate will all have been processed. |
321 * The shutdown should happen no later than if sent with | 309 * The shutdown should happen no later than if sent with |
322 * `BEFORE_NEXT_EVENT`. | 310 * `BEFORE_NEXT_EVENT`. |
323 * It may happen earlier if the system has a way to shut down cleanly | 311 * It may happen earlier if the system has a way to shut down cleanly |
324 * at an earlier time, even during the execution of another event. | 312 * at an earlier time, even during the execution of another event. |
325 * * `BEFORE_NEXT_EVENT`: The shutdown is scheduled for the next time | 313 * * `BEFORE_NEXT_EVENT`: The shutdown is scheduled for the next time |
326 * control returns to the event loop of the receiving isolate, | 314 * control returns to the event loop of the receiving isolate, |
327 * after the current event, and any already scheduled control events, | 315 * after the current event, and any already scheduled control events, |
328 * are completed. | 316 * are completed. |
329 */ | 317 */ |
330 external void kill({int priority: BEFORE_NEXT_EVENT}); | 318 external void kill({int priority: BEFORE_NEXT_EVENT}); |
331 | 319 |
332 /** | 320 /** |
333 * Request that the isolate send [response] on the [responsePort]. | 321 * Request that the isolate send [response] on the [responsePort]. |
334 * | 322 * |
335 * WARNING: This method is experimental and not handled on every platform yet. | |
336 * | |
337 * If the isolate is alive, it will eventually send `response` | 323 * If the isolate is alive, it will eventually send `response` |
338 * (defaulting to `null`) on the response port. | 324 * (defaulting to `null`) on the response port. |
339 * | 325 * |
340 * The [priority] must be one of [IMMEDIATE] or [BEFORE_NEXT_EVENT]. | 326 * The [priority] must be one of [IMMEDIATE] or [BEFORE_NEXT_EVENT]. |
341 * The response is sent at different times depending on the ping type: | 327 * The response is sent at different times depending on the ping type: |
342 * | 328 * |
343 * * `IMMEDIATE`: The the isolate responds as soon as it receives the | 329 * * `IMMEDIATE`: The the isolate responds as soon as it receives the |
344 * control message. This is after any previous control message | 330 * control message. This is after any previous control message |
345 * from the same isolate has been received, but may be during | 331 * from the same isolate has been received, but may be during |
346 * execution of another event. | 332 * execution of another event. |
347 * * `BEFORE_NEXT_EVENT`: The response is scheduled for the next time | 333 * * `BEFORE_NEXT_EVENT`: The response is scheduled for the next time |
348 * control returns to the event loop of the receiving isolate, | 334 * control returns to the event loop of the receiving isolate, |
349 * after the current event, and any already scheduled control events, | 335 * after the current event, and any already scheduled control events, |
350 * are completed. | 336 * are completed. |
351 * | 337 * |
352 * If `response` cannot be sent to the isolate, then the request is ignored. | 338 * If `response` cannot be sent to the isolate, then the request is ignored. |
353 * It is recommended to only use simple values that can be sent to all | 339 * It is recommended to only use simple values that can be sent to all |
354 * isolates, like `null`, booleans, numbers or strings. | 340 * isolates, like `null`, booleans, numbers or strings. |
355 */ | 341 */ |
356 external void ping(SendPort responsePort, {Object response, | 342 external void ping(SendPort responsePort, {Object response, |
357 int priority: IMMEDIATE}); | 343 int priority: IMMEDIATE}); |
358 | 344 |
359 /** | 345 /** |
360 * Requests that uncaught errors of the isolate are sent back to [port]. | 346 * Requests that uncaught errors of the isolate are sent back to [port]. |
361 * | 347 * |
362 * WARNING: This method is experimental and not handled on every platform yet. | |
363 * | |
364 * The errors are sent back as two elements lists. | 348 * The errors are sent back as two elements lists. |
365 * The first element is a `String` representation of the error, usually | 349 * The first element is a `String` representation of the error, usually |
366 * created by calling `toString` on the error. | 350 * created by calling `toString` on the error. |
367 * The second element is a `String` representation of an accompanying | 351 * The second element is a `String` representation of an accompanying |
368 * stack trace, or `null` if no stack trace was provided. | 352 * stack trace, or `null` if no stack trace was provided. |
369 * To convert this back to a [StackTrace] object, use [StackTrace.fromString]. | 353 * To convert this back to a [StackTrace] object, use [StackTrace.fromString]. |
370 * | 354 * |
371 * Listening using the same port more than once does nothing. It will only | 355 * Listening using the same port more than once does nothing. It will only |
372 * get each error once. | 356 * get each error once. |
373 */ | 357 */ |
374 external void addErrorListener(SendPort port); | 358 external void addErrorListener(SendPort port); |
375 | 359 |
376 /** | 360 /** |
377 * Stop listening for uncaught errors through [port]. | 361 * Stop listening for uncaught errors through [port]. |
378 * | 362 * |
379 * WARNING: This method is experimental and not handled on every platform yet. | |
380 * | |
381 * The `port` should be a port that is listening for errors through | 363 * The `port` should be a port that is listening for errors through |
382 * [addErrorListener]. This call requests that the isolate stops sending | 364 * [addErrorListener]. This call requests that the isolate stops sending |
383 * errors on the port. | 365 * errors on the port. |
384 * | 366 * |
385 * If the same port has been passed via `addErrorListener` more than once, | 367 * If the same port has been passed via `addErrorListener` more than once, |
386 * only one call to `removeErrorListener` is needed to stop it from receiving | 368 * only one call to `removeErrorListener` is needed to stop it from receiving |
387 * errors. | 369 * errors. |
388 * | 370 * |
389 * Closing the receive port at the end of the send port will not stop the | 371 * Closing the receive port at the end of the send port will not stop the |
390 * isolate from sending errors, they are just going to be lost. | 372 * isolate from sending errors, they are just going to be lost. |
(...skipping 207 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
598 * as the original error, but has no other features of the original error. | 580 * as the original error, but has no other features of the original error. |
599 */ | 581 */ |
600 class RemoteError implements Error { | 582 class RemoteError implements Error { |
601 final String _description; | 583 final String _description; |
602 final StackTrace stackTrace; | 584 final StackTrace stackTrace; |
603 RemoteError(String description, String stackDescription) | 585 RemoteError(String description, String stackDescription) |
604 : _description = description, | 586 : _description = description, |
605 stackTrace = new StackTrace.fromString(stackDescription); | 587 stackTrace = new StackTrace.fromString(stackDescription); |
606 String toString() => _description; | 588 String toString() => _description; |
607 } | 589 } |
OLD | NEW |