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,Blockingetc. 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 viafork()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, viaPromise.async(Upstream), the resumption of work when the result becomes available is within a new execution segment. During any execution segment, thecurrent()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 anExecInterceptorto 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 namedratpack.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
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description default <O> Executionadd(com.google.common.reflect.TypeToken<O> type, O object)Adds a registry entry that is available by the given type.default <O> Executionadd(java.lang.Class<O> type, O object)Adds a registry entry that is available by the given type.default Executionadd(java.lang.Object object)Adds a registry entry.voidaddInterceptor(ExecInterceptor execInterceptor, Block continuation)Adds an interceptor that wraps the rest of the current execution segment and all future segments of this execution.<O> ExecutionaddLazy(com.google.common.reflect.TypeToken<O> type, java.util.function.Supplier<? extends O> supplier)Adds a lazily created entry to the registry.default <O> ExecutionaddLazy(java.lang.Class<O> type, java.util.function.Supplier<? extends O> supplier)Adds a lazily created entry to the registry.static Executioncurrent()Provides the currently executing execution.static java.util.Optional<Execution>currentOpt()Provides the currently executing execution, if any.static ExecStarterfork()Used to create a new execution.ExecControllergetController()The execution controller that this execution is associated with.io.netty.channel.EventLoopgetEventLoop()The specific event loop that this execution is using for compute operations.default ExecutionRefgetParent()A ref to the execution that forked this execution.ExecutionRefgetRef()A reference to this execution.static booleanisActive()Whether there is currently an active bound execution.static booleanisBlockingThread()Whether the current thread is a Ratpack blocking thread.booleanisComplete()Indicates whether the execution has completed or not.static booleanisComputeThread()Whether the current thread is a Ratpack compute thread.static booleanisManagedThread()Whether the current thread is a thread that is managed by Ratpack.default java.util.Optional<ExecutionRef>maybeParent()A ref to the execution that forked this execution, if it has a parent.voidonComplete(java.lang.AutoCloseable closeable)Registers a closeable that will be closed when the execution completes.static Operationsleep(java.time.Duration duration)Creates a sleep operation.static voidsleep(java.time.Duration duration, Block onWake)Pauses this execution for the given duration.-
Methods inherited from interface ratpack.registry.MutableRegistry
remove, remove
-
Methods inherited from interface ratpack.registry.Registry
first, first, get, get, getAll, getAll, join, maybeGet, maybeGet
-
Methods inherited from interface ratpack.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 java.util.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
ExecControllerand simply callsExecController.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 returnfalsebutcurrent()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:
java.lang.IllegalStateException- if this is a top level exception with no parent- Since:
- 1.6
- See Also:
maybeParent()
-
maybeParent
default java.util.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(java.lang.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
trueif called during anonComplete(AutoCloseable)orExecSpec.onComplete(Action)callback.- Returns:
- whether the execution has completed or not
- Since:
- 1.5
-
add
default <O> Execution add(java.lang.Class<O> type, O object)
Adds a registry entry that is available by the given type.- Specified by:
addin interfaceRegistrySpec- Type Parameters:
O- the public type of the registry entry- Parameters:
type- the public type of the registry entryobject- 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:
addin interfaceRegistrySpec- Type Parameters:
O- the public type of the registry entry- Parameters:
type- the public type of the registry entryobject- the actual registry entry- Returns:
- this
-
add
default Execution add(java.lang.Object object)
Adds a registry entry.- Specified by:
addin interfaceRegistrySpec- Parameters:
object- the object to add to the registry- Returns:
- this
-
addLazy
default <O> Execution addLazy(java.lang.Class<O> type, java.util.function.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:
addLazyin interfaceRegistrySpec- Type Parameters:
O- the public type of the registry entry- Parameters:
type- the public type of the registry entrysupplier- the supplier for creating the object when needed- Returns:
- this
-
addLazy
<O> Execution addLazy(com.google.common.reflect.TypeToken<O> type, java.util.function.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:
addLazyin interfaceRegistrySpec- Type Parameters:
O- the public type of the registry entry- Parameters:
type- the public type of the registry entrysupplier- the supplier for creating the object when needed- Returns:
- this
-
addInterceptor
void addInterceptor(ExecInterceptor execInterceptor, Block continuation) throws java.lang.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
ExecInterceptorfor 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 addcontinuation- the rest of the code to be executed- Throws:
java.lang.Exception- any thrown bycontinuation- See Also:
ExecInterceptor
-
sleep
static void sleep(java.time.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 foronWake- the code to resume with upon awaking- Since:
- 1.5
-
sleep
static Operation sleep(java.time.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
-
-