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 library dart.isolate; | 5 library dart.isolate; |
6 | 6 |
7 import "dart:async"; | 7 import "dart:async"; |
8 | 8 |
9 part "isolate_stream.dart"; | 9 /** |
10 * Returns the initial message an isolate received. | |
11 * | |
12 * If the isolate is the main-isolate it contains the list of arguments that | |
13 * have been given on the command line. | |
14 * | |
15 * This getter supercedes io:Options (which is now deprecated). | |
16 */ | |
17 // TODO(floitsch): alternatively we could keep io:Options (or a nicer variant | |
18 // of it). The main advantage of removing it, is that libraries/programs that | |
19 // are otherwise server-independent could be spawned in the browser. | |
20 // If devs use dart:io just for the arguments they can't be used in spawnUri, | |
21 // by forcing them to use dart:isolate they would run in the browser, too. | |
22 dynamic get isolateArguments; | |
Søren Gjesse
2013/07/26 11:49:35
The name of this should be in the plural form. How
floitsch
2013/07/26 12:01:28
Done.
| |
10 | 23 |
11 class IsolateSpawnException implements Exception { | 24 class IsolateSpawnException implements Exception { |
12 const IsolateSpawnException(String this._s); | 25 const IsolateSpawnException(String this._s); |
13 String toString() => "IsolateSpawnException: '$_s'"; | 26 String toString() => "IsolateSpawnException: '$_s'"; |
14 final String _s; | 27 final String _s; |
15 } | 28 } |
16 | 29 |
17 /** | 30 /** |
Søren Gjesse
2013/07/26 11:49:35
Please remove or rewrite the old parts of the dart
floitsch
2013/07/26 12:01:28
Done.
| |
18 * The initial [ReceivePort] available by default for this isolate. This | |
19 * [ReceivePort] is created automatically and it is commonly used to establish | |
20 * the first communication between isolates (see [spawnFunction] and | |
21 * [spawnUri]). | |
22 */ | |
23 ReceivePort get port => _Isolate.port; | |
24 | |
25 /** | |
26 * Creates and spawns an isolate that shares the same code as the current | 31 * Creates and spawns an isolate that shares the same code as the current |
27 * isolate, but that starts from [topLevelFunction]. The [topLevelFunction] | 32 * isolate, but that starts from [topLevelFunction]. The [topLevelFunction] |
28 * argument must be a static top-level function or a static method that takes no | 33 * argument must be a static top-level function or a static method that takes no |
29 * arguments. It is illegal to pass a function closure. | 34 * arguments. It is illegal to pass a function closure. |
30 * | 35 * |
31 * When any isolate starts (even the main script of the application), a default | 36 * When any isolate starts (even the main script of the application), a default |
32 * [ReceivePort] is created for it. This port is available from the top-level | 37 * [ReceivePort] is created for it. This port is available from the top-level |
33 * getter [port] defined in this library. | 38 * getter [port] defined in this library. |
34 * | 39 * |
35 * [spawnFunction] returns a [SendPort] derived from the child isolate's default | 40 * Usually the initial [message] contains a [SendPort] so that the spawner and |
36 * port. | 41 * spawnee can communicate with each other. |
37 * | |
38 * The optional [unhandledExceptionCallback] argument is invoked whenever an | |
39 * exception inside the isolate is unhandled. It can be seen as a big | |
40 * `try/catch` around everything that is executed inside the isolate. The | |
41 * callback should return `true` when it was able to handled the exception. | |
42 */ | 42 */ |
43 SendPort spawnFunction(void topLevelFunction(), | 43 void spawnFunction(void topLevelFunction(), [dynamic message]); |
Søren Gjesse
2013/07/26 11:49:35
Don't you want the topLevelFunction to take one ar
floitsch
2013/07/26 12:01:28
Sounds interesting. Would you still set the `isola
| |
44 [bool unhandledExceptionCallback(IsolateUnhandledException e)]) | |
45 => _Isolate.spawnFunction(topLevelFunction, unhandledExceptionCallback); | |
46 | 44 |
47 /** | 45 /** |
Søren Gjesse
2013/07/26 11:49:35
Ditto.
floitsch
2013/07/26 12:01:28
Done.
| |
48 * Creates and spawns an isolate whose code is available at [uri]. Like with | 46 * Creates and spawns an isolate whose code is available at [uri]. Like with |
49 * [spawnFunction], the child isolate will have a default [ReceivePort], and a | 47 * [spawnFunction], the child isolate will have a default [ReceivePort], and a |
50 * this function returns a [SendPort] derived from it. | 48 * this function returns a [SendPort] derived from it. |
51 */ | 49 */ |
52 SendPort spawnUri(String uri) => _Isolate.spawnUri(uri); | 50 void spawnUri(Uri uri, [dynamic message]); |
53 | 51 |
54 /** | 52 /** |
55 * [SendPort]s are created from [ReceivePort]s. Any message sent through | 53 * [SendPort]s are created from [ReceivePort]s. Any message sent through |
56 * a [SendPort] is delivered to its respective [ReceivePort]. There might be | 54 * a [SendPort] is delivered to its respective [ReceivePort]. There might be |
57 * many [SendPort]s for the same [ReceivePort]. | 55 * many [SendPort]s for the same [ReceivePort]. |
58 * | 56 * |
59 * [SendPort]s can be transmitted to other isolates. | 57 * [SendPort]s can be transmitted to other isolates. |
60 */ | 58 */ |
61 abstract class SendPort { | 59 abstract class SendPort { |
62 | 60 |
63 /** | 61 /** |
64 * Sends an asynchronous [message] to this send port. The message is copied to | 62 * Sends an asynchronous [message] to this send port. The message is copied to |
65 * the receiving isolate. If specified, the [replyTo] port will be provided to | 63 * the receiving isolate. If specified, the [replyTo] port will be provided to |
66 * the receiver to facilitate exchanging sequences of messages. | 64 * the receiver to facilitate exchanging sequences of messages. |
67 * | 65 * |
68 * The content of [message] can be: primitive values (null, num, bool, double, | 66 * The content of [message] can be: primitive values (null, num, bool, double, |
69 * String), instances of [SendPort], and lists and maps whose elements are any | 67 * String), instances of [SendPort], and lists and maps whose elements are any |
70 * of these. List and maps are also allowed to be cyclic. | 68 * of these. List and maps are also allowed to be cyclic. |
71 * | 69 * |
70 * If, during serialization, an object of different type is encountered, the | |
71 * serializer (if given) is invoked. TODO(floitsch): specify how | |
72 * serialization and deserialization should work. | |
Søren Gjesse
2013/07/26 11:49:35
Should it be possible to override the built-in ser
floitsch
2013/07/26 12:01:28
Not sure. Could be an option, but it sounds danger
Lasse Reichstein Nielsen
2013/08/12 07:19:03
You can't override the serialization and deseriali
| |
73 * | |
72 * In the special circumstances when two isolates share the same code and are | 74 * In the special circumstances when two isolates share the same code and are |
73 * running in the same process (e.g. isolates created via [spawnFunction]), it | 75 * running in the same process (e.g. isolates created via [spawnFunction]), it |
74 * is also possible to send object instances (which would be copied in the | 76 * is also possible to send object instances (which would be copied in the |
75 * process). This is currently only supported by the dartvm. For now, the | 77 * process). This is currently only supported by the dartvm. For now, the |
76 * dart2js compiler only supports the restricted messages described above. | 78 * dart2js compiler only supports the restricted messages described above. |
77 * | 79 * |
78 * Deprecation note: it is no longer valid to transmit a [ReceivePort] in a | 80 * Deprecation note: it is no longer valid to transmit a [ReceivePort] in a |
79 * message. Previously they were translated to the corresponding send port | 81 * message. Previously they were translated to the corresponding send port |
80 * before being transmitted. | 82 * before being transmitted. |
81 */ | 83 */ |
82 void send(var message, [SendPort replyTo]); | 84 void send(var message, { serializer(x), SendPort replyTo }); |
Søren Gjesse
2013/07/26 11:49:35
Serializer and deserializer come i pairs. It could
floitsch
2013/07/26 12:01:28
I like this, but the problem is that you don't kno
| |
83 | 85 |
84 /** | 86 /** |
85 * Sends a message to this send port and returns a [Future] of the reply. | 87 * Sends a message to this send port and returns a [Future] of the reply. |
86 * Basically, this internally creates a new receive port, sends a | 88 * Basically, this internally creates a new receive port, sends a |
87 * message to this send port with replyTo set to such receive port, and, when | 89 * message to this send port with replyTo set to such receive port, and, when |
88 * a reply is received, it closes the receive port and completes the returned | 90 * a reply is received, it closes the receive port and completes the returned |
89 * future. | 91 * future. |
92 * | |
93 * Note: it is not possible to provide a serializer to this function. Use | |
94 * [send] instead. | |
90 */ | 95 */ |
91 Future call(var message); | 96 Future call(var message); |
92 | 97 |
93 /** | 98 /** |
94 * Tests whether [other] is a [SendPort] pointing to the same | 99 * Tests whether [other] is a [SendPort] pointing to the same |
95 * [ReceivePort] as this one. | 100 * [ReceivePort] as this one. |
96 */ | 101 */ |
97 bool operator==(var other); | 102 bool operator==(var other); |
98 | 103 |
99 /** | 104 /** |
(...skipping 11 matching lines...) Expand all Loading... | |
111 * is delivered to the [ReceivePort] it has been created from. There, they are | 116 * is delivered to the [ReceivePort] it has been created from. There, they are |
112 * dispatched to the callback that has been registered on the receive port. | 117 * dispatched to the callback that has been registered on the receive port. |
113 * | 118 * |
114 * A [ReceivePort] may have many [SendPort]s. | 119 * A [ReceivePort] may have many [SendPort]s. |
115 */ | 120 */ |
116 abstract class ReceivePort { | 121 abstract class ReceivePort { |
117 | 122 |
118 /** | 123 /** |
119 * Opens a long-lived port for receiving messages. The returned port | 124 * Opens a long-lived port for receiving messages. The returned port |
120 * must be explicitly closed through [ReceivePort.close]. | 125 * must be explicitly closed through [ReceivePort.close]. |
126 * | |
127 * If a message was serialized during sending the deserializer is invoked | |
128 * when receiving data. | |
121 */ | 129 */ |
122 external factory ReceivePort(); | 130 external factory ReceivePort({ deserializer(x) }); |
123 | 131 |
124 /** | 132 /** |
125 * Sets up a callback function for receiving pending or future | 133 * Sets up a callback function for receiving pending or future |
126 * messages on this receive port. | 134 * messages on this receive port. |
127 */ | 135 */ |
128 void receive(void callback(var message, SendPort replyTo)); | 136 void onData(void callback(var message, SendPort replyTo)); |
129 | 137 |
130 /** | 138 /** |
131 * Closes this receive port immediately. Pending messages will not | 139 * Closes this receive port immediately. Pending messages will not |
132 * be processed and it is impossible to re-open the port. Single-shot | 140 * be processed and it is impossible to re-open the port. Single-shot |
133 * reply ports, such as those created through [SendPort.call], are | 141 * reply ports, such as those created through [SendPort.call], are |
134 * automatically closed when the reply has been received. Multiple | 142 * automatically closed when the reply has been received. Multiple |
135 * invocations of [close] are allowed but ignored. | 143 * invocations of [close] are allowed but ignored. |
136 */ | 144 */ |
137 void close(); | 145 void close(); |
138 | 146 |
(...skipping 59 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
198 const IsolateUnhandledException(this.message, this.source, this.stackTrace); | 206 const IsolateUnhandledException(this.message, this.source, this.stackTrace); |
199 | 207 |
200 String toString() { | 208 String toString() { |
201 return 'IsolateUnhandledException: exception while handling message: ' | 209 return 'IsolateUnhandledException: exception while handling message: ' |
202 '${message} \n ' | 210 '${message} \n ' |
203 '${source.toString().replaceAll("\n", "\n ")}\n' | 211 '${source.toString().replaceAll("\n", "\n ")}\n' |
204 'original stack trace:\n ' | 212 'original stack trace:\n ' |
205 '${stackTrace.toString().replaceAll("\n","\n ")}'; | 213 '${stackTrace.toString().replaceAll("\n","\n ")}'; |
206 } | 214 } |
207 } | 215 } |
OLD | NEW |