OLD | NEW |
| (Empty) |
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 | |
3 // BSD-style license that can be found in the LICENSE file. | |
4 | |
5 /** | |
6 * Concurrent programming using _isolates_: | |
7 * independent workers that are similar to threads | |
8 * but don't share memory, | |
9 * communicating only via messages. | |
10 */ | |
11 library dart.isolate; | |
12 | |
13 import "dart:async"; | |
14 | |
15 part "capability.dart"; | |
16 | |
17 /** | |
18 * Thrown when an isolate cannot be created. | |
19 */ | |
20 class IsolateSpawnException implements Exception { | |
21 /** Error message reported by the spawn operation. */ | |
22 final String message; | |
23 IsolateSpawnException(this.message); | |
24 String toString() => "IsolateSpawnException: $message"; | |
25 } | |
26 | |
27 /** | |
28 * An isolated Dart execution context. | |
29 * | |
30 * All Dart code runs in an isolate, and code can access classes and values | |
31 * only from the same isolate. Different isolates can communicate by sending | |
32 * values through ports (see [ReceivePort], [SendPort]). | |
33 * | |
34 * An `Isolate` object is a reference to an isolate, usually different from | |
35 * the current isolate. | |
36 * It represents, and can be used control, the other isolate. | |
37 * | |
38 * When spawning a new isolate, the spawning isolate receives an `Isolate` | |
39 * object representing the new isolate when the spawn operation succeeds. | |
40 * | |
41 * Isolates run code in its own event loop, and each event may run smaller tasks | |
42 * in a nested microtask queue. | |
43 * | |
44 * An `Isolate` object allows other isolates to control the event loop | |
45 * of the isolate that it represents, and to inspect the isolate, | |
46 * for example by pausing the isolate or by getting events when the isolate | |
47 * has an uncaught error. | |
48 * | |
49 * The [controlPort] gives access to controlling the isolate, and the | |
50 * [pauseCapability] and [terminateCapability] guard access to some control | |
51 * operations. | |
52 * The `Isolate` object provided by a spawn operation will have the | |
53 * control port and capabilities needed to control the isolate. | |
54 * New isolates objects can be created without some of these capabilities | |
55 * if necessary. | |
56 * | |
57 * An `Isolate` object cannot be sent over a `SendPort`, but the control port | |
58 * and capabilities can be sent, and can be used to create a new functioning | |
59 * `Isolate` object in the receiving port's isolate. | |
60 */ | |
61 class Isolate { | |
62 /** Argument to `ping` and `kill`: Ask for immediate action. */ | |
63 static const int IMMEDIATE = 0; | |
64 /** Argument to `ping` and `kill`: Ask for action before the next event. */ | |
65 static const int BEFORE_NEXT_EVENT = 1; | |
66 /** Argument to `ping` and `kill`: Ask for action after normal events. */ | |
67 static const int AS_EVENT = 2; | |
68 | |
69 /** | |
70 * Control port used to send control messages to the isolate. | |
71 * | |
72 * This class provides helper functions that sends control messages | |
73 * to the control port. | |
74 * | |
75 * The control port identifies the isolate. | |
76 */ | |
77 final SendPort controlPort; | |
78 | |
79 /** | |
80 * Capability granting the ability to pause the isolate. | |
81 * | |
82 * This capability is used by [pause]. | |
83 * If the capability is not the correct pause capability of the isolate, | |
84 * including if the capability is `null`, then calls to `pause` will have no | |
85 * effect. | |
86 * | |
87 * If the isolate is started in a paused state, use this capability as | |
88 * argument to [resume] to resume the isolate. | |
89 */ | |
90 final Capability pauseCapability; | |
91 | |
92 /** | |
93 * Capability granting the ability to terminate the isolate. | |
94 * | |
95 * This capability is used by [kill] and [setErrorsFatal]. | |
96 * If the capability is not the correct termination capability of the isolate, | |
97 * including if the capability is `null`, then calls to those methods will | |
98 * have no effect. | |
99 */ | |
100 final Capability terminateCapability; | |
101 | |
102 /** | |
103 * Create a new [Isolate] object with a restricted set of capabilities. | |
104 * | |
105 * The port should be a control port for an isolate, as taken from | |
106 * another `Isolate` object. | |
107 * | |
108 * The capabilities should be the subset of the capabilities that are | |
109 * available to the original isolate. | |
110 * Capabilities of an isolate are locked to that isolate, and have no effect | |
111 * anywhere else, so the capabilities should come from the same isolate as | |
112 * the control port. | |
113 * | |
114 * If all the available capabilities are included, | |
115 * there is no reason to create a new object, | |
116 * since the behavior is defined entirely | |
117 * by the control port and capabilities. | |
118 */ | |
119 Isolate(this.controlPort, {this.pauseCapability, | |
120 this.terminateCapability}); | |
121 | |
122 /** | |
123 * Return the current [Isolate]. | |
124 * | |
125 * The isolate gives access to the capabilities needed to inspect, | |
126 * pause or kill the isolate, and allows granting these capabilities | |
127 * to others. | |
128 */ | |
129 external static Isolate get current; | |
130 | |
131 /** | |
132 * Creates and spawns an isolate that shares the same code as the current | |
133 * isolate. | |
134 * | |
135 * The argument [entryPoint] specifies the entry point of the spawned | |
136 * isolate. It must be a top-level function or a static method that | |
137 * takes one argument - that is, one-parameter functions that can be | |
138 * compile-time constant function values. | |
139 * It is not allowed to pass the value of function expressions or an instance | |
140 * method extracted from an object. | |
141 * | |
142 * The entry-point function is invoked with the initial [message]. | |
143 * Usually the initial [message] contains a [SendPort] so | |
144 * that the spawner and spawnee can communicate with each other. | |
145 * | |
146 * If the [paused] parameter is set to `true`, | |
147 * the isolate will start up in a paused state, | |
148 * as if by an initial call of `isolate.pause(isolate.pauseCapability)`. | |
149 * This allows setting up error or exit listeners on the isolate | |
150 * before it starts running. | |
151 * To resume the isolate, call `isolate.resume(isolate.pauseCapability)`. | |
152 * | |
153 * WARNING: The `pause` parameter is not implemented on all platforms yet. | |
154 * | |
155 * Returns a future that will complete with an [Isolate] instance if the | |
156 * spawning succeeded. It will complete with an error otherwise. | |
157 */ | |
158 external static Future<Isolate> spawn(void entryPoint(message), var message, | |
159 { bool paused: false }); | |
160 | |
161 /** | |
162 * Creates and spawns an isolate that runs the code from the library with | |
163 * the specified URI. | |
164 * | |
165 * The isolate starts executing the top-level `main` function of the library | |
166 * with the given URI. | |
167 * | |
168 * The target `main` must be a subtype of one of these three signatures: | |
169 * | |
170 * * `main()` | |
171 * * `main(args)` | |
172 * * `main(args, message)` | |
173 * | |
174 * When present, the parameter `args` is set to the provided [args] list. | |
175 * When present, the parameter `message` is set to the initial [message]. | |
176 * | |
177 * If the [packageRoot] parameter is provided, it is used to find the location | |
178 * of packages imports in the spawned isolate. | |
179 * The `packageRoot` URI must be a "file" or "http"/"https" URI that specifies | |
180 * a directory. If it doesn't end in a slash, one will be added before | |
181 * using the URI, and any query or fragment parts are ignored. | |
182 * Package imports (like "package:foo/bar.dart") in the new isolate are | |
183 * resolved against this location, as by | |
184 * `packageRoot.resolve("foo/bar.dart")`. | |
185 * This includes the main entry [uri] if it happens to be a package-URL. | |
186 * If [packageRoot] is omitted, it defaults to the same URI that | |
187 * the current isolate is using. | |
188 * | |
189 * WARNING: The [packageRoot] parameter is not implemented on all | |
190 * platforms yet. | |
191 * | |
192 * If the [paused] parameter is set to `true`, | |
193 * the isolate will start up in a paused state, | |
194 * as if by an initial call of `isolate.pause(isolate.pauseCapability)`. | |
195 * This allows setting up error or exit listeners on the isolate | |
196 * before it starts running. | |
197 * To resume the isolate, call `isolate.resume(isolate.pauseCapability)`. | |
198 * | |
199 * WARNING: The `pause` parameter is not implemented on all platforms yet. | |
200 * | |
201 * Returns a future that will complete with an [Isolate] instance if the | |
202 * spawning succeeded. It will complete with an error otherwise. | |
203 */ | |
204 external static Future<Isolate> spawnUri( | |
205 Uri uri, | |
206 List<String> args, | |
207 var message, | |
208 {bool paused: false, | |
209 Uri packageRoot}); | |
210 | |
211 /** | |
212 * Requests the isolate to pause. | |
213 * | |
214 * WARNING: This method is experimental and not handled on every platform yet. | |
215 * | |
216 * The isolate should stop handling events by pausing its event queue. | |
217 * The request will eventually make the isolate stop doing anything. | |
218 * It will be handled before any other messages that are later sent to the | |
219 * isolate from the current isolate, but no other guarantees are provided. | |
220 * | |
221 * The event loop may be paused before previously sent, but not yet exeuted, | |
222 * messages have been reached. | |
223 * | |
224 * If [resumeCapability] is provided, it is used to identity the pause, | |
225 * and must be used again to end the pause using [resume]. | |
226 * Otherwise a new resume capability is created and returned. | |
227 * | |
228 * If an isolate is paused more than once using the same capability, | |
229 * only one resume with that capability is needed to end the pause. | |
230 * | |
231 * If an isolate is paused using more than one capability, | |
232 * they must all be individully ended before the isolate resumes. | |
233 * | |
234 * Returns the capability that must be used to resume end the pause. | |
235 */ | |
236 Capability pause([Capability resumeCapability]) { | |
237 if (resumeCapability == null) resumeCapability = new Capability(); | |
238 _pause(resumeCapability); | |
239 return resumeCapability; | |
240 } | |
241 | |
242 /** Internal implementation of [pause]. */ | |
243 external void _pause(Capability resumeCapability); | |
244 | |
245 /** | |
246 * Resumes a paused isolate. | |
247 * | |
248 * WARNING: This method is experimental and not handled on every platform yet. | |
249 * | |
250 * Sends a message to an isolate requesting that it ends a pause | |
251 * that was requested using the [resumeCapability]. | |
252 * | |
253 * When all active pause requests have been cancelled, the isolate | |
254 * will continue handling normal messages. | |
255 * | |
256 * The capability must be one returned by a call to [pause] on this | |
257 * isolate, otherwise the resume call does nothing. | |
258 */ | |
259 external void resume(Capability resumeCapability); | |
260 | |
261 /** | |
262 * Asks the isolate to send a message on [responsePort] when it terminates. | |
263 * | |
264 * WARNING: This method is experimental and not handled on every platform yet. | |
265 * | |
266 * The isolate will send a `null` message on [responsePort] as the last | |
267 * thing before it terminates. It will run no further code after the message | |
268 * has been sent. | |
269 * | |
270 * If the isolate is already dead, no message will be sent. | |
271 */ | |
272 /* TODO(lrn): Can we do better? Can the system recognize this message and | |
273 * send a reply if the receiving isolate is dead? | |
274 */ | |
275 external void addOnExitListener(SendPort responsePort); | |
276 | |
277 /** | |
278 * Stop listening on exit messages from the isolate. | |
279 * | |
280 * WARNING: This method is experimental and not handled on every platform yet. | |
281 * | |
282 * If a call has previously been made to [addOnExitListener] with the same | |
283 * send-port, this will unregister the port, and it will no longer receive | |
284 * a message when the isolate terminates. | |
285 * A response may still be sent until this operation is fully processed by | |
286 * the isolate. | |
287 */ | |
288 external void removeOnExitListener(SendPort responsePort); | |
289 | |
290 /** | |
291 * Set whether uncaught errors will terminate the isolate. | |
292 * | |
293 * WARNING: This method is experimental and not handled on every platform yet. | |
294 * | |
295 * If errors are fatal, any uncaught error will terminate the isolate | |
296 * event loop and shut down the isolate. | |
297 * | |
298 * This call requires the [terminateCapability] for the isolate. | |
299 * If the capability is not correct, no change is made. | |
300 */ | |
301 external void setErrorsFatal(bool errorsAreFatal); | |
302 | |
303 /** | |
304 * Requests the isolate to shut down. | |
305 * | |
306 * WARNING: This method is experimental and not handled on every platform yet. | |
307 * | |
308 * The isolate is requested to terminate itself. | |
309 * The [priority] argument specifies when this must happen. | |
310 * | |
311 * The [priority] must be one of [IMMEDIATE], [BEFORE_NEXT_EVENT] or | |
312 * [AS_EVENT]. | |
313 * The shutdown is performed at different times depending on the priority: | |
314 * | |
315 * * `IMMEDIATE`: The isolate shuts down as soon as possible. | |
316 * Control messages are handled in order, so all previously sent control | |
317 * events from this isolate will all have been processed. | |
318 * The shutdown should happen no later than if sent with | |
319 * `BEFORE_NEXT_EVENT`. | |
320 * It may happen earlier if the system has a way to shut down cleanly | |
321 * at an earlier time, even during the execution of another event. | |
322 * * `BEFORE_NEXT_EVENT`: The shutdown is scheduled for the next time | |
323 * control returns to the event loop of the receiving isolate, | |
324 * after the current event, and any already scheduled control events, | |
325 * are completed. | |
326 * * `AS_EVENT`: The shutdown does not happen until all prevously sent | |
327 * non-control messages from the current isolate to the receiving isolate | |
328 * have been processed. | |
329 * The kill operation effectively puts the shutdown into the normal event | |
330 * queue after previously sent messages, and it is affected by any control | |
331 * messages that affect normal events, including `pause`. | |
332 * This can be used to wait for a another event to be processed. | |
333 */ | |
334 external void kill([int priority = BEFORE_NEXT_EVENT]); | |
335 | |
336 /** | |
337 * Request that the isolate send a response on the [responsePort]. | |
338 * | |
339 * WARNING: This method is experimental and not handled on every platform yet. | |
340 * | |
341 * If the isolate is alive, it will eventually send a `null` response on | |
342 * the response port. | |
343 * | |
344 * The [pingType] must be one of [IMMEDIATE], [BEFORE_NEXT_EVENT] or | |
345 * [AS_EVENT]. | |
346 * The response is sent at different times depending on the ping type: | |
347 * | |
348 * * `IMMEDIATE`: The isolate responds as soon as it receives the | |
349 * control message. This is after any previous control message | |
350 * from the same isolate has been received. | |
351 * * `BEFORE_NEXT_EVENT`: The response is scheduled for the next time | |
352 * control returns to the event loop of the receiving isolate, | |
353 * after the current event, and any already scheduled control events, | |
354 * are completed. | |
355 * * `AS_EVENT`: The response is not sent until all prevously sent | |
356 * non-control messages from the current isolate to the receiving isolate | |
357 * have been processed. | |
358 * The ping effectively puts the response into the normal event queue | |
359 * after previously sent messages, and it is affected by any control | |
360 * messages that affect normal events, including `pause`. | |
361 * This can be used to wait for a another event to be processed. | |
362 */ | |
363 external void ping(SendPort responsePort, [int pingType = IMMEDIATE]); | |
364 | |
365 /** | |
366 * Requests that uncaught errors of the isolate are sent back to [port]. | |
367 * | |
368 * WARNING: This method is experimental and not handled on every platform yet. | |
369 * | |
370 * The errors are sent back as two elements lists. | |
371 * The first element is a `String` representation of the error, usually | |
372 * created by calling `toString` on the error. | |
373 * The second element is a `String` representation of an accompanying | |
374 * stack trace, or `null` if no stack trace was provided. | |
375 * | |
376 * Listening using the same port more than once does nothing. It will only | |
377 * get each error once. | |
378 */ | |
379 external void addErrorListener(SendPort port); | |
380 | |
381 /** | |
382 * Stop listening for uncaught errors through [port]. | |
383 * | |
384 * WARNING: This method is experimental and not handled on every platform yet. | |
385 * | |
386 * The `port` should be a port that is listening for errors through | |
387 * [addErrorListener]. This call requests that the isolate stops sending | |
388 * errors on the port. | |
389 * | |
390 * If the same port has been passed via `addErrorListener` more than once, | |
391 * only one call to `removeErrorListener` is needed to stop it from receiving | |
392 * errors. | |
393 * | |
394 * Closing the receive port at the end of the send port will not stop the | |
395 * isolate from sending errors, they are just going to be lost. | |
396 */ | |
397 external void removeErrorListener(SendPort port); | |
398 | |
399 /** | |
400 * Returns a broadcast stream of uncaught errors from the isolate. | |
401 * | |
402 * Each error is provided as an error event on the stream. | |
403 * | |
404 * The actual error object and stackTraces will not necessarily | |
405 * be the same object types as in the actual isolate, but they will | |
406 * always have the same [Object.toString] result. | |
407 * | |
408 * This stream is based on [addErrorListener] and [removeErrorListener]. | |
409 */ | |
410 Stream get errors { | |
411 StreamController controller; | |
412 RawReceivePort port; | |
413 void handleError(message) { | |
414 String errorDescription = message[0]; | |
415 String stackDescription = message[1]; | |
416 var error = new RemoteError(errorDescription, stackDescription); | |
417 controller.addError(error, error.stackTrace); | |
418 } | |
419 controller = new StreamController.broadcast( | |
420 sync: true, | |
421 onListen: () { | |
422 port = new RawReceivePort(handleError); | |
423 this.addErrorListener(port.sendPort); | |
424 }, | |
425 onCancel: () { | |
426 this.removeErrorListener(port.sendPort); | |
427 port.close(); | |
428 port = null; | |
429 }); | |
430 return controller.stream; | |
431 } | |
432 } | |
433 | |
434 /** | |
435 * Sends messages to its [ReceivePort]s. | |
436 * | |
437 * [SendPort]s are created from [ReceivePort]s. Any message sent through | |
438 * a [SendPort] is delivered to its corresponding [ReceivePort]. There might be | |
439 * many [SendPort]s for the same [ReceivePort]. | |
440 * | |
441 * [SendPort]s can be transmitted to other isolates, and they preserve equality | |
442 * when sent. | |
443 */ | |
444 abstract class SendPort implements Capability { | |
445 | |
446 /** | |
447 * Sends an asynchronous [message] through this send port, to its | |
448 * corresponding `ReceivePort`. | |
449 * | |
450 * The content of [message] can be: primitive values (null, num, bool, double, | |
451 * String), instances of [SendPort], and lists and maps whose elements are any | |
452 * of these. List and maps are also allowed to be cyclic. | |
453 * | |
454 * In the special circumstances when two isolates share the same code and are | |
455 * running in the same process (e.g. isolates created via [Isolate.spawn]), it | |
456 * is also possible to send object instances (which would be copied in the | |
457 * process). This is currently only supported by the dartvm. For now, the | |
458 * dart2js compiler only supports the restricted messages described above. | |
459 */ | |
460 void send(var message); | |
461 | |
462 /** | |
463 * Tests whether [other] is a [SendPort] pointing to the same | |
464 * [ReceivePort] as this one. | |
465 */ | |
466 bool operator==(var other); | |
467 | |
468 /** | |
469 * Returns an immutable hash code for this send port that is | |
470 * consistent with the == operator. | |
471 */ | |
472 int get hashCode; | |
473 } | |
474 | |
475 /** | |
476 * Together with [SendPort], the only means of communication between isolates. | |
477 * | |
478 * [ReceivePort]s have a `sendPort` getter which returns a [SendPort]. | |
479 * Any message that is sent through this [SendPort] | |
480 * is delivered to the [ReceivePort] it has been created from. There, the | |
481 * message is dispatched to the `ReceivePort`'s listener. | |
482 * | |
483 * A [ReceivePort] is a non-broadcast stream. This means that it buffers | |
484 * incoming messages until a listener is registered. Only one listener can | |
485 * receive messages. See [Stream.asBroadcastStream] for transforming the port | |
486 * to a broadcast stream. | |
487 * | |
488 * A [ReceivePort] may have many [SendPort]s. | |
489 */ | |
490 abstract class ReceivePort implements Stream { | |
491 | |
492 /** | |
493 * Opens a long-lived port for receiving messages. | |
494 * | |
495 * A [ReceivePort] is a non-broadcast stream. This means that it buffers | |
496 * incoming messages until a listener is registered. Only one listener can | |
497 * receive messages. See [Stream.asBroadcastStream] for transforming the port | |
498 * to a broadcast stream. | |
499 * | |
500 * A receive port is closed by canceling its subscription. | |
501 */ | |
502 external factory ReceivePort(); | |
503 | |
504 /** | |
505 * Creates a [ReceivePort] from a [RawReceivePort]. | |
506 * | |
507 * The handler of the given [rawPort] is overwritten during the construction | |
508 * of the result. | |
509 */ | |
510 external factory ReceivePort.fromRawReceivePort(RawReceivePort rawPort); | |
511 | |
512 /** | |
513 * Inherited from [Stream]. | |
514 * | |
515 * Note that [onError] and [cancelOnError] are ignored since a ReceivePort | |
516 * will never receive an error. | |
517 * | |
518 * The [onDone] handler will be called when the stream closes. | |
519 * The stream closes when [close] is called. | |
520 */ | |
521 StreamSubscription listen(void onData(var message), | |
522 { Function onError, | |
523 void onDone(), | |
524 bool cancelOnError }); | |
525 | |
526 /** | |
527 * Closes `this`. | |
528 * | |
529 * If the stream has not been canceled yet, adds a close-event to the event | |
530 * queue and discards any further incoming messages. | |
531 * | |
532 * If the stream has already been canceled this method has no effect. | |
533 */ | |
534 void close(); | |
535 | |
536 /** | |
537 * Returns a [SendPort] that sends to this receive port. | |
538 */ | |
539 SendPort get sendPort; | |
540 } | |
541 | |
542 abstract class RawReceivePort { | |
543 /** | |
544 * Opens a long-lived port for receiving messages. | |
545 * | |
546 * A [RawReceivePort] is low level and does not work with [Zone]s. It | |
547 * can not be paused. The data-handler must be set before the first | |
548 * event is received. | |
549 */ | |
550 external factory RawReceivePort([void handler(event)]); | |
551 | |
552 /** | |
553 * Sets the handler that is invoked for every incoming message. | |
554 * | |
555 * The handler is invoked in the root-zone ([Zone.ROOT]). | |
556 */ | |
557 void set handler(Function newHandler); | |
558 | |
559 /** | |
560 * Closes the port. | |
561 * | |
562 * After a call to this method any incoming message is silently dropped. | |
563 */ | |
564 void close(); | |
565 | |
566 /** | |
567 * Returns a [SendPort] that sends to this raw receive port. | |
568 */ | |
569 SendPort get sendPort; | |
570 } | |
571 | |
572 /** | |
573 * Wraps unhandled exceptions thrown during isolate execution. It is | |
574 * used to show both the error message and the stack trace for unhandled | |
575 * exceptions. | |
576 */ | |
577 // TODO(floitsch): probably going to remove and replace with something else. | |
578 class _IsolateUnhandledException implements Exception { | |
579 /** Message being handled when exception occurred. */ | |
580 final message; | |
581 | |
582 /** Wrapped exception. */ | |
583 final source; | |
584 | |
585 /** Trace for the wrapped exception. */ | |
586 final StackTrace stackTrace; | |
587 | |
588 const _IsolateUnhandledException(this.message, this.source, this.stackTrace); | |
589 | |
590 String toString() { | |
591 return 'IsolateUnhandledException: exception while handling message: ' | |
592 '${message} \n ' | |
593 '${source.toString().replaceAll("\n", "\n ")}\n' | |
594 'original stack trace:\n ' | |
595 '${stackTrace.toString().replaceAll("\n","\n ")}'; | |
596 } | |
597 } | |
598 | |
599 /** | |
600 * Description of an error from another isolate. | |
601 * | |
602 * This error has the same `toString()` and `stackTrace.toString()` behavior | |
603 * as the original error, but has no other features of the original error. | |
604 */ | |
605 class RemoteError implements Error { | |
606 final String _description; | |
607 final StackTrace stackTrace; | |
608 RemoteError(String description, String stackDescription) | |
609 : _description = description, | |
610 stackTrace = new _RemoteStackTrace(stackDescription); | |
611 String toString() => _description; | |
612 } | |
613 | |
614 class _RemoteStackTrace implements StackTrace { | |
615 String _trace; | |
616 _RemoteStackTrace(this._trace); | |
617 String toString() => _trace; | |
618 } | |
OLD | NEW |