Interface InvocationCompletionScope

All Superinterfaces:
AutoCloseable
public interface InvocationCompletionScope extends AutoCloseable
Host-owned physical lifetime spanning decode, root invocation, tracked work and encoding. Reply timeout/cancellation is independent of physical completion. Implementations serialize CALL context access and never treat cancellation of an arbitrary application future as worker exit.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    abortBeforeTarget()
    Aborts only an invocation whose root has never entered application decoding or target code.
    default void
    addResultFinalizer(InvocationResultFinalizer finalizer)
    Registers one host finalizer before actual application body entry.
    <T> T
    call(Callable<T> action)
    Runs root application entry exactly once and observes its logical result before detaching context.
    void
    close()
    Marks actual kernel encode/boundary exit.
    default <T> T
    context(Class<T> type)
    Reads an installed host attachment under the current invocation's serial CALL ownership.
    <T> CompletionStage<T>
    continueInContext(Callable<T> action)
    Serializes a continuation under the same captured context without creating a second root.
    default <T> Optional<T>
    findContext(Class<T> type)
    Finds an exact-type attachment only inside this invocation's actual owned CALL.
    CompletionStage<Object>
    logicalResult()
    Returns a host-owned mirror of the logical root result observed inside the captured context.
    default void
    markApplicationEntry()
    Freezes host registration immediately before the generated application body executes.
    CompletionStage<Void>
    physicalCompletion()
    Returns read-only completion after boundary exit, root exit, all tracked work and cleanup.
    default <T> void
    putContext(Class<T> type, T value)
    Installs a bounded exact-type host attachment before application body entry.
    void
    requestCancellation()
    Signals cooperative cancellation; does not interrupt, undo or close application ownership.
    default boolean
    supportsResultFinalizers()
    Reports whether this implementation supports trusted result finalizers and typed attachments.

  • Method Details

    • call

      <T> T call(Callable<T> action) throws Exception
      Runs root application entry exactly once and observes its logical result before detaching context.
      Type Parameters:
      T - root result type
      Parameters:
      action - decoding and actual target entry
      Returns:
      logical result, possibly a stage
      Throws:
      Exception - if application entry fails

    • continueInContext

      <T> CompletionStage<T> continueInContext(Callable<T> action)
      Serializes a continuation under the same captured context without creating a second root.
      Type Parameters:
      T - result type
      Parameters:
      action - encoding or another host continuation
      Returns:
      completion after continuation context has actually exited

    • supportsResultFinalizers

      default boolean supportsResultFinalizers()
      Reports whether this implementation supports trusted result finalizers and typed attachments.
      Returns:
      false for compatibility-only ownership adapters

    • addResultFinalizer

      default void addResultFinalizer(InvocationResultFinalizer finalizer)
      Registers one host finalizer before actual application body entry. Registration is bounded and frozen at body entry; applications never receive this installer.
      Parameters:
      finalizer - trusted non-null finalizer

    • putContext

      default <T> void putContext(Class<T> type, T value)
      Installs a bounded exact-type host attachment before application body entry.
      Type Parameters:
      T - attachment type
      Parameters:
      type - exact attachment key
      value - non-null value assignable to type

    • context

      default <T> T context(Class<T> type)
      Reads an installed host attachment under the current invocation's serial CALL ownership.
      Type Parameters:
      T - attachment type
      Parameters:
      type - exact installed attachment key
      Returns:
      invocation-owned attachment, never a mutable attachment registry

    • findContext

      default <T> Optional<T> findContext(Class<T> type)
      Finds an exact-type attachment only inside this invocation's actual owned CALL. Empty means a missing key; unsupported, outside-owner and closed access must fail instead.
      Type Parameters:
      T - attachment type
      Parameters:
      type - exact attachment key
      Returns:
      read-only optional attachment, never a mutable registry

    • markApplicationEntry

      default void markApplicationEntry()
      Freezes host registration immediately before the generated application body executes. Compatibility-only adapters without finalizers may ignore this notification.

    • logicalResult

      CompletionStage<Object> logicalResult()
      Returns a host-owned mirror of the logical root result observed inside the captured context. The kernel must await this mirror rather than invoke application-controlled future conversion hooks. Cancellation of a result may complete this view exceptionally while physical ownership remains retained.
      Returns:
      read-only host logical result completion

    • physicalCompletion

      CompletionStage<Void> physicalCompletion()
      Returns read-only completion after boundary exit, root exit, all tracked work and cleanup.
      Returns:
      physical completion; cancellation of this view cannot release owned resources

    • requestCancellation

      void requestCancellation()
      Signals cooperative cancellation; does not interrupt, undo or close application ownership.

    • abortBeforeTarget

      void abortBeforeTarget()
      Aborts only an invocation whose root has never entered application decoding or target code.

    • close

      void close()
      Marks actual kernel encode/boundary exit. Idempotent; never fabricates physical completion.
      Specified by:
      close in interface AutoCloseable