kotlinx.coroutines.experimental

Class BuildersKt

kotlinx.coroutines.experimental.BuildersKt

public class BuildersKt

Method Summary

Modifier and Type	Method and Description
static Job	launch(kotlin.coroutines.experimental.CoroutineContext context, CoroutineStart start, Job parent, 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.Function1<? 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

launch

public static Job launch(kotlin.coroutines.experimental.CoroutineContext context,
                         CoroutineStart start,
                         Job parent,
                         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.

The context for the new coroutine can be explicitly specified. See class CoroutineDispatcher for the standard context implementations that are provided by kotlinx.coroutines. The CoroutineScope.getCoroutineContext of the parent coroutine from its interface CoroutineScope may be used, in which case the interface 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 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 CoroutineContextKt.newCoroutineContext for a description of debugging facilities that are available for newly created coroutine.

Parameters:

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

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.

See Also:

interface Job, Job.cancel, class CoroutineDispatcher, CoroutineScope.getCoroutineContext, interface CoroutineScope, interface Job, ContinuationInterceptor, enum CoroutineStart, interface Job, Job.start, Job.join, interface CoroutineExceptionHandler, CoroutineContextKt.newCoroutineContext

withContext

public static <T> java.lang.Object withContext(kotlin.coroutines.experimental.CoroutineContext context,
                                               CoroutineStart start,
                                               kotlin.jvm.functions.Function1<? 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

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.

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

See CoroutineContextKt.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, Thread.interrupt, InterruptedException, CoroutineContextKt.newCoroutineContext