languages/dart-sdk
languages/dart-sdk
1
0
Fork 0
mirror of https://github.com/dart-lang/sdk synced 2024-09-15 21:30:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

Address shortcomings in documentation on Isolate class.

Browse source 
Addresses issued #26597 and #26627.

BUG= http://dartbug.com/26597 http://dartbug.com/26627
R=eernst@google.com, floitsch@google.com

Review URL: https://codereview.chromium.org/2062683002 .
This commit is contained in:
Lasse R.H. Nielsen 2016-09-28 10:42:06 +02:00
parent debbf68223
commit 9487e107bb
1 changed files with 38 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

62
sdk/lib/isolate/isolate.dart
View file

@ -7,9 +7,9 @@
* independent workers that are similar to threads
* but don't share memory,
* communicating only via messages.
*
*
* To use this library in your code:
*
*
* import 'dart:isolate';
*/
library dart.isolate;
@ -162,19 +162,27 @@ class Isolate {
* Creates and spawns an isolate that shares the same code as the current
* isolate.
*
* The argument [entryPoint] specifies the entry point of the spawned
* isolate. It must be a top-level function or a static method that
* takes one argument - that is, one-parameter functions that can be
* compile-time constant function values.
* It is not allowed to pass the value of function expressions or an instance
* method extracted from an object.
* The argument [entryPoint] specifies the initial function to call
* in the spawned isolate.
* The entry-point function is invoked in the new isolate with [message]
* as the only argument.
*
* The function must be a top-level function or a static method
* that can be called with a single argument,
* that is, a compile-time constant function value
* which accepts at least one positional parameter
* and has at most one required positional parameter.
* The function may accept any number of optional parameters,
* as long as it *can* be called with just a single argument.
* The function must not be the value of a function expression
* or an instance method tear-off.
*
* The entry-point function is invoked with the initial [message].
* Usually the initial [message] contains a [SendPort] so
* that the spawner and spawnee can communicate with each other.
*
* If the [paused] parameter is set to `true`,
* the isolate will start up in a paused state,
* just before calling the [entryPoint] function with the [message],
* as if by an initial call of `isolate.pause(isolate.pauseCapability)`.
* To resume the isolate, call `isolate.resume(isolate.pauseCapability)`.
*
@ -184,19 +192,22 @@ class Isolate {
* corresponding parameter and was processed before the isolate starts
* running.
*
* If [errorsAreFatal] is omitted, the platform may choose a default behavior
* or inherit the current isolate's behavior.
*
* You can also call the [setErrorsFatal], [addOnExitListener] and
* [addErrorListener] methods on the returned isolate, but unless the
* isolate was started as [paused], it may already have terminated
* before those methods can complete.
*
* Returns a future that will complete with an [Isolate] instance if the
* Returns a future which will complete with an [Isolate] instance if the
* spawning succeeded. It will complete with an error otherwise.
*/
external static Future<Isolate> spawn(void entryPoint(message), var message,
{ bool paused: false,
bool errorsAreFatal,
SendPort onExit,
SendPort onError });
{bool paused: false,
bool errorsAreFatal,
SendPort onExit,
SendPort onError});
/**
* Creates and spawns an isolate that runs the code from the library with
@ -291,13 +302,16 @@ class Isolate {
/**
* Requests the isolate to pause.
*
* The isolate should stop handling events by pausing its event queue.
* The request will eventually make the isolate stop doing anything.
* It will be handled before any other messages that are later sent to the
* isolate from the current isolate, but no other guarantees are provided.
* When the isolate receives the pause command, it stops
* processing events from the event loop queue.
* It may still add new events to the queue in response to, e.g., timers
* or receive-port messages. When the isolate is resumed, it handles
* the already enqueued events.
*
* The event loop may be paused before previously sent, but not yet exeuted,
* messages have been reached.
* The pause request is sent through the isolate's command port,
* which bypasses the receiving isolate's event loop.
* The pause takes effect when it is received, pausing the event loop
* as it is at that time.
*
* If [resumeCapability] is provided, it is used to identity the pause,
* and must be used again to end the pause using [resume].
@ -307,12 +321,12 @@ class Isolate {
* only one resume with that capability is needed to end the pause.
*
* If an isolate is paused using more than one capability,
* they must all be individully ended before the isolate resumes.
* each pause must be individually ended before the isolate resumes.
*
* Returns the capability that must be used to resume end the pause.
* Returns the capability that must be used to end the pause.
*/
Capability pause([Capability resumeCapability]) {
if (resumeCapability == null) resumeCapability = new Capability();
resumeCapability ??= new Capability();
_pause(resumeCapability);
return resumeCapability;
}
@ -327,7 +341,7 @@ class Isolate {
* that was requested using the [resumeCapability].
*
* When all active pause requests have been cancelled, the isolate
* will continue handling normal messages.
* will continue processing events and handling normal messages.
*
* The capability must be one returned by a call to [pause] on this
* isolate, otherwise the resume call does nothing.