Isolate final

final class Isolate

An isolated Dart execution context.

All Dart code runs in an isolate, and code can access classes and values only from the same isolate. Different isolates can communicate by sending values through ports (see ReceivePort, SendPort).

An Isolate object is a reference to an isolate, usually different from the current isolate. It represents, and can be used to control, the other isolate.

When spawning a new isolate, the spawning isolate receives an Isolate object representing the new isolate when the spawn operation succeeds.

Isolates run code in its own event loop, and each event may run smaller tasks in a nested microtask queue.

An Isolate object allows other isolates to control the event loop of the isolate that it represents, and to inspect the isolate, for example by pausing the isolate or by getting events when the isolate has an uncaught error.

The controlPort identifies and gives access to controlling the isolate, and the pauseCapability and terminateCapability guard access to some control operations. For example, calling pause on an Isolate object created without a pauseCapability, has no effect.

The Isolate object provided by a spawn operation will have the control port and capabilities needed to control the isolate. New isolate objects can be created without some of these capabilities if necessary, using the Isolate.new constructor.

An Isolate object cannot be sent over a SendPort, but the control port and capabilities can be sent, and can be used to create a new functioning Isolate object in the receiving port's isolate.

Constructors

Isolate()

Isolate(
  SendPort controlPort, {
  Capability? pauseCapability,
  Capability? terminateCapability,
})

Creates a new Isolate object with a restricted set of capabilities.

The port should be a control port for an isolate, as taken from another Isolate object.

The capabilities should be the subset of the capabilities that are available to the original isolate. Capabilities of an isolate are locked to that isolate, and have no effect anywhere else, so the capabilities should come from the same isolate as the control port.

Can also be used to create an Isolate object from a control port, and any available capabilities, that have been sent through a SendPort.

Example:

dart

Isolate isolate = findSomeIsolate();
Isolate restrictedIsolate = Isolate(isolate.controlPort);
untrustedCode(restrictedIsolate);

This example creates a new Isolate object that cannot be used to pause or terminate the isolate. All the untrusted code can do is to inspect the isolate and see uncaught errors or when it terminates.

Implementation

dart

Isolate(this.controlPort, {this.pauseCapability, this.terminateCapability});

Properties

controlPort final

final SendPort controlPort

Control port used to send control messages to the isolate.

The control port identifies the isolate.

An Isolate object allows sending control messages through the control port.

Some control messages require a specific capability to be passed along with the message (see pauseCapability and terminateCapability), otherwise the message is ignored by the isolate.

Implementation

dart

final SendPort controlPort;

debugName no setter

String? get debugName

The name of the Isolate displayed for debug purposes.

This can be set using the debugName parameter in spawn and spawnUri.

This name does not uniquely identify an isolate. Multiple isolates in the same process may have the same debugName.

For a given isolate, this value will be the same as the values returned by Dart_DebugName in the C embedding API and the debugName property in IsolateMirror.

Implementation

dart

external String? get debugName;

errors no setter

Stream<dynamic> get errors

Returns a broadcast stream of uncaught errors from the isolate.

Each error is provided as an error event on the stream.

The actual error object and stackTraces will not necessarily be the same object types as in the actual isolate, but they will always have the same Object.toString result.

This stream is based on addErrorListener and removeErrorListener.

Implementation

dart

Stream get errors {
  StreamController controller = StreamController.broadcast(sync: true);
  RawReceivePort? port;
  void handleError(Object? message) {
    var listMessage = message as List<Object?>;
    var errorDescription = listMessage[0] as String;
    var stackDescription = listMessage[1] as String;
    var error = RemoteError(errorDescription, stackDescription);
    controller.addError(error, error.stackTrace);
  }

  controller.onListen = () {
    RawReceivePort receivePort = RawReceivePort(handleError);
    port = receivePort;
    this.addErrorListener(receivePort.sendPort);
  };
  controller.onCancel = () {
    var listenPort = port!;
    port = null;
    this.removeErrorListener(listenPort.sendPort);
    listenPort.close();
  };
  return controller.stream;
}

hashCode no setter inherited

int get hashCode

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Inherited from Object.

Implementation

dart

external int get hashCode;

pauseCapability final

final Capability? pauseCapability

Capability granting the ability to pause the isolate.

This capability is required by pause. If the capability is null, or if it is not the correct pause capability of the isolate identified by controlPort, then calls to pause will have no effect.

If the isolate is spawned in a paused state, use this capability as argument to the resume method in order to resume the paused isolate.

Implementation

dart

final Capability? pauseCapability;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

dart

external Type get runtimeType;

terminateCapability final

final Capability? terminateCapability

Capability granting the ability to terminate the isolate.

This capability is required by kill and setErrorsFatal. If the capability is null, or if it is not the correct termination capability of the isolate identified by controlPort, then calls to those methods will have no effect.

Implementation

dart

final Capability? terminateCapability;

Methods

addErrorListener()

void addErrorListener(SendPort port)

Requests that uncaught errors of the isolate are sent back to port.

The errors are sent back as two-element lists. The first element is a String representation of the error, usually created by calling toString on the error. The second element is a String representation of an accompanying stack trace, or null if no stack trace was provided. To convert this back to a StackTrace object, use StackTrace.fromString.

Listening using the same port more than once does nothing. A port will only receive each error once, and will only need to be removed once using removeErrorListener.

Closing the receive port that is associated with the port does not stop the isolate from sending uncaught errors, they are just going to be lost. Instead use removeErrorListener to stop receiving errors on port.

Since isolates run concurrently, it's possible for it to exit before the error listener is established. To avoid this, start the isolate paused, add the listener and then resume the isolate.

Implementation

dart

external void addErrorListener(SendPort port);

addOnExitListener()

void addOnExitListener(SendPort responsePort, {Object? response})

Requests an exit message on responsePort when the isolate terminates.

The isolate will send response as a message on responsePort as the last thing before it terminates. It will run no further code after the message has been sent.

Adding the same port more than once will only cause it to receive one exit message, using the last response value that was added, and it only needs to be removed once using removeOnExitListener.

If the isolate has terminated before it can receive this request, no exit message will be sent.

The response object must follow the same restrictions as enforced by SendPort.send when sending to an isolate from another isolate group; only simple values that can be sent to all isolates, like null, booleans, numbers or strings, are allowed.

Since isolates run concurrently, it's possible for it to exit before the exit listener is established, and in that case no response will be sent on responsePort. To avoid this, either use the corresponding parameter to the spawn function, or start the isolate paused, add the listener and then resume the isolate.

Implementation

dart

&#47;* TODO(lrn): Can we do better? Can the system recognize this message and
 * send a reply if the receiving isolate is dead?
 *&#47;
external void addOnExitListener(SendPort responsePort, {Object? response});

kill()

void kill({int priority = beforeNextEvent})

Requests the isolate to shut down.

The isolate is requested to terminate itself. The priority argument specifies when this must happen.

The priority, when provided, must be one of immediate or beforeNextEvent (the default). The shutdown is performed at different times depending on the priority:

immediate: The isolate shuts down as soon as possible. Control messages are handled in order, so all previously sent control events from this isolate will all have been processed. The shutdown should happen no later than if sent with beforeNextEvent. It may happen earlier if the system has a way to shut down cleanly at an earlier time, even during the execution of another event.
beforeNextEvent: The shutdown is scheduled for the next time control returns to the event loop of the receiving isolate, after the current event, and any already scheduled control events, are completed.

If terminateCapability is null, or it's not the terminate capability of the isolate identified by controlPort, the kill request is ignored by the receiving isolate.

Implementation

dart

external void kill({int priority = beforeNextEvent});

noSuchMethod() inherited

dynamic noSuchMethod(Invocation invocation)

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dart

dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

dart

class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

Implementation

dart

@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

pause()

Capability pause([Capability? resumeCapability])

Requests the isolate to pause.

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 starts handling the already enqueued events.

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.

The resumeCapability is used to identity the pause, and must be used again to end the pause using resume. If resumeCapability is omitted, a new capability object is created and used instead.

If an isolate is paused more than once using the same capability, only one resume with that capability is needed to end the pause.

If an isolate is paused using more than one capability, each pause must be individually ended before the isolate resumes.

Returns the capability that must be used to end the pause. This is either resumeCapability, or a new capability when resumeCapability is omitted.

If pauseCapability is null, or it's not the pause capability of the isolate identified by controlPort, the pause request is ignored by the receiving isolate.

Implementation

dart

Capability pause([Capability? resumeCapability]) {
  resumeCapability ??= Capability();
  _pause(resumeCapability);
  return resumeCapability;
}

ping()

void ping(SendPort responsePort, {Object? response, int priority = immediate})

Requests that the isolate send response on the responsePort.

If the isolate is alive, it will eventually send response (defaulting to null) on the response port.

The priority must be one of immediate or beforeNextEvent. The response is sent at different times depending on the ping type:

immediate: The isolate responds as soon as it receives the control message. This is after any previous control message from the same isolate has been received and processed, but may be during execution of another event.
beforeNextEvent: The response is scheduled for the next time control returns to the event loop of the receiving isolate, after the current event, and any already scheduled control events, are completed.

Implementation

dart

external void ping(
  SendPort responsePort, {
  Object? response,
  int priority = immediate,
});

removeErrorListener()

void removeErrorListener(SendPort port)

Stops listening for uncaught errors from the isolate.

Requests for the isolate to not send uncaught errors on port. If the isolate isn't expecting to send uncaught errors on port, because the port hasn't been added using addErrorListener, or because it has already been removed, the request is ignored.

If the same port has been passed via addErrorListener more than once, only one call to removeErrorListener is needed to stop it from receiving uncaught errors.

Uncaught errors message may still be sent by the isolate until this request is received and processed.

Implementation

dart

external void removeErrorListener(SendPort port);

removeOnExitListener()

void removeOnExitListener(SendPort responsePort)

Stops listening for exit messages from the isolate.

Requests for the isolate to not send exit messages on responsePort. If the isolate isn't expecting to send exit messages on responsePort, because the port hasn't been added using addOnExitListener, or because it has already been removed, the request is ignored.

If the same port has been passed via addOnExitListener more than once, only one call to removeOnExitListener is needed to stop it from receiving exit messages.

Closing the receive port that is associated with the responsePort does not stop the isolate from sending uncaught errors, they are just going to be lost.

An exit message may still be sent if the isolate terminates before this request is received and processed.

Implementation

dart

external void removeOnExitListener(SendPort responsePort);

resume()

void resume(Capability resumeCapability)

Resumes a paused isolate.

Sends a message to an isolate requesting that it ends a pause that was previously requested.

When all active pause requests have been cancelled, the isolate will continue processing events and handling normal messages.

If the resumeCapability is not one that has previously been used to pause the isolate, or it has already been used to resume from that pause, the resume call has no effect.

Implementation

dart

external void resume(Capability resumeCapability);

setErrorsFatal()

void setErrorsFatal(bool errorsAreFatal)

Sets whether uncaught errors will terminate the isolate.

If errors are fatal, any uncaught error will terminate the isolate event loop and shut down the isolate.

This call requires the terminateCapability for the isolate. If the capability is absent or incorrect, no change is made.

Since isolates run concurrently, it's possible for the receiving isolate to exit due to an error, before a request, using this method, has been received and processed. To avoid this, either use the corresponding parameter to the spawn function, or start the isolate paused, set errors non-fatal and then resume the isolate.

Implementation

dart

external void setErrorsFatal(bool errorsAreFatal);

toString() inherited

String toString()

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.

Inherited from Object.

Implementation

dart

external String toString();

Operators

operator ==() inherited

bool operator ==(Object other)

The equality operator.

The default behavior for all Objects is to return true if and only if this object and other are the same object.

Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be:

Total: It must return a boolean for all arguments. It should never throw.
Reflexive: For all objects o, o == o must be true.
Symmetric: For all objects o1 and o2, o1 == o2 and o2 == o1 must either both be true, or both be false.
Transitive: For all objects o1, o2, and o3, if o1 == o2 and o2 == o3 are true, then o1 == o3 must be true.

The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified.

If a subclass overrides the equality operator, it should override the hashCode method as well to maintain consistency.

Inherited from Object.

Implementation

dart

external bool operator ==(Object other);

Static Properties

current no setter

Isolate get current

An Isolate object representing the current isolate.

The current isolate for code using current is the isolate running the code.

The isolate object provides the capabilities required to inspect, pause or kill the isolate, and allows granting these capabilities to others.

It is possible to pause the current isolate, but doing so without first passing the ability to resume it again to another isolate, is a sure way to hang your program.

Implementation

dart

external static Isolate get current;

packageConfig no setter

Future<Uri?> get packageConfig

The location of the package configuration file of the current isolate.

If the isolate was spawned without specifying its package configuration file then the returned value is null.

Otherwise, the returned value is an absolute URI specifying the location of isolate's package configuration file.

The package configuration file is usually named package_config.json, and you can use package:package_config to read and parse it.

Implementation

dart

external static Future<Uri?> get packageConfig;

packageConfigSync no setter

Uri? get packageConfigSync

The location of the package configuration file of the current isolate.

If the isolate was spawned without specifying its package configuration file then the returned value is null.

Otherwise, the returned value is an absolute URI specifying the location of isolate's package configuration file.

The package configuration file is usually named package_config.json, and you can use package:package_config to read and parse it.

Implementation

dart

@Since('3.2')
external static Uri? get packageConfigSync;

Static Methods

exit()

Never exit([SendPort? finalMessagePort, Object? message])

Terminates the current isolate synchronously.

This operation is potentially dangerous and should be used judiciously. The isolate stops operating immediately. It throws if the optional message does not adhere to the limitations on what can be sent from one isolate to another (see SendPort.send for more details). It also throws if a finalMessagePort is associated with an isolate spawned outside of current isolate group, spawned via spawnUri. Please refer to isolate group for more details about isolate groups.

If successful, a call to this method does not return. Pending finally blocks are not executed, control flow will not go back to the event loop, scheduled asynchronous asks will never run, and even pending isolate control commands may be ignored. (The isolate will send messages to ports already registered using Isolate.addOnExitListener, but no further Dart code will run in the isolate.)

If finalMessagePort is provided, and the message can be sent through it (see SendPort.send for more details), then the message is sent through that port as the final operation of the current isolate. The isolate terminates immediately after that SendPort.send call returns.

If the port is a native port -- one provided by ReceivePort.sendPort or RawReceivePort.sendPort -- the system may be able to send this final message more efficiently than normal port communication between live isolates. In these cases this final message object graph will be reassigned to the receiving isolate without copying. Further, the receiving isolate will in most cases be able to receive the message in constant time.

Implementation

dart

external static Never exit([SendPort? finalMessagePort, Object? message]);

resolvePackageUri()

Future<Uri?> resolvePackageUri(Uri packageUri)

Resolves a package: URI to its actual location.

Returns the actual location of the file or directory specified by the packageUri package: URI.

If the packageUri is not a package: URI, it's returned as-is.

Returns null if packageUri is a package: URI, but either the current package configuration does not have a configuration for the package name of the URI, or the URI is not valid (doesn't start with package:valid_package_name/),

A package: URI is resolved to its actual location based on a package resolution configuration (see packageConfig) which specifies how to find the actual location of the file or directory that the package: URI points to.

The actual location corresponding to a package: URI is always a non-package: URI, typically a file: or possibly http: URI.

A program may be run in a way where source files are not available, and if so, the returned URI may not correspond to the actual file or directory or be null.

Implementation

dart

external static Future<Uri?> resolvePackageUri(Uri packageUri);

resolvePackageUriSync()

Uri? resolvePackageUriSync(Uri packageUri)

Resolves a package: URI to its actual location.

Returns the actual location of the file or directory specified by the packageUri package: URI.

If the packageUri is not a package: URI, it's returned as-is.

The actual location corresponding to a package: URI is always a non-package: URI, typically a file: or possibly http: URI.

A program may be run in a way where source files are not available, and if so, the returned URI may not correspond to the actual file or directory or be null.

Implementation

dart

@Since('3.2')
external static Uri? resolvePackageUriSync(Uri packageUri);

run()

Future<R> run<R>(FutureOr<R> Function() computation, {String? debugName})

Runs computation in a new isolate and returns the result.

dart

int slowFib(int n) =>
    n <= 1 ? 1 : slowFib(n - 1) + slowFib(n - 2);

// Compute without blocking current isolate.
var fib40 = await Isolate.run(() => slowFib(40));

If computation is asynchronous (returns a Future<R>) then that future is awaited in the new isolate, completing the entire asynchronous computation, before returning the result.

dart

int slowFib(int n) =>
    n <= 1 ? 1 : slowFib(n - 1) + slowFib(n - 2);
Stream<int> fibStream() async* {
  for (var i = 0;; i++) yield slowFib(i);
}

// Returns `Future<int>`.
var fib40 = await Isolate.run(() => fibStream().elementAt(40));

If computation throws, the isolate is terminated and this function throws the same error.

dart

Future<int> eventualError() async {
  await Future.delayed(const Duration(seconds: 1));
  throw StateError("In a bad state!");
}

try {
  await Isolate.run(eventualError);
} on StateError catch (e, s) {
  print(e.message); // In a bad state!
  print(LineSplitter.split("$s").first); // Contains "eventualError"
}

Any uncaught asynchronous errors will terminate the computation as well, but will be reported as a RemoteError because addErrorListener does not provide the original error object.

The result is sent using exit, which means it's sent to this isolate without copying.

The computation function and its result (or error) must be sendable between isolates. Objects that cannot be sent include open files and sockets (see SendPort.send for details).

If computation is a closure then it may implicitly send unexpected state to the isolate due to limitations in the Dart implementation. This can cause performance issues, increased memory usage (see http://dartbug.com/36983) or, if the state includes objects that can't be spent between isolates, a runtime failure.

dart


void serializeAndWrite(File f, Object o) async {
  final openFile = await f.open(mode: FileMode.append);
  Future writeNew() async {
    // Will fail with:
    // "Invalid argument(s): Illegal argument in isolate message"
    // because `openFile` is captured.
    final encoded = await Isolate.run(() => jsonEncode(o));
    await openFile.writeString(encoded);
    await openFile.flush();
    await openFile.close();
  }

  if (await openFile.position() == 0) {
    await writeNew();
  }
}

In such cases, you can create a new function to call Isolate.run that takes all of the required state as arguments.

dart


void serializeAndWrite(File f, Object o) async {
  final openFile = await f.open(mode: FileMode.append);
  Future writeNew() async {
    Future<String> encode(o) => Isolate.run(() => jsonEncode(o));
    final encoded = await encode(o);
    await openFile.writeString(encoded);
    await openFile.flush();
    await openFile.close();
  }

  if (await openFile.position() == 0) {
    await writeNew();
  }
}

The debugName is only used to name the new isolate for debugging.

Implementation

dart

@Since("2.19")
static Future<R> run<R>(FutureOr<R> computation(), {String? debugName}) {
  var result = Completer<R>();
  var resultPort = RawReceivePort();
  resultPort.handler = (response) {
    resultPort.close();
    if (response == null) {
      &#47;&#47; onExit handler message, isolate terminated without sending result.
      result.completeError(
        RemoteError("Computation ended without result", ""),
        StackTrace.empty,
      );
      return;
    }
    var list = response as List<Object?>;
    if (list.length == 2) {
      var remoteError = list[0];
      var remoteStack = list[1];
      if (remoteStack is StackTrace) {
        &#47;&#47; Typed error.
        result.completeError(remoteError!, remoteStack);
      } else {
        &#47;&#47; onError handler message, uncaught async error.
        &#47;&#47; Both values are strings, so calling `toString` is efficient.
        var error = RemoteError(
          remoteError.toString(),
          remoteStack.toString(),
        );
        result.completeError(error, error.stackTrace);
      }
    } else {
      assert(list.length == 1);
      result.complete(list[0] as R);
    }
  };
  try {
    Isolate.spawn(
      _RemoteRunner._remoteExecute,
      _RemoteRunner<R>(computation, resultPort.sendPort),
      onError: resultPort.sendPort,
      onExit: resultPort.sendPort,
      errorsAreFatal: true,
      debugName: debugName,
    ).then<void>(
      (_) {},
      onError: (error, stack) {
        &#47;&#47; Sending the computation failed asynchronously.
        &#47;&#47; Do not expect a response, report the error asynchronously.
        resultPort.close();
        result.completeError(error, stack);
      },
    );
  } on Object {
    &#47;&#47; Sending the computation failed synchronously.
    &#47;&#47; This is not expected to happen, but if it does,
    &#47;&#47; the synchronous error is respected and rethrown synchronously.
    resultPort.close();
    rethrow;
  }
  return result.future;
}

spawn()

Future<Isolate> spawn<T>(
  void Function(T message) entryPoint,
  T message, {
  bool paused = false,
  bool errorsAreFatal = true,
  SendPort? onExit,
  SendPort? onError,
  String? debugName,
})

Spawns an isolate that shares the same code as the current isolate.

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 entryPoint function must be able to be called with a single argument, that is, a function 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. If entryPoint is a closure then it may implicitly send unexpected state to the isolate due to limitations in the Dart implementation. This can cause performance issues, increased memory usage (see http://dartbug.com/36983) or, if the state includes objects that can't be spent between isolates, a runtime failure. See run for an example.

message must be sendable between isolates. Objects that cannot be sent include open files and sockets (see SendPort.send for details). 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).

If the errorsAreFatal, onExit and/or onError parameters are provided, the isolate will act as if, respectively, setErrorsFatal, addOnExitListener and addErrorListener were called with the corresponding parameter and was processed before the isolate starts running.

If debugName is provided, the spawned Isolate will be identifiable by this name in debuggers and logging.

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 which will complete with an Isolate instance if the spawning succeeded. It will complete with an error otherwise.

One can expect the base memory overhead of an isolate to be in the order of 30 kb.

Implementation

dart

external static Future<Isolate> spawn<T>(
  void entryPoint(T message),
  T message, {
  bool paused = false,
  bool errorsAreFatal = true,
  SendPort? onExit,
  SendPort? onError,
  String? debugName,
});

spawnUri()

Future<Isolate> spawnUri(
  Uri uri,
  List<String> args,
  dynamic message, {
  bool paused = false,
  SendPort? onExit,
  SendPort? onError,
  bool errorsAreFatal = true,
  bool? checked,
  Map<String, String>? environment,
  Uri? packageRoot,
  Uri? packageConfig,
  bool automaticPackageResolution = false,
  String? debugName,
})

Spawns an isolate running the script file specified by uri.

Creates and spawns a new isolate that runs the Dart program which has the uri file as the entry point that provides the main method. The new isolate belongs to a new isolate group, different from the isolate group of the spawning isolate.

The isolate starts executing the top-level main function of the library with the given URI.

The target main must be callable with zero, one or two arguments. Examples:

main()
main(args)
main(args, message)

When present, the parameter args is set to the provided args list. When present, the parameter message is set to the initial message. A runtime error occurs if the message argument's runtime type cannot be assigned to the second parameter of the main method.

If the paused parameter is set to true, the isolate will start up in a paused state, as if by an initial call of isolate.pause(isolate.pauseCapability). To resume the isolate, call isolate.resume(isolate.pauseCapability).

The checked parameter controls whether asserts are enabled in the created isolate. In a production-mode program, the parameter is ignored, and assertions are always disabled in all isolates. Otherwise if a true or false value is provided, assertions are enabled or disabled, respectively, in the created isolate. If null or no argument is provided, asserts are enabled in the created isolate if and only if they are enabled in the spawning isolate.

It may not always be possible to honor the checked parameter. If the isolate code was pre-compiled, it may not be possible to change the checked mode setting dynamically. In that case, the checked parameter is ignored.

If the packageConfig parameter is provided, then it is used to find the location of a package resolution configuration file for the spawned isolate.

If the automaticPackageResolution parameter is provided, then the location of the package sources in the spawned isolate is automatically determined.

The environment is a mapping from strings to strings which the spawned isolate uses when looking up String.fromEnvironment values. The system may add its own entries to environment as well. If environment is omitted, the spawned isolate has the same environment declarations as the spawning isolate.

WARNING: The environment parameter is not implemented on all platforms yet.

If debugName is provided, the spawned Isolate will be identifiable by this name in debuggers and logging.

Returns a future that will complete with an Isolate instance if the spawning succeeded. It will complete with an error otherwise.

Implementation

dart

external static Future<Isolate> spawnUri(
  Uri uri,
  List<String> args,
  var message, {
  bool paused = false,
  SendPort? onExit,
  SendPort? onError,
  bool errorsAreFatal = true,
  bool? checked,
  Map<String, String>? environment,
  @Deprecated('The packages&#47; dir is not supported in Dart 2')
  Uri? packageRoot,
  Uri? packageConfig,
  bool automaticPackageResolution = false,
  String? debugName,
});

Constants

beforeNextEvent

const int beforeNextEvent

Argument to ping and kill: Ask for action before the next event.

Implementation

dart

static const int beforeNextEvent = 1;

immediate

const int immediate

Argument to ping and kill: Ask for immediate action.

Implementation

dart

static const int immediate = 0;

Isolate final ​

Constructors ​

Isolate() ​

Properties ​

controlPort final ​

debugName no setter ​

errors no setter ​

hashCode no setter inherited ​

pauseCapability final ​

runtimeType no setter inherited ​

terminateCapability final ​

Methods ​

addErrorListener() ​

addOnExitListener() ​

kill() ​

noSuchMethod() inherited ​

pause() ​

ping() ​

removeErrorListener() ​

removeOnExitListener() ​

resume() ​

setErrorsFatal() ​

toString() inherited ​

Operators ​

operator ==() inherited ​

Static Properties ​

current no setter ​

packageConfig no setter ​

packageConfigSync no setter ​

Static Methods ​

exit() ​

resolvePackageUri() ​

resolvePackageUriSync() ​

run() ​

spawn() ​

spawnUri() ​

Constants ​

beforeNextEvent ​

immediate ​

Isolate final

Constructors

Isolate()

Properties

controlPort final

debugName no setter

errors no setter

hashCode no setter inherited

pauseCapability final

runtimeType no setter inherited

terminateCapability final

Methods

addErrorListener()

addOnExitListener()

kill()

noSuchMethod() inherited

pause()

ping()

removeErrorListener()

removeOnExitListener()

resume()

setErrorsFatal()

toString() inherited

Operators

operator ==() inherited

Static Properties

current no setter

packageConfig no setter

packageConfigSync no setter

Static Methods

exit()

resolvePackageUri()

resolvePackageUriSync()

run()

spawn()

spawnUri()

Constants

beforeNextEvent

immediate