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