const virtual class concurrent::Actor

sys::Obj
  concurrent::Actor

@Js
@JsNative

Actor is a worker who processes messages asynchronously.

See docLang::Actors and examples.

locals

static Map<Str,Obj?> locals()

Return the map of "global" variables visibile only to the current actor (similar to how thread locals work in Java). These variables are keyed by a string name - by convention use a dotted notation beginning with your pod name to avoid naming collisions.

make

new make(ActorPool pool := ActorPool.defVal(), Func<Obj?,Obj?>? receive := null)

Create an actor whose execution is controlled by the given ActorPool. If receive is non-null, then it is used to process messages sent to this actor. If receive is specified then it must be an immutable function (it cannot capture state from the calling thread), otherwise NotImmutableErr is thrown. If receive is null, then you must subclass Actor and override the receive method.

makeCoalescing

new makeCoalescing(ActorPool pool, Func<Obj?,Obj?>? toKey, Func<Obj?,Obj?,Obj?>? coalesce, Func<Obj?,Obj?>? receive := null)

Create an actor with a coalescing message loop. This constructor follows the same semantics as make, but has the ability to coalesce the messages pending in the thread's message queue. Coalesced messages are merged into a single pending message with a shared Future.

The toKey function is used to derive a key for each message, or if null then the message itself is used as the key. If the toKey function returns null, then the message is not considered for coalescing. Internally messages are indexed by key for efficient coalescing.

If an incoming message has the same key as a pending message in the queue, then the coalesce function is called to coalesce the messages into a new merged message. If coalesce function itself is null, then we use the incoming message (last one wins). The coalesced message occupies the same position in the queue as the original and reuses the original message's Future instance.

Both the toKey and coalesce functions are called while holding an internal lock on the queue. So the functions must be efficient and never attempt to interact with other actors.

pool

ActorPool pool()

The pool used to control execution of this actor.

receive

protected virtual Obj? receive(Obj? msg)

The receive behavior for this actor is handled by overriding this method or by passing a function to the constructor. Return the result made available by the Future. If an exception is raised by this method, then it is raised by Future.get.

send

Future send(Obj? msg)

Asynchronously send a message to this actor for processing. If msg is not immutable, then NotImmutableErr is thrown. Throw Err if this actor's pool has been stopped. Return a future which may be used to obtain the result once it the actor has processed the message. If the message is coalesced then this method returns the original message's future reference. Also see sendLater and sendWhenComplete.

sendLater

Future sendLater(Duration d, Obj? msg)

Schedule a message for delivery after the specified period of duration has elapsed. Once the period has elapsed the message is appended to the end of this actor's queue. Accuracy of scheduling is dependent on thread coordination and pending messages in the queue. Scheduled messages are not guaranteed to be processed if the actor's pool is stopped. Scheduled messages are never coalesced. Also see send and sendWhenComplete.

sendWhenComplete

Future sendWhenComplete(Future f, Obj? msg)

Schedule a message for delivery after the given future has completed. Completion may be due to the future returning a result, throwing an exception, or cancellation. Send-when-complete messages are never coalesced. The given future must be an actor based future. Also see send and sendLater.

sleep

static Void sleep(Duration duration)

Put the currently executing actor thread to sleep for the specified period. If the thread is interrupted for any reason while sleeping, then InterruptedErr is thrown.