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

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      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​(java.lang.Class<O> type, O object)
      Adds a registry entry that is available by the given type.
      default Execution add​(java.lang.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, java.util.function.Supplier<? extends O> supplier)
      Adds a lazily created entry to the registry.
      default <O> Execution addLazy​(java.lang.Class<O> type, java.util.function.Supplier<? extends O> supplier)
      Adds a lazily created entry to the registry.
      static Execution current()
      Provides the currently executing execution.
      static java.util.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 java.util.Optional<ExecutionRef> maybeParent()
      A ref to the execution that forked this execution, if it has a parent.
      void onComplete​(java.lang.AutoCloseable closeable)
      Registers a closeable that will be closed when the execution completes.
      static Operation sleep​(java.time.Duration duration)
      Creates a sleep operation.
      static void sleep​(java.time.Duration duration, Block onWake)
      Pauses this execution for the given duration.
    • Method Detail

      • 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()
      • 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:
        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
      • 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:
        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​(java.lang.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​(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:
        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,
                              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:
        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 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 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:
        java.lang.Exception - any thrown by continuation
        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 for
        onWake - 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