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 115 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
126 * Example: | 126 * Example: |
127 * ```dart | 127 * ```dart |
128 * Isolate isolate = findSomeIsolate(); | 128 * Isolate isolate = findSomeIsolate(); |
129 * Isolate restrictedIsolate = new Isolate(isolate.controlPort); | 129 * Isolate restrictedIsolate = new Isolate(isolate.controlPort); |
130 * untrustedCode(restrictedIsolate); | 130 * untrustedCode(restrictedIsolate); |
131 * ``` | 131 * ``` |
132 * This example creates a new `Isolate` object that cannot be used to | 132 * This example creates a new `Isolate` object that cannot be used to |
133 * pause or terminate the isolate. All the untrusted code can do is to | 133 * pause or terminate the isolate. All the untrusted code can do is to |
134 * inspect the isolate and see uncaught errors or when it terminates. | 134 * inspect the isolate and see uncaught errors or when it terminates. |
135 */ | 135 */ |
136 Isolate(this.controlPort, {this.pauseCapability, | 136 Isolate(this.controlPort, {this.pauseCapability, this.terminateCapability}); |
137 this.terminateCapability}); | |
138 | 137 |
139 /** | 138 /** |
140 * Return an [Isolate] object representing the current isolate. | 139 * Return an [Isolate] object representing the current isolate. |
141 * | 140 * |
142 * The current isolate for code using [current] | 141 * The current isolate for code using [current] |
143 * is the isolate running the code. | 142 * is the isolate running the code. |
144 * | 143 * |
145 * The isolate object provides the capabilities required to inspect, | 144 * The isolate object provides the capabilities required to inspect, |
146 * pause or kill the isolate, and allows granting these capabilities | 145 * pause or kill the isolate, and allows granting these capabilities |
147 * to others. | 146 * to others. |
(...skipping 71 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
219 * | 218 * |
220 * You can also call the [setErrorsFatal], [addOnExitListener] and | 219 * You can also call the [setErrorsFatal], [addOnExitListener] and |
221 * [addErrorListener] methods on the returned isolate, but unless the | 220 * [addErrorListener] methods on the returned isolate, but unless the |
222 * isolate was started as [paused], it may already have terminated | 221 * isolate was started as [paused], it may already have terminated |
223 * before those methods can complete. | 222 * before those methods can complete. |
224 * | 223 * |
225 * Returns a future which will complete with an [Isolate] instance if the | 224 * Returns a future which will complete with an [Isolate] instance if the |
226 * spawning succeeded. It will complete with an error otherwise. | 225 * spawning succeeded. It will complete with an error otherwise. |
227 */ | 226 */ |
228 external static Future<Isolate> spawn(void entryPoint(message), var message, | 227 external static Future<Isolate> spawn(void entryPoint(message), var message, |
229 {bool paused: false, | 228 {bool paused: false, |
230 bool errorsAreFatal, | 229 bool errorsAreFatal, |
231 SendPort onExit, | 230 SendPort onExit, |
232 SendPort onError}); | 231 SendPort onError}); |
233 | 232 |
234 /** | 233 /** |
235 * Creates and spawns an isolate that runs the code from the library with | 234 * Creates and spawns an isolate that runs the code from the library with |
236 * the specified URI. | 235 * the specified URI. |
237 * | 236 * |
238 * The isolate starts executing the top-level `main` function of the library | 237 * The isolate starts executing the top-level `main` function of the library |
239 * with the given URI. | 238 * with the given URI. |
240 * | 239 * |
241 * The target `main` must be callable with zero, one or two arguments. | 240 * The target `main` must be callable with zero, one or two arguments. |
242 * Examples: | 241 * Examples: |
(...skipping 58 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
301 * If `environment` is omitted, the spawned isolate has the same environment | 300 * If `environment` is omitted, the spawned isolate has the same environment |
302 * declarations as the spawning isolate. | 301 * declarations as the spawning isolate. |
303 * | 302 * |
304 * WARNING: The [environment] parameter is not implemented on all | 303 * WARNING: The [environment] parameter is not implemented on all |
305 * platforms yet. | 304 * platforms yet. |
306 * | 305 * |
307 * Returns a future that will complete with an [Isolate] instance if the | 306 * Returns a future that will complete with an [Isolate] instance if the |
308 * spawning succeeded. It will complete with an error otherwise. | 307 * spawning succeeded. It will complete with an error otherwise. |
309 */ | 308 */ |
310 external static Future<Isolate> spawnUri( | 309 external static Future<Isolate> spawnUri( |
311 Uri uri, | 310 Uri uri, List<String> args, var message, |
312 List<String> args, | |
313 var message, | |
314 {bool paused: false, | 311 {bool paused: false, |
315 SendPort onExit, | 312 SendPort onExit, |
316 SendPort onError, | 313 SendPort onError, |
317 bool errorsAreFatal, | 314 bool errorsAreFatal, |
318 bool checked, | 315 bool checked, |
319 Map<String, String> environment, | 316 Map<String, String> environment, |
320 Uri packageRoot, | 317 Uri packageRoot, |
321 Uri packageConfig, | 318 Uri packageConfig, |
322 bool automaticPackageResolution: false}); | 319 bool automaticPackageResolution: false}); |
323 | 320 |
324 /** | 321 /** |
325 * Requests the isolate to pause. | 322 * Requests the isolate to pause. |
326 * | 323 * |
327 * When the isolate receives the pause command, it stops | 324 * When the isolate receives the pause command, it stops |
328 * processing events from the event loop queue. | 325 * processing events from the event loop queue. |
329 * It may still add new events to the queue in response to, e.g., timers | 326 * It may still add new events to the queue in response to, e.g., timers |
330 * or receive-port messages. When the isolate is resumed, | 327 * or receive-port messages. When the isolate is resumed, |
331 * it starts handling the already enqueued events. | 328 * it starts handling the already enqueued events. |
332 * | 329 * |
(...skipping 157 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
490 * | 487 * |
491 * * `IMMEDIATE`: The isolate responds as soon as it receives the | 488 * * `IMMEDIATE`: The isolate responds as soon as it receives the |
492 * control message. This is after any previous control message | 489 * control message. This is after any previous control message |
493 * from the same isolate has been received and processed, | 490 * from the same isolate has been received and processed, |
494 * but may be during execution of another event. | 491 * but may be during execution of another event. |
495 * * `BEFORE_NEXT_EVENT`: The response is scheduled for the next time | 492 * * `BEFORE_NEXT_EVENT`: The response is scheduled for the next time |
496 * control returns to the event loop of the receiving isolate, | 493 * control returns to the event loop of the receiving isolate, |
497 * after the current event, and any already scheduled control events, | 494 * after the current event, and any already scheduled control events, |
498 * are completed. | 495 * are completed. |
499 */ | 496 */ |
500 external void ping(SendPort responsePort, {Object response, | 497 external void ping(SendPort responsePort, |
501 int priority: IMMEDIATE}); | 498 {Object response, int priority: IMMEDIATE}); |
502 | 499 |
503 /** | 500 /** |
504 * Requests that uncaught errors of the isolate are sent back to [port]. | 501 * Requests that uncaught errors of the isolate are sent back to [port]. |
505 * | 502 * |
506 * The errors are sent back as two elements lists. | 503 * The errors are sent back as two elements lists. |
507 * The first element is a `String` representation of the error, usually | 504 * The first element is a `String` representation of the error, usually |
508 * created by calling `toString` on the error. | 505 * created by calling `toString` on the error. |
509 * The second element is a `String` representation of an accompanying | 506 * The second element is a `String` representation of an accompanying |
510 * stack trace, or `null` if no stack trace was provided. | 507 * stack trace, or `null` if no stack trace was provided. |
511 * To convert this back to a [StackTrace] object, use [StackTrace.fromString]. | 508 * To convert this back to a [StackTrace] object, use [StackTrace.fromString]. |
(...skipping 41 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
553 */ | 550 */ |
554 Stream get errors { | 551 Stream get errors { |
555 StreamController controller; | 552 StreamController controller; |
556 RawReceivePort port; | 553 RawReceivePort port; |
557 void handleError(message) { | 554 void handleError(message) { |
558 String errorDescription = message[0]; | 555 String errorDescription = message[0]; |
559 String stackDescription = message[1]; | 556 String stackDescription = message[1]; |
560 var error = new RemoteError(errorDescription, stackDescription); | 557 var error = new RemoteError(errorDescription, stackDescription); |
561 controller.addError(error, error.stackTrace); | 558 controller.addError(error, error.stackTrace); |
562 } | 559 } |
| 560 |
563 controller = new StreamController.broadcast( | 561 controller = new StreamController.broadcast( |
564 sync: true, | 562 sync: true, |
565 onListen: () { | 563 onListen: () { |
566 port = new RawReceivePort(handleError); | 564 port = new RawReceivePort(handleError); |
567 this.addErrorListener(port.sendPort); | 565 this.addErrorListener(port.sendPort); |
568 }, | 566 }, |
569 onCancel: () { | 567 onCancel: () { |
570 this.removeErrorListener(port.sendPort); | 568 this.removeErrorListener(port.sendPort); |
571 port.close(); | 569 port.close(); |
572 port = null; | 570 port = null; |
573 }); | 571 }); |
574 return controller.stream; | 572 return controller.stream; |
575 } | 573 } |
576 } | 574 } |
577 | 575 |
578 /** | 576 /** |
579 * Sends messages to its [ReceivePort]s. | 577 * Sends messages to its [ReceivePort]s. |
580 * | 578 * |
581 * [SendPort]s are created from [ReceivePort]s. Any message sent through | 579 * [SendPort]s are created from [ReceivePort]s. Any message sent through |
582 * a [SendPort] is delivered to its corresponding [ReceivePort]. There might be | 580 * a [SendPort] is delivered to its corresponding [ReceivePort]. There might be |
583 * many [SendPort]s for the same [ReceivePort]. | 581 * many [SendPort]s for the same [ReceivePort]. |
584 * | 582 * |
585 * [SendPort]s can be transmitted to other isolates, and they preserve equality | 583 * [SendPort]s can be transmitted to other isolates, and they preserve equality |
586 * when sent. | 584 * when sent. |
587 */ | 585 */ |
588 abstract class SendPort implements Capability { | 586 abstract class SendPort implements Capability { |
589 | |
590 /** | 587 /** |
591 * Sends an asynchronous [message] through this send port, to its | 588 * Sends an asynchronous [message] through this send port, to its |
592 * corresponding `ReceivePort`. | 589 * corresponding `ReceivePort`. |
593 * | 590 * |
594 * The content of [message] can be: primitive values (null, num, bool, double, | 591 * The content of [message] can be: primitive values (null, num, bool, double, |
595 * String), instances of [SendPort], and lists and maps whose elements are any | 592 * String), instances of [SendPort], and lists and maps whose elements are any |
596 * of these. List and maps are also allowed to be cyclic. | 593 * of these. List and maps are also allowed to be cyclic. |
597 * | 594 * |
598 * In the special circumstances when two isolates share the same code and are | 595 * In the special circumstances when two isolates share the same code and are |
599 * running in the same process (e.g. isolates created via [Isolate.spawn]), it | 596 * running in the same process (e.g. isolates created via [Isolate.spawn]), it |
600 * is also possible to send object instances (which would be copied in the | 597 * is also possible to send object instances (which would be copied in the |
601 * process). This is currently only supported by the dartvm. For now, the | 598 * process). This is currently only supported by the dartvm. For now, the |
602 * dart2js compiler only supports the restricted messages described above. | 599 * dart2js compiler only supports the restricted messages described above. |
603 * | 600 * |
604 * The send happens immediately and doesn't block. The corresponding receive | 601 * The send happens immediately and doesn't block. The corresponding receive |
605 * port can receive the message as soon as its isolate's event loop is ready | 602 * port can receive the message as soon as its isolate's event loop is ready |
606 * to deliver it, independently of what the sending isolate is doing. | 603 * to deliver it, independently of what the sending isolate is doing. |
607 */ | 604 */ |
608 void send(var message); | 605 void send(var message); |
609 | 606 |
610 /** | 607 /** |
611 * Tests whether [other] is a [SendPort] pointing to the same | 608 * Tests whether [other] is a [SendPort] pointing to the same |
612 * [ReceivePort] as this one. | 609 * [ReceivePort] as this one. |
613 */ | 610 */ |
614 bool operator==(var other); | 611 bool operator ==(var other); |
615 | 612 |
616 /** | 613 /** |
617 * Returns an immutable hash code for this send port that is | 614 * Returns an immutable hash code for this send port that is |
618 * consistent with the == operator. | 615 * consistent with the == operator. |
619 */ | 616 */ |
620 int get hashCode; | 617 int get hashCode; |
621 } | 618 } |
622 | 619 |
623 /** | 620 /** |
624 * Together with [SendPort], the only means of communication between isolates. | 621 * Together with [SendPort], the only means of communication between isolates. |
625 * | 622 * |
626 * [ReceivePort]s have a `sendPort` getter which returns a [SendPort]. | 623 * [ReceivePort]s have a `sendPort` getter which returns a [SendPort]. |
627 * Any message that is sent through this [SendPort] | 624 * Any message that is sent through this [SendPort] |
628 * is delivered to the [ReceivePort] it has been created from. There, the | 625 * is delivered to the [ReceivePort] it has been created from. There, the |
629 * message is dispatched to the `ReceivePort`'s listener. | 626 * message is dispatched to the `ReceivePort`'s listener. |
630 * | 627 * |
631 * A [ReceivePort] is a non-broadcast stream. This means that it buffers | 628 * A [ReceivePort] is a non-broadcast stream. This means that it buffers |
632 * incoming messages until a listener is registered. Only one listener can | 629 * incoming messages until a listener is registered. Only one listener can |
633 * receive messages. See [Stream.asBroadcastStream] for transforming the port | 630 * receive messages. See [Stream.asBroadcastStream] for transforming the port |
634 * to a broadcast stream. | 631 * to a broadcast stream. |
635 * | 632 * |
636 * A [ReceivePort] may have many [SendPort]s. | 633 * A [ReceivePort] may have many [SendPort]s. |
637 */ | 634 */ |
638 abstract class ReceivePort implements Stream { | 635 abstract class ReceivePort implements Stream { |
639 | |
640 /** | 636 /** |
641 * Opens a long-lived port for receiving messages. | 637 * Opens a long-lived port for receiving messages. |
642 * | 638 * |
643 * A [ReceivePort] is a non-broadcast stream. This means that it buffers | 639 * A [ReceivePort] is a non-broadcast stream. This means that it buffers |
644 * incoming messages until a listener is registered. Only one listener can | 640 * incoming messages until a listener is registered. Only one listener can |
645 * receive messages. See [Stream.asBroadcastStream] for transforming the port | 641 * receive messages. See [Stream.asBroadcastStream] for transforming the port |
646 * to a broadcast stream. | 642 * to a broadcast stream. |
647 * | 643 * |
648 * A receive port is closed by canceling its subscription. | 644 * A receive port is closed by canceling its subscription. |
649 */ | 645 */ |
(...skipping 10 matching lines...) Expand all Loading... |
660 /** | 656 /** |
661 * Inherited from [Stream]. | 657 * Inherited from [Stream]. |
662 * | 658 * |
663 * Note that [onError] and [cancelOnError] are ignored since a ReceivePort | 659 * Note that [onError] and [cancelOnError] are ignored since a ReceivePort |
664 * will never receive an error. | 660 * will never receive an error. |
665 * | 661 * |
666 * The [onDone] handler will be called when the stream closes. | 662 * The [onDone] handler will be called when the stream closes. |
667 * The stream closes when [close] is called. | 663 * The stream closes when [close] is called. |
668 */ | 664 */ |
669 StreamSubscription listen(void onData(var message), | 665 StreamSubscription listen(void onData(var message), |
670 { Function onError, | 666 {Function onError, void onDone(), bool cancelOnError}); |
671 void onDone(), | |
672 bool cancelOnError }); | |
673 | 667 |
674 /** | 668 /** |
675 * Closes `this`. | 669 * Closes `this`. |
676 * | 670 * |
677 * If the stream has not been canceled yet, adds a close-event to the event | 671 * If the stream has not been canceled yet, adds a close-event to the event |
678 * queue and discards any further incoming messages. | 672 * queue and discards any further incoming messages. |
679 * | 673 * |
680 * If the stream has already been canceled this method has no effect. | 674 * If the stream has already been canceled this method has no effect. |
681 */ | 675 */ |
682 void close(); | 676 void close(); |
(...skipping 41 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
724 * as the original error, but has no other features of the original error. | 718 * as the original error, but has no other features of the original error. |
725 */ | 719 */ |
726 class RemoteError implements Error { | 720 class RemoteError implements Error { |
727 final String _description; | 721 final String _description; |
728 final StackTrace stackTrace; | 722 final StackTrace stackTrace; |
729 RemoteError(String description, String stackDescription) | 723 RemoteError(String description, String stackDescription) |
730 : _description = description, | 724 : _description = description, |
731 stackTrace = new StackTrace.fromString(stackDescription); | 725 stackTrace = new StackTrace.fromString(stackDescription); |
732 String toString() => _description; | 726 String toString() => _description; |
733 } | 727 } |
OLD | NEW |