Package ratpack.exec

Interface Execution

All Superinterfaces:

MutableRegistry, Registry, RegistrySpec

public interface Execution
extends MutableRegistry

A logical operation, such as servicing a request, that may be comprised of non contiguous units of work.

In a synchronous environment, a logical operation is typically given exclusive access to a thread for its duration. The use of thread local variables for operation global state and try/catch as a global error handling strategy rely on this. The execution construct provides mechanisms to emulate constructs of synchronous programming that cannot be achieved the same way in asynchronous programming.

Almost all work that occurs as part of a running Ratpack application happens during an execution. Ratpack APIs such as Promise, Blocking etc. can only be used within an execution. Request processing is always within an execution. When initiating other work (e.g. background processing), an execution can be created via fork()

The term “execution segment” (sometimes just “segment”) is used to refer to a unit of work within an execution. An execution segment has exclusive access to a thread. All executions start with the segment given to the ExecStarter.start(Action) method. If the initial execution segment does not use any asynchronous APIs, the execution will be comprised of that single segment. When an asynchronous API is used, via Promise.async(Upstream), the resumption of work when the result becomes available is within a new execution segment. During any execution segment, the current() method will return the current execution, giving global access to the execution object.

Segments of an execution are never executed concurrently.

Execution state (i.e. simulating thread locals)

Each execution is a MutableRegistry. Objects can be added to this registry and then later retrieved at any time during the execution. The registry storage can be leveraged via an ExecInterceptor to manage thread local storage for execution segments.

Error handling

When starting an execution, a global error handler can be specified via ExecStarter.onError(Action). The default error handler simply logs the error to a logger named ratpack.exec.Execution.

The error handler for request processing executions forwards the exception to Context.error(Throwable).

Cleanup

The onComplete(AutoCloseable) method can be used to register actions to invoke or resources to close when the execution completes.

See Also:

ExecInterceptor, ExecInitializer, ExecController, Promise

Method Summary

Modifier and Type	Method	Description
default <O> Execution	add(com.google.common.reflect.TypeToken<O> type, O object)	Adds a registry entry that is available by the given type.
default <O> Execution	add(Class<O> type, O object)	Adds a registry entry that is available by the given type.
default Execution	add(Object object)	Adds a registry entry.
void	addInterceptor(ExecInterceptor execInterceptor, Block continuation)	Adds an interceptor that wraps the rest of the current execution segment and all future segments of this execution.
<O> Execution	addLazy(com.google.common.reflect.TypeToken<O> type, Supplier<? extends O> supplier)	Adds a lazily created entry to the registry.
default <O> Execution	addLazy(Class<O> type, Supplier<? extends O> supplier)	Adds a lazily created entry to the registry.
static Execution	current()	Provides the currently executing execution.
static Optional<Execution>	currentOpt()	Provides the currently executing execution, if any.
static ExecStarter	fork()	Used to create a new execution.
ExecController	getController()	The execution controller that this execution is associated with.
io.netty.channel.EventLoop	getEventLoop()	The specific event loop that this execution is using for compute operations.
default ExecutionRef	getParent()	A ref to the execution that forked this execution.
ExecutionRef	getRef()	A reference to this execution.
static boolean	isActive()	Whether there is currently an active bound execution.
static boolean	isBlockingThread()	Whether the current thread is a Ratpack blocking thread.
boolean	isComplete()	Indicates whether the execution has completed or not.
static boolean	isComputeThread()	Whether the current thread is a Ratpack compute thread.
static boolean	isManagedThread()	Whether the current thread is a thread that is managed by Ratpack.
default Optional<ExecutionRef>	maybeParent()	A ref to the execution that forked this execution, if it has a parent.
void	onComplete(AutoCloseable closeable)	Registers a closeable that will be closed when the execution completes.
static Operation	sleep(Duration duration)	Creates a sleep operation.
static void	sleep(Duration duration, Block onWake)	Pauses this execution for the given duration.

Methods inherited from interface ratpack.exec.registry.MutableRegistry

remove, remove

Methods inherited from interface ratpack.exec.registry.Registry

first, first, get, get, getAll, getAll, join, maybeGet, maybeGet

Methods inherited from interface ratpack.exec.registry.RegistrySpec

with

Method Detail

current

static Execution current()
                  throws UnmanagedThreadException

Provides the currently executing execution.

Returns:

the currently executing execution

Throws:

UnmanagedThreadException - if called from outside of an execution

See Also:

currentOpt()

currentOpt

static Optional<Execution> currentOpt()

Provides the currently executing execution, if any.

Returns:

the currently executing execution

Since:

1.5

See Also:

current()

fork

static ExecStarter fork()
                 throws UnmanagedThreadException

Used to create a new execution.

This method obtains the thread bound ExecController and simply calls ExecController.fork().

Returns:

an execution starter

Throws:

UnmanagedThreadException - if there is no thread bound execution controller (i.e. this was called on a thread that is not managed by the Ratpack application)

isActive

static boolean isActive()

Whether there is currently an active bound execution.

When true, current() will return an execution. When completing/closing an execution (e.g. onComplete(AutoCloseable)), this will return false but current() will still return an execution.

Returns:

whether there is currently an active bound execution

Since:

1.5

isManagedThread

static boolean isManagedThread()

Whether the current thread is a thread that is managed by Ratpack.

Returns:

whether the current thread is a thread that is managed by Ratpack

isComputeThread

static boolean isComputeThread()

Whether the current thread is a Ratpack compute thread.

Returns:

whether the current thread is a Ratpack compute thread

isBlockingThread

static boolean isBlockingThread()

Whether the current thread is a Ratpack blocking thread.

Returns:

whether the current thread is a Ratpack blocking thread

getController

ExecController getController()

The execution controller that this execution is associated with.

Returns:

the execution controller that this execution is associated with

getEventLoop

io.netty.channel.EventLoop getEventLoop()

The specific event loop that this execution is using for compute operations.

When integrating with asynchronous API that allows an executor to be specified that should be used to schedule the receipt of the value, use this executor.

Returns:

the event loop used by this execution

getRef

ExecutionRef getRef()

A reference to this execution.

Returns:

a reference to this execution

Since:

1.6

getParent

default ExecutionRef getParent()

A ref to the execution that forked this execution.

Returns:

a ref to the execution that forked this execution

Throws:

IllegalStateException - if this is a top level exception with no parent

Since:

1.6

See Also:

maybeParent()

maybeParent

default Optional<ExecutionRef> maybeParent()

A ref to the execution that forked this execution, if it has a parent.

Returns:

a ref to the execution that forked this execution

Since:

1.6

onComplete

void onComplete(AutoCloseable closeable)

Registers a closeable that will be closed when the execution completes.

Where possible, care should be taken to have the given closeable not throw exceptions. Any that are thrown will be logged and ignored.

Parameters:

closeable - the resource to close when the execution completes

isComplete

boolean isComplete()

Indicates whether the execution has completed or not.

Will return true if called during an onComplete(AutoCloseable) or ExecSpec.onComplete(Action) callback.

Returns:

whether the execution has completed or not

Since:

1.5

add

default <O> Execution add(Class<O> type,
                          O object)

Adds a registry entry that is available by the given type.

Specified by:

add in interface RegistrySpec

Type Parameters:

O - the public type of the registry entry

Parameters:

type - the public type of the registry entry

object - the actual registry entry

Returns:

this

add

default <O> Execution add(com.google.common.reflect.TypeToken<O> type,
                          O object)

Adds a registry entry that is available by the given type.

Specified by:

add in interface RegistrySpec

Type Parameters:

O - the public type of the registry entry

Parameters:

type - the public type of the registry entry

object - the actual registry entry

Returns:

this

add

default Execution add(Object object)

Adds a registry entry.

Specified by:

add in interface RegistrySpec

Parameters:

object - the object to add to the registry

Returns:

this

addLazy

default <O> Execution addLazy(Class<O> type,
                              Supplier<? extends O> supplier)

Adds a lazily created entry to the registry.

The supplier will be invoked exactly once, when a query is made to the registry of a compatible type of the given type.

Specified by:

addLazy in interface RegistrySpec

Type Parameters:

O - the public type of the registry entry

Parameters:

type - the public type of the registry entry

supplier - the supplier for creating the object when needed

Returns:

this

addLazy

<O> Execution addLazy(com.google.common.reflect.TypeToken<O> type,
                      Supplier<? extends O> supplier)

Adds a lazily created entry to the registry.

The supplier will be invoked exactly once, when a query is made to the registry of a compatible type of the given type.

Specified by:

addLazy in interface RegistrySpec

Type Parameters:

O - the public type of the registry entry

Parameters:

type - the public type of the registry entry

supplier - the supplier for creating the object when needed

Returns:

this

addInterceptor

void addInterceptor(ExecInterceptor execInterceptor,
                    Block continuation)
             throws Exception

Adds an interceptor that wraps the rest of the current execution segment and all future segments of this execution.

The given action is executed immediately. Any code executed after a call to this method in the same execution segment WILL NOT be intercepted. Therefore, it is advisable to not execute any code after calling this method in a given execution segment.

See ExecInterceptor for example use of an interceptor.

It is generally preferable to register the interceptor in the server registry, or execution registry when starting, than using this method. That way, the interceptor can interceptor all of the execution.

Parameters:

execInterceptor - the execution interceptor to add

continuation - the rest of the code to be executed

Throws:

Exception - any thrown by continuation

See Also:

ExecInterceptor

sleep

static void sleep(Duration duration,
                  Block onWake)

Pauses this execution for the given duration.

Unlike Thread.sleep(long), this method does not block the thread. The thread will be relinquished for use by other executions.

The given block will be invoked after the duration has passed. The duration must be non-negative.

Parameters:

duration - the duration this execution should sleep for

onWake - the code to resume with upon awaking

Since:

1.5

sleep

static Operation sleep(Duration duration)

Creates a sleep operation.

Unlike Thread.sleep(long), this method does not block the thread. The thread will be relinquished for use by other executions.

The given block will be invoked after the duration has passed. The duration must be non-negative.

Parameters:

duration - the duration this execution should sleep for

Since:

1.5