Module io.github.teceli.resiliencia.patterns
Package io.github.teceli.resiliencia.patterns.timeout

Record Class Timeout<T>

java.lang.Object
java.lang.Record
io.github.teceli.resiliencia.patterns.timeout.Timeout<T>
All Implemented Interfaces:
Resilient<T>
public record Timeout<T>(String name, Duration timeout, boolean cancelOnTimeout, List<ResilienceEvent.Listener> listeners, Clock clock) extends Record implements Resilient<T>
Timeout pattern: execute an operation on a virtual thread and bound how long the caller waits for it. When the deadline passes and cancelOnTimeout is true (the default), the worker thread is interrupted — a real cancellation signal, not polling. Either way the caller gets a ResilientTimeoutException (or Outcome.TimedOut via outcome(io.github.teceli.resiliencia.core.api.Resilient.Operation<T>)) immediately once the deadline passes. Whether the operation actually stops depends on it responding to interruption; the caller is unblocked either way. The deadline is enforced against real elapsed time; the Clock is used only for event timestamps, so a manual clock in tests affects observability data, not the deadline. Immutable and reusable: each withX method returns a new, independently usable Timeout instance rather than mutating this one.

  • Constructor Details

    • Timeout

      public Timeout(String name, Duration timeout, boolean cancelOnTimeout, List<ResilienceEvent.Listener> listeners, Clock clock)
      Creates an instance of a Timeout record class.
      Parameters:
      name - the value for the name record component
      timeout - the value for the timeout record component
      cancelOnTimeout - the value for the cancelOnTimeout record component
      listeners - the value for the listeners record component
      clock - the value for the clock record component

  • Method Details

    • of

      public static <T> Timeout<T> of(String name, Duration timeout)
      A Timeout with the given deadline, ready to use as-is or refine further via withX methods. There is no default duration: a timeout is always an explicit business decision.
      Parameters:
      name - identifier used in every TimeoutEvent emitted by this instance. Not enforced unique across instances — there is no global registry to check against.

    • withTimeout

      public Timeout<T> withTimeout(Duration timeout)
      How long the caller waits before the operation is considered timed out. Must be positive.

    • withCancelOnTimeout

      public Timeout<T> withCancelOnTimeout(boolean cancelOnTimeout)
      Whether the operation's virtual thread is interrupted when the deadline passes. Default: true. Set to false to let the operation finish naturally in the background — the caller still receives the timeout exception immediately either way — useful when the operation holds resources that must be released cleanly rather than abandoned mid-interruption.

    • withListener

      public Timeout<T> withListener(ResilienceEvent.Listener listener)
      Add a listener notified of every TimeoutEvent emitted by this instance. Listener exceptions are logged and otherwise ignored — a broken listener never affects the outcome.

    • withClock

      public Timeout<T> withClock(Clock clock)
      Use a custom Clock instead of the system clock for event timestamps.

    • patternName

      public String patternName()
      Description copied from interface: Resilient
      The name of this pattern, e.g. "retry", "timeout", "circuit-breaker". Used for identification (e.g. by Policy) without coupling to concrete pattern types. Defaults to "custom" for user-defined Resilient implementations.
      Specified by:
      patternName in interface Resilient<T>

    • patternKind

      public PatternKind patternKind()
      Description copied from interface: Resilient
      The kind of this pattern, used for internal comparisons (e.g. Policy order validation). Unlike Resilient.patternName(), which is a free-form observability label, this is a closed enum the library can reason about exhaustively. Defaults to PatternKind.CUSTOM for user-defined Resilient implementations.
      Specified by:
      patternKind in interface Resilient<T>

    • call

      public T call(Resilient.Operation<T> operation) throws ResilientException
      Description copied from interface: Resilient
      Execute an operation with resilience guarantees. May throw ResilienciaException or a specific pattern exception.
      Specified by:
      call in interface Resilient<T>
      Throws:
      ResilientException

    • outcome

      public Outcome<T> outcome(Resilient.Operation<T> operation)
      Description copied from interface: Resilient
      Execute an operation and capture the result or failure as an Outcome. Never throws for a recorded Exception — always returns Success, Failure, or a pattern-specific outcome. An Error thrown by the operation propagates uncaught instead of being captured as a Failure: fatal JVM conditions (e.g. OutOfMemoryError) should not be treated as a recoverable result.
      Specified by:
      outcome in interface Resilient<T>

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • name

      public String name()
      Returns the value of the name record component.
      Returns:
      the value of the name record component

    • timeout

      public Duration timeout()
      Returns the value of the timeout record component.
      Returns:
      the value of the timeout record component

    • cancelOnTimeout

      public boolean cancelOnTimeout()
      Returns the value of the cancelOnTimeout record component.
      Returns:
      the value of the cancelOnTimeout record component

    • listeners

      public List<ResilienceEvent.Listener> listeners()
      Returns the value of the listeners record component.
      Returns:
      the value of the listeners record component

    • clock

      public Clock clock()
      Returns the value of the clock record component.
      Returns:
      the value of the clock record component