kotlinx.coroutines.channels

Class ActorKt

kotlinx.coroutines.channels.ActorKt

public class ActorKt

Method Summary

Modifier and Type

Method and Description

static <E> SendChannel<E>

actor(CoroutineScope $receiver, NonExistentClass context, int capacity, CoroutineStart start, kotlin.jvm.functions.Function1<? super java.lang.Throwable,kotlin.Unit> onCompletion, kotlin.jvm.functions.Function2<? super kotlinx.coroutines.channels.ActorScope<E>,? super kotlin.coroutines.experimental.Continuation<? super kotlin.Unit>,? extends java.lang.Object> block) Launches new coroutine that is receiving messages from its mailbox channel and returns a reference to its mailbox channel as a interface SendChannel. The resulting object can be used to SendChannel.send messages to this coroutine.

Method Detail

actor

public static <E> SendChannel<E> actor(CoroutineScope $receiver,
                                       NonExistentClass context,
                                       int capacity,
                                       CoroutineStart start,
                                       kotlin.jvm.functions.Function1<? super java.lang.Throwable,kotlin.Unit> onCompletion,
                                       kotlin.jvm.functions.Function2<? super kotlinx.coroutines.channels.ActorScope<E>,? super kotlin.coroutines.experimental.Continuation<? super kotlin.Unit>,? extends java.lang.Object> block)

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

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

Coroutine context is inherited from a interface CoroutineScope, additional context elements can be specified with context argument. If the context does not have any dispatcher nor any other ContinuationInterceptor, then Dispatchers.getDefault is used. The parent job is inherited from a interface CoroutineScope as well, but it can also be overridden with corresponding coroutineContext element.

By default, the coroutine is immediately scheduled for execution. Other options can be specified via start parameter. See enum 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 SendChannel.send 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.

The kind of the resulting channel depends on the specified capacity parameter. See interface Channel interface documentation for details.

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 SendChannel.close 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(context = job) {  ... }
...
// abort the actor
job.cancel()

When actor's parent job is Job.cancel, 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.

Note: This API will become obsolete in future updates with introduction of complex actors. See https://github.com/Kotlin/kotlinx.coroutines/issues/87.

Parameters:

context - additional to CoroutineScope.getCoroutineContext context of the coroutine.

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

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

onCompletion - optional completion handler for the actor coroutine (see Job.invokeOnCompletion)

block - the coroutine code.

See Also:

interface SendChannel, SendChannel.send, interface ActorScope, interface CoroutineScope, interface ReceiveChannel, ReceiveChannel.receive, SendChannel.close, interface CoroutineScope, ContinuationInterceptor, Dispatchers.getDefault, interface CoroutineScope, coroutineContext, enum CoroutineStart, SendChannel.send, interface Channel, SendChannel.close, Job.cancel, https://github.com/Kotlin/kotlinx.coroutines/issues/87