actor

Platform and version requirements: JVM

Launches new coroutine that is receiving messages from its mailbox channel and returns a reference to its mailbox channel as a SendChannel. The resulting object can be used to send messages to this coroutine.

The scope of the coroutine contains ActorScope interface, which implements both CoroutineScope and ReceiveChannel, so that coroutine can invoke receive directly. The channel is closed when the coroutine completes.

The context for the new coroutine can be explicitly specified. See CoroutineDispatcher for the standard context implementations that are provided by kotlinx.coroutines. The context of the parent coroutine from its scope may be used, in which case the Job of the resulting coroutine is a child of the job of the parent coroutine. The parent job may be also explicitly specified using parent parameter.

If the context does not have any dispatcher nor any other ContinuationInterceptor, then DefaultDispatcher is used.

By default, the coroutine is immediately scheduled for execution. Other options can be specified via start parameter. See CoroutineStart for details. An optional start parameter can be set to CoroutineStart.LAZY to start coroutine lazily. In this case, it will be started implicitly on the first message sent to this actors’s mailbox channel.

Uncaught exceptions in this coroutine close the channel with this exception as a cause and the resulting channel becomes failed, so that any attempt to send to such a channel throws exception.

See newCoroutineContext for a description of debugging facilities that are available for newly created coroutine.

Using actors

A typical usage of the actor builder looks like this:

val c = actor {
    // initialize actor's state
    for (msg in channel) {
        // process message here
    }
}
// send messages to the actor
c.send(...)
...
// stop the actor when it is no longer needed
c.close()

Stopping and cancelling actors

When the inbox channel of the actor is closed it sends a special “close token” to the actor. The actor still processes all the messages that were already sent and then “for (msg in channel)” loop terminates and the actor completes.

If the actor needs to be aborted without processing all the messages that were already sent to it, then it shall be created with a parent job:

val job = Job()
val c = actor(parent = job) {  ... }
...
// abort the actor
job.cancel()

When actor’s parent job is cancelled, then actor’s job becomes cancelled. It means that “for (msg in channel)” and other cancellable suspending functions throw CancellationException and actor completes without processing remaining messages.

Parameters

context - context of the coroutine. The default value is DefaultDispatcher.

capacity - capacity of the channel’s buffer (no buffer by default).

start - coroutine start option. The default value is CoroutineStart.DEFAULT.

parent - explicitly specifies the parent job, overrides job from the context (if any).*

block - the coroutine code.