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 isolateMessage; | |
Lasse Reichstein Nielsen
2013/08/26 08:06:06
Another global variable.
Can we please just pass
| |
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 /** |
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 * The initial [message] is stored in the global [isolateMessage] where the |
32 * [ReceivePort] is created for it. This port is available from the top-level | 37 * spawnee can access it. Usually the initial [message] contains a [SendPort] so |
33 * getter [port] defined in this library. | 38 * that the spawner and spawnee can communicate with each other. |
34 * | |
35 * [spawnFunction] returns a [SendPort] derived from the child isolate's default | |
36 * port. | |
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 */ | 39 */ |
43 SendPort spawnFunction(void topLevelFunction(), | 40 void spawnFunction(void topLevelFunction(), [dynamic message]); |
44 [bool unhandledExceptionCallback(IsolateUnhandledException e)]) | |
45 => _Isolate.spawnFunction(topLevelFunction, unhandledExceptionCallback); | |
46 | 41 |
47 /** | 42 /** |
48 * Creates and spawns an isolate whose code is available at [uri]. Like with | 43 * Creates and spawns an isolate whose code is available at [uri]. |
49 * [spawnFunction], the child isolate will have a default [ReceivePort], and a | 44 * |
50 * this function returns a [SendPort] derived from it. | 45 * Otherwise similar to [spawnFunction]. |
51 */ | 46 */ |
52 SendPort spawnUri(String uri) => _Isolate.spawnUri(uri); | 47 void spawnUri(Uri uri, [dynamic message]); |
Lasse Reichstein Nielsen
2013/08/26 08:06:06
Make it possible for this call to pass at least
-
| |
53 | 48 |
54 /** | 49 /** |
55 * [SendPort]s are created from [ReceivePort]s. Any message sent through | 50 * [SendPort]s are created from [ReceivePort]s. Any message sent through |
56 * a [SendPort] is delivered to its respective [ReceivePort]. There might be | 51 * a [SendPort] is delivered to its respective [ReceivePort]. There might be |
57 * many [SendPort]s for the same [ReceivePort]. | 52 * many [SendPort]s for the same [ReceivePort]. |
58 * | 53 * |
59 * [SendPort]s can be transmitted to other isolates. | 54 * [SendPort]s can be transmitted to other isolates. |
60 */ | 55 */ |
61 abstract class SendPort { | 56 abstract class SendPort { |
62 | 57 |
63 /** | 58 /** |
64 * Sends an asynchronous [message] to this send port. The message is copied to | 59 * 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 | 60 * the receiving isolate. If specified, the [replyTo] port will be provided to |
66 * the receiver to facilitate exchanging sequences of messages. | 61 * the receiver to facilitate exchanging sequences of messages. |
67 * | 62 * |
68 * The content of [message] can be: primitive values (null, num, bool, double, | 63 * 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 | 64 * String), instances of [SendPort], and lists and maps whose elements are any |
70 * of these. List and maps are also allowed to be cyclic. | 65 * of these. List and maps are also allowed to be cyclic. |
71 * | 66 * |
67 * If, during serialization, an object of different type (then the primitive | |
68 * values mentioned above) is encountered, the | |
69 * serializer (if given) is invoked. TODO(floitsch): specify how | |
70 * serialization and deserialization should work. | |
71 * | |
72 * In the special circumstances when two isolates share the same code and are | 72 * 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 | 73 * 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 | 74 * 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 | 75 * process). This is currently only supported by the dartvm. For now, the |
76 * dart2js compiler only supports the restricted messages described above. | 76 * dart2js compiler only supports the restricted messages described above. |
77 * | 77 * |
78 * Deprecation note: it is no longer valid to transmit a [ReceivePort] in a | 78 * Deprecation note: it is no longer valid to transmit a [ReceivePort] in a |
79 * message. Previously they were translated to the corresponding send port | 79 * message. Previously they were translated to the corresponding send port |
80 * before being transmitted. | 80 * before being transmitted. |
81 */ | 81 */ |
82 void send(var message, [SendPort replyTo]); | 82 // We could allow a named deserializer argument which must be a global |
83 // function (just like for spawnFunction) and could be transmitted (again, | |
84 // like for spawnFunction). This way the receiver wouldn't need to know | |
85 // how to deserialize. | |
86 // void send(var message, { serializer(x), deserializer(x), SendPort replyTo } ); | |
87 void send(var message, { serializer(x), SendPort replyTo }); | |
83 | 88 |
84 /** | 89 /** |
85 * Sends a message to this send port and returns a [Future] of the reply. | 90 * 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 | 91 * 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 | 92 * 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 | 93 * a reply is received, it closes the receive port and completes the returned |
89 * future. | 94 * future. |
95 * | |
96 * Note: it is not possible to provide a serializer to this function. Use | |
97 * [send] instead. | |
90 */ | 98 */ |
91 Future call(var message); | 99 Future call(var message); |
92 | 100 |
93 /** | 101 /** |
94 * Tests whether [other] is a [SendPort] pointing to the same | 102 * Tests whether [other] is a [SendPort] pointing to the same |
95 * [ReceivePort] as this one. | 103 * [ReceivePort] as this one. |
96 */ | 104 */ |
97 bool operator==(var other); | 105 bool operator==(var other); |
98 | 106 |
99 /** | 107 /** |
(...skipping 11 matching lines...) Expand all Loading... | |
111 * is delivered to the [ReceivePort] it has been created from. There, they are | 119 * 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. | 120 * dispatched to the callback that has been registered on the receive port. |
113 * | 121 * |
114 * A [ReceivePort] may have many [SendPort]s. | 122 * A [ReceivePort] may have many [SendPort]s. |
115 */ | 123 */ |
116 abstract class ReceivePort { | 124 abstract class ReceivePort { |
117 | 125 |
118 /** | 126 /** |
119 * Opens a long-lived port for receiving messages. The returned port | 127 * Opens a long-lived port for receiving messages. The returned port |
120 * must be explicitly closed through [ReceivePort.close]. | 128 * must be explicitly closed through [ReceivePort.close]. |
129 * | |
130 * If a message was serialized during sending the deserializer is invoked | |
131 * when receiving data. | |
121 */ | 132 */ |
122 external factory ReceivePort(); | 133 external factory ReceivePort({ deserializer(x) }); |
123 | 134 |
124 /** | 135 /** |
125 * Sets up a callback function for receiving pending or future | 136 * Sets up a callback function for receiving pending or future |
126 * messages on this receive port. | 137 * messages on this receive port. |
127 */ | 138 */ |
128 void receive(void callback(var message, SendPort replyTo)); | 139 void onData(void callback(var message, SendPort replyTo)); |
129 | 140 |
130 /** | 141 /** |
131 * Closes this receive port immediately. Pending messages will not | 142 * Closes this receive port immediately. Pending messages will not |
132 * be processed and it is impossible to re-open the port. Single-shot | 143 * be processed and it is impossible to re-open the port. Single-shot |
133 * reply ports, such as those created through [SendPort.call], are | 144 * reply ports, such as those created through [SendPort.call], are |
134 * automatically closed when the reply has been received. Multiple | 145 * automatically closed when the reply has been received. Multiple |
135 * invocations of [close] are allowed but ignored. | 146 * invocations of [close] are allowed but ignored. |
136 */ | 147 */ |
137 void close(); | 148 void close(); |
138 | 149 |
(...skipping 59 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
198 const IsolateUnhandledException(this.message, this.source, this.stackTrace); | 209 const IsolateUnhandledException(this.message, this.source, this.stackTrace); |
199 | 210 |
200 String toString() { | 211 String toString() { |
201 return 'IsolateUnhandledException: exception while handling message: ' | 212 return 'IsolateUnhandledException: exception while handling message: ' |
202 '${message} \n ' | 213 '${message} \n ' |
203 '${source.toString().replaceAll("\n", "\n ")}\n' | 214 '${source.toString().replaceAll("\n", "\n ")}\n' |
204 'original stack trace:\n ' | 215 'original stack trace:\n ' |
205 '${stackTrace.toString().replaceAll("\n","\n ")}'; | 216 '${stackTrace.toString().replaceAll("\n","\n ")}'; |
206 } | 217 } |
207 } | 218 } |
OLD | NEW |