| 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 |