| 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 191 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 202 external static Future<Isolate> spawnUri( | 202 external static Future<Isolate> spawnUri( |
| 203 Uri uri, | 203 Uri uri, |
| 204 List<String> args, | 204 List<String> args, |
| 205 var message, | 205 var message, |
| 206 {bool paused: false, | 206 {bool paused: false, |
| 207 Uri packageRoot}); | 207 Uri packageRoot}); |
| 208 | 208 |
| 209 /** | 209 /** |
| 210 * Requests the isolate to pause. | 210 * Requests the isolate to pause. |
| 211 * | 211 * |
| 212 * WARNING: This method is experimental and not handled on every platform yet. | |
| 213 * | |
| 214 * The isolate should stop handling events by pausing its event queue. | 212 * The isolate should stop handling events by pausing its event queue. |
| 215 * The request will eventually make the isolate stop doing anything. | 213 * The request will eventually make the isolate stop doing anything. |
| 216 * It will be handled before any other messages that are later sent to the | 214 * It will be handled before any other messages that are later sent to the |
| 217 * isolate from the current isolate, but no other guarantees are provided. | 215 * isolate from the current isolate, but no other guarantees are provided. |
| 218 * | 216 * |
| 219 * The event loop may be paused before previously sent, but not yet exeuted, | 217 * The event loop may be paused before previously sent, but not yet exeuted, |
| 220 * messages have been reached. | 218 * messages have been reached. |
| 221 * | 219 * |
| 222 * If [resumeCapability] is provided, it is used to identity the pause, | 220 * If [resumeCapability] is provided, it is used to identity the pause, |
| 223 * and must be used again to end the pause using [resume]. | 221 * and must be used again to end the pause using [resume]. |
| (...skipping 12 matching lines...) Expand all Loading... |
| 236 _pause(resumeCapability); | 234 _pause(resumeCapability); |
| 237 return resumeCapability; | 235 return resumeCapability; |
| 238 } | 236 } |
| 239 | 237 |
| 240 /** Internal implementation of [pause]. */ | 238 /** Internal implementation of [pause]. */ |
| 241 external void _pause(Capability resumeCapability); | 239 external void _pause(Capability resumeCapability); |
| 242 | 240 |
| 243 /** | 241 /** |
| 244 * Resumes a paused isolate. | 242 * Resumes a paused isolate. |
| 245 * | 243 * |
| 246 * WARNING: This method is experimental and not handled on every platform yet. | |
| 247 * | |
| 248 * Sends a message to an isolate requesting that it ends a pause | 244 * Sends a message to an isolate requesting that it ends a pause |
| 249 * that was requested using the [resumeCapability]. | 245 * that was requested using the [resumeCapability]. |
| 250 * | 246 * |
| 251 * When all active pause requests have been cancelled, the isolate | 247 * When all active pause requests have been cancelled, the isolate |
| 252 * will continue handling normal messages. | 248 * will continue handling normal messages. |
| 253 * | 249 * |
| 254 * The capability must be one returned by a call to [pause] on this | 250 * The capability must be one returned by a call to [pause] on this |
| 255 * isolate, otherwise the resume call does nothing. | 251 * isolate, otherwise the resume call does nothing. |
| 256 */ | 252 */ |
| 257 external void resume(Capability resumeCapability); | 253 external void resume(Capability resumeCapability); |
| 258 | 254 |
| 259 /** | 255 /** |
| 260 * Asks the isolate to send [response] on [responsePort] when it terminates. | 256 * Asks the isolate to send [response] on [responsePort] when it terminates. |
| 261 * | 257 * |
| 262 * WARNING: This method is experimental and not handled on every platform yet. | |
| 263 * | |
| 264 * The isolate will send a `response` message on `responsePort` as the last | 258 * The isolate will send a `response` message on `responsePort` as the last |
| 265 * thing before it terminates. It will run no further code after the message | 259 * thing before it terminates. It will run no further code after the message |
| 266 * has been sent. | 260 * has been sent. |
| 267 * | 261 * |
| 268 * Adding the same port more than once will only cause it to receive one | 262 * Adding the same port more than once will only cause it to receive one |
| 269 * message, using the last response value that was added. | 263 * message, using the last response value that was added. |
| 270 * | 264 * |
| 271 * If the isolate is already dead, no message will be sent. | 265 * If the isolate is already dead, no message will be sent. |
| 272 * If `response` cannot be sent to the isolate, then the request is ignored. | 266 * If `response` cannot be sent to the isolate, then the request is ignored. |
| 273 * It is recommended to only use simple values that can be sent to all | 267 * It is recommended to only use simple values that can be sent to all |
| 274 * isolates, like `null`, booleans, numbers or strings. | 268 * isolates, like `null`, booleans, numbers or strings. |
| 275 */ | 269 */ |
| 276 /* TODO(lrn): Can we do better? Can the system recognize this message and | 270 /* TODO(lrn): Can we do better? Can the system recognize this message and |
| 277 * send a reply if the receiving isolate is dead? | 271 * send a reply if the receiving isolate is dead? |
| 278 */ | 272 */ |
| 279 external void addOnExitListener(SendPort responsePort, {Object response}); | 273 external void addOnExitListener(SendPort responsePort, {Object response}); |
| 280 | 274 |
| 281 /** | 275 /** |
| 282 * Stop listening on exit messages from the isolate. | 276 * Stop listening on exit messages from the isolate. |
| 283 * | 277 * |
| 284 * WARNING: This method is experimental and not handled on every platform yet. | |
| 285 * | |
| 286 * If a call has previously been made to [addOnExitListener] with the same | 278 * If a call has previously been made to [addOnExitListener] with the same |
| 287 * send-port, this will unregister the port, and it will no longer receive | 279 * send-port, this will unregister the port, and it will no longer receive |
| 288 * a message when the isolate terminates. | 280 * a message when the isolate terminates. |
| 289 * A response may still be sent until this operation is fully processed by | 281 * A response may still be sent until this operation is fully processed by |
| 290 * the isolate. | 282 * the isolate. |
| 291 */ | 283 */ |
| 292 external void removeOnExitListener(SendPort responsePort); | 284 external void removeOnExitListener(SendPort responsePort); |
| 293 | 285 |
| 294 /** | 286 /** |
| 295 * Set whether uncaught errors will terminate the isolate. | 287 * Set whether uncaught errors will terminate the isolate. |
| 296 * | 288 * |
| 297 * WARNING: This method is experimental and not handled on every platform yet. | |
| 298 * | |
| 299 * If errors are fatal, any uncaught error will terminate the isolate | 289 * If errors are fatal, any uncaught error will terminate the isolate |
| 300 * event loop and shut down the isolate. | 290 * event loop and shut down the isolate. |
| 301 * | 291 * |
| 302 * This call requires the [terminateCapability] for the isolate. | 292 * This call requires the [terminateCapability] for the isolate. |
| 303 * If the capability is not correct, no change is made. | 293 * If the capability is not correct, no change is made. |
| 304 */ | 294 */ |
| 305 external void setErrorsFatal(bool errorsAreFatal); | 295 external void setErrorsFatal(bool errorsAreFatal); |
| 306 | 296 |
| 307 /** | 297 /** |
| 308 * Requests the isolate to shut down. | 298 * Requests the isolate to shut down. |
| 309 * | 299 * |
| 310 * WARNING: This method is experimental and not handled on every platform yet. | |
| 311 * | |
| 312 * The isolate is requested to terminate itself. | 300 * The isolate is requested to terminate itself. |
| 313 * The [priority] argument specifies when this must happen. | 301 * The [priority] argument specifies when this must happen. |
| 314 * | 302 * |
| 315 * The [priority] must be one of [IMMEDIATE] or [BEFORE_NEXT_EVENT]. | 303 * The [priority] must be one of [IMMEDIATE] or [BEFORE_NEXT_EVENT]. |
| 316 * The shutdown is performed at different times depending on the priority: | 304 * The shutdown is performed at different times depending on the priority: |
| 317 * | 305 * |
| 318 * * `IMMEDIATE`: The the isolate shuts down as soon as possible. | 306 * * `IMMEDIATE`: The the isolate shuts down as soon as possible. |
| 319 * Control messages are handled in order, so all previously sent control | 307 * Control messages are handled in order, so all previously sent control |
| 320 * events from this isolate will all have been processed. | 308 * events from this isolate will all have been processed. |
| 321 * The shutdown should happen no later than if sent with | 309 * The shutdown should happen no later than if sent with |
| 322 * `BEFORE_NEXT_EVENT`. | 310 * `BEFORE_NEXT_EVENT`. |
| 323 * It may happen earlier if the system has a way to shut down cleanly | 311 * It may happen earlier if the system has a way to shut down cleanly |
| 324 * at an earlier time, even during the execution of another event. | 312 * at an earlier time, even during the execution of another event. |
| 325 * * `BEFORE_NEXT_EVENT`: The shutdown is scheduled for the next time | 313 * * `BEFORE_NEXT_EVENT`: The shutdown is scheduled for the next time |
| 326 * control returns to the event loop of the receiving isolate, | 314 * control returns to the event loop of the receiving isolate, |
| 327 * after the current event, and any already scheduled control events, | 315 * after the current event, and any already scheduled control events, |
| 328 * are completed. | 316 * are completed. |
| 329 */ | 317 */ |
| 330 external void kill({int priority: BEFORE_NEXT_EVENT}); | 318 external void kill({int priority: BEFORE_NEXT_EVENT}); |
| 331 | 319 |
| 332 /** | 320 /** |
| 333 * Request that the isolate send [response] on the [responsePort]. | 321 * Request that the isolate send [response] on the [responsePort]. |
| 334 * | 322 * |
| 335 * WARNING: This method is experimental and not handled on every platform yet. | |
| 336 * | |
| 337 * If the isolate is alive, it will eventually send `response` | 323 * If the isolate is alive, it will eventually send `response` |
| 338 * (defaulting to `null`) on the response port. | 324 * (defaulting to `null`) on the response port. |
| 339 * | 325 * |
| 340 * The [priority] must be one of [IMMEDIATE] or [BEFORE_NEXT_EVENT]. | 326 * The [priority] must be one of [IMMEDIATE] or [BEFORE_NEXT_EVENT]. |
| 341 * The response is sent at different times depending on the ping type: | 327 * The response is sent at different times depending on the ping type: |
| 342 * | 328 * |
| 343 * * `IMMEDIATE`: The the isolate responds as soon as it receives the | 329 * * `IMMEDIATE`: The the isolate responds as soon as it receives the |
| 344 * control message. This is after any previous control message | 330 * control message. This is after any previous control message |
| 345 * from the same isolate has been received, but may be during | 331 * from the same isolate has been received, but may be during |
| 346 * execution of another event. | 332 * execution of another event. |
| 347 * * `BEFORE_NEXT_EVENT`: The response is scheduled for the next time | 333 * * `BEFORE_NEXT_EVENT`: The response is scheduled for the next time |
| 348 * control returns to the event loop of the receiving isolate, | 334 * control returns to the event loop of the receiving isolate, |
| 349 * after the current event, and any already scheduled control events, | 335 * after the current event, and any already scheduled control events, |
| 350 * are completed. | 336 * are completed. |
| 351 * | 337 * |
| 352 * If `response` cannot be sent to the isolate, then the request is ignored. | 338 * If `response` cannot be sent to the isolate, then the request is ignored. |
| 353 * It is recommended to only use simple values that can be sent to all | 339 * It is recommended to only use simple values that can be sent to all |
| 354 * isolates, like `null`, booleans, numbers or strings. | 340 * isolates, like `null`, booleans, numbers or strings. |
| 355 */ | 341 */ |
| 356 external void ping(SendPort responsePort, {Object response, | 342 external void ping(SendPort responsePort, {Object response, |
| 357 int priority: IMMEDIATE}); | 343 int priority: IMMEDIATE}); |
| 358 | 344 |
| 359 /** | 345 /** |
| 360 * Requests that uncaught errors of the isolate are sent back to [port]. | 346 * Requests that uncaught errors of the isolate are sent back to [port]. |
| 361 * | 347 * |
| 362 * WARNING: This method is experimental and not handled on every platform yet. | |
| 363 * | |
| 364 * The errors are sent back as two elements lists. | 348 * The errors are sent back as two elements lists. |
| 365 * The first element is a `String` representation of the error, usually | 349 * The first element is a `String` representation of the error, usually |
| 366 * created by calling `toString` on the error. | 350 * created by calling `toString` on the error. |
| 367 * The second element is a `String` representation of an accompanying | 351 * The second element is a `String` representation of an accompanying |
| 368 * stack trace, or `null` if no stack trace was provided. | 352 * stack trace, or `null` if no stack trace was provided. |
| 369 * To convert this back to a [StackTrace] object, use [StackTrace.fromString]. | 353 * To convert this back to a [StackTrace] object, use [StackTrace.fromString]. |
| 370 * | 354 * |
| 371 * Listening using the same port more than once does nothing. It will only | 355 * Listening using the same port more than once does nothing. It will only |
| 372 * get each error once. | 356 * get each error once. |
| 373 */ | 357 */ |
| 374 external void addErrorListener(SendPort port); | 358 external void addErrorListener(SendPort port); |
| 375 | 359 |
| 376 /** | 360 /** |
| 377 * Stop listening for uncaught errors through [port]. | 361 * Stop listening for uncaught errors through [port]. |
| 378 * | 362 * |
| 379 * WARNING: This method is experimental and not handled on every platform yet. | |
| 380 * | |
| 381 * The `port` should be a port that is listening for errors through | 363 * The `port` should be a port that is listening for errors through |
| 382 * [addErrorListener]. This call requests that the isolate stops sending | 364 * [addErrorListener]. This call requests that the isolate stops sending |
| 383 * errors on the port. | 365 * errors on the port. |
| 384 * | 366 * |
| 385 * If the same port has been passed via `addErrorListener` more than once, | 367 * If the same port has been passed via `addErrorListener` more than once, |
| 386 * only one call to `removeErrorListener` is needed to stop it from receiving | 368 * only one call to `removeErrorListener` is needed to stop it from receiving |
| 387 * errors. | 369 * errors. |
| 388 * | 370 * |
| 389 * Closing the receive port at the end of the send port will not stop the | 371 * Closing the receive port at the end of the send port will not stop the |
| 390 * isolate from sending errors, they are just going to be lost. | 372 * isolate from sending errors, they are just going to be lost. |
| (...skipping 207 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 598 * as the original error, but has no other features of the original error. | 580 * as the original error, but has no other features of the original error. |
| 599 */ | 581 */ |
| 600 class RemoteError implements Error { | 582 class RemoteError implements Error { |
| 601 final String _description; | 583 final String _description; |
| 602 final StackTrace stackTrace; | 584 final StackTrace stackTrace; |
| 603 RemoteError(String description, String stackDescription) | 585 RemoteError(String description, String stackDescription) |
| 604 : _description = description, | 586 : _description = description, |
| 605 stackTrace = new StackTrace.fromString(stackDescription); | 587 stackTrace = new StackTrace.fromString(stackDescription); |
| 606 String toString() => _description; | 588 String toString() => _description; |
| 607 } | 589 } |
| OLD | NEW |