SendPort abstract interface

abstract interface class SendPort implements Capability

Sends messages to its ReceivePorts.

SendPorts are created from ReceivePorts. Any message sent through a SendPort is delivered to its corresponding ReceivePort. There might be many SendPorts for the same ReceivePort.

SendPorts can be transmitted to other isolates, and they preserve equality when sent.

Implemented types

• Capability

Available Extensions

• NativePort

Properties

hashCode no setter override

int get hashCode

A hash code for this send port that is consistent with the == operator.

Implementation

int get hashCode;

nativePort extension no setter

int get nativePort

The native port of this SendPort.

The returned native port can for example be used by C code to post messages to the connected ReceivePort via Dart_PostCObject() - see dart_native_api.h.

Only the send ports from the platform classes ReceivePort and RawReceivePort are supported. User-defined implementations of SendPort are not supported.

Available on SendPort, provided by the NativePort extension

Implementation

external int get nativePort;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

external Type get runtimeType;

Methods

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:

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:

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

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

send()

void send(Object? message)

Sends an asynchronous message through this send port, to its corresponding ReceivePort.

If the sending and receiving isolates do not share the same code (an isolate created using Isolate.spawnUri does not share the code of the isolate that spawned it), the transitive object graph of message can only contain the following kinds of objects:

• null
• true and false
• Instances of int, double, String
• Instances created through list, map and set literals
• Instances created by constructors of: - List, Map, LinkedHashMap, Set and LinkedHashSet
  • TransferableTypedData
  • Capability
• SendPort instances from ReceivePort.sendPort or RawReceivePort.sendPort where the receive ports are created using those classes' constructors.
• Instances of Type representing one of the types mentioned above, Object, dynamic, void and Never as well as nullable variants of all these types. For generic types type arguments must be sendable types for the whole type to be sendable.

If the sender and receiver isolate share the same code (e.g. isolates created via Isolate.spawn), the transitive object graph of message can contain any object, with the following exceptions:

• Objects with native resources (subclasses of e.g. NativeFieldWrapperClass1). A Socket object for example refers internally to objects that have native resources attached and can therefore not be sent.
• ReceivePort
• DynamicLibrary
• Finalizable
• Finalizer
• NativeFinalizer
• UserTag
• MirrorReference

Instances of classes that either themselves are marked with @pragma('vm:isolate-unsendable'), extend or implement such classes cannot be sent through the ports.

Apart from those exceptions any object can be sent. Objects that are identified as immutable (e.g. strings) will be shared whereas all other objects will be copied.

The send happens immediately and may have a linear time cost to copy the transitive object graph. The send itself doesn't block (i.e. doesn't wait until the receiver has received the message). The corresponding receive port can receive the message as soon as its isolate's event loop is ready to deliver it, independently of what the sending isolate is doing.

Note: Due to an implementation choice the Dart VM made for how closures represent captured state, closures can currently capture more state than they need, which can cause the transitive closure to be larger than needed. Open bug to address this: http://dartbug.com/36983

Implementation

void send(Object? message);

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

external String toString();

Operators

operator ==() override

bool operator ==(Object other)

Tests whether other is a SendPort pointing to the same ReceivePort as this one.

Implementation

bool operator ==(var other);