kotlinx.coroutines.experimental

Class BuildersKt

kotlinx.coroutines.experimental.BuildersKt

public class BuildersKt

Method Summary

Modifier and Type	Method and Description
static Job	launch(CoroutineScope $receiver, kotlin.coroutines.experimental.CoroutineContext context, CoroutineStart start, kotlin.jvm.functions.Function1<? super java.lang.Throwable,kotlin.Unit> onCompletion, kotlin.jvm.functions.Function2<? super kotlinx.coroutines.experimental.CoroutineScope,? super kotlin.coroutines.experimental.Continuation<? super kotlin.Unit>,? extends java.lang.Object> block) Launches new coroutine without blocking current thread and returns a reference to the coroutine as a interface Job. The coroutine is cancelled when the resulting job is Job.cancel.
static <T> T	runBlocking(kotlin.coroutines.experimental.CoroutineContext context, kotlin.jvm.functions.Function2<? super kotlinx.coroutines.experimental.CoroutineScope,? super kotlin.coroutines.experimental.Continuation<? super T>,? extends java.lang.Object> block) Runs new coroutine and blocks current thread interruptibly until its completion. This function should not be used from coroutine. It is designed to bridge regular blocking code to libraries that are written in suspending style, to be used in main functions and in tests.
static <T> java.lang.Object	withContext(kotlin.coroutines.experimental.CoroutineContext context, CoroutineStart start, kotlin.jvm.functions.Function2<? super kotlinx.coroutines.experimental.CoroutineScope,? super kotlin.coroutines.experimental.Continuation<? super T>,? extends java.lang.Object> block, kotlin.coroutines.experimental.Continuation<? super T> p) Calls the specified suspending block with a given coroutine context, suspends until it completes, and returns the result.

Method Detail

runBlocking

public static <T> T runBlocking(kotlin.coroutines.experimental.CoroutineContext context,
                                kotlin.jvm.functions.Function2<? super kotlinx.coroutines.experimental.CoroutineScope,? super kotlin.coroutines.experimental.Continuation<? super T>,? extends java.lang.Object> block)

Runs new coroutine and blocks current thread interruptibly until its completion. This function should not be used from coroutine. It is designed to bridge regular blocking code to libraries that are written in suspending style, to be used in main functions and in tests.

The default class CoroutineDispatcher for this builder in an implementation of interface EventLoop that processes continuations in this blocked thread until the completion of this coroutine. See class CoroutineDispatcher for the other implementations that are provided by kotlinx.coroutines.

When class CoroutineDispatcher is explicitly specified in the context, then the new coroutine runs in the context of the specified dispatcher while the current thread is blocked. If the specified dispatcher implements interface EventLoop interface and this runBlocking invocation is performed from inside of the this event loop's thread, then this event loop is processed using its EventLoop.processNextEvent method until coroutine completes.

If this blocked thread is interrupted (see Thread.interrupt), then the coroutine job is cancelled and this runBlocking invocation throws InterruptedException.

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

Parameters:

context - context of the coroutine. The default value is an implementation of interface EventLoop.

block - the coroutine code.

See Also:

class CoroutineDispatcher, interface EventLoop, class CoroutineDispatcher, class CoroutineDispatcher, interface EventLoop, EventLoop.processNextEvent, Thread.interrupt, InterruptedException

withContext

public static <T> java.lang.Object withContext(kotlin.coroutines.experimental.CoroutineContext context,
                                               CoroutineStart start,
                                               kotlin.jvm.functions.Function2<? super kotlinx.coroutines.experimental.CoroutineScope,? super kotlin.coroutines.experimental.Continuation<? super T>,? extends java.lang.Object> block,
                                               kotlin.coroutines.experimental.Continuation<? super T> p)

Calls the specified suspending block with a given coroutine context, suspends until it completes, and returns the result.

This function immediately applies dispatcher from the new context, shifting execution of the block into the different thread inside the block, and back when it completes. The specified context is added onto the current coroutine context for the execution of the block.

An optional start parameter is used only if the specified context uses a different class CoroutineDispatcher than a current one, otherwise it is ignored. By default, the coroutine is immediately scheduled for execution and can be cancelled while it is waiting to be executed and it can be cancelled while the result is scheduled to be processed by the invoker context. Other options can be specified via start parameter. See enum CoroutineStart for details. A value of CoroutineStart.LAZY is not supported and produces IllegalArgumentException.

See Also:

class CoroutineDispatcher, enum CoroutineStart, IllegalArgumentException

launch

public static Job launch(CoroutineScope $receiver,
                         kotlin.coroutines.experimental.CoroutineContext context,
                         CoroutineStart start,
                         kotlin.jvm.functions.Function1<? super java.lang.Throwable,kotlin.Unit> onCompletion,
                         kotlin.jvm.functions.Function2<? super kotlinx.coroutines.experimental.CoroutineScope,? super kotlin.coroutines.experimental.Continuation<? super kotlin.Unit>,? extends java.lang.Object> block)

Launches new coroutine without blocking current thread and returns a reference to the coroutine as a interface Job. The coroutine is cancelled when the resulting job is Job.cancel.

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.Default 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 start 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, the coroutine interface Job is created in new state. It can be explicitly started with Job.start function and will be started implicitly on the first invocation of Job.join.

Uncaught exceptions in this coroutine cancel parent job in the context by default (unless interface CoroutineExceptionHandler is explicitly specified), which means that when launch is used with the context of another coroutine, then any uncaught exception leads to the cancellation of parent coroutine.

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

Parameters:

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

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

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

block - the coroutine code which will be invoked in the context of the provided scope.

See Also:

interface Job, Job.cancel, interface CoroutineScope, ContinuationInterceptor, interface CoroutineScope, coroutineContext, enum CoroutineStart, interface Job, Job.start, Job.join, interface CoroutineExceptionHandler