Package jline.util

Class LineTimeout

java.lang.Object
jline.util.LineTimeout
public final class LineTimeout extends Object
Cooperative wall-clock budget for one solve (port of MATLAB lineTimeoutArm / lineTimeoutExceeded / lineTimeoutTripped / lineTimeoutTrip).

The budget lives on a PER-THREAD deadline stack, so two solvers running concurrently on different threads never see each other's deadline, and a nested or composite solve draws on its caller's budget instead of restarting it:

  • arm(double) pushes a frame whose deadline is the EARLIER of the own budget and the enclosing frame's deadline (an inner solve can tighten the budget but never extend it), and returns a LineTimeout.Scope that pops it on close() (use try-with-resources);
  • an infinite own budget with no enclosing frame pushes nothing;
  • exceeded() is the checkpoint: true when the top frame's deadline has passed, and it marks that frame TRIPPED;
  • a tripped frame passes the mark to its parent when it pops, so an enclosing composite (AUTO, LN, ENV) sees that an inner solve stopped early.
The result flag (SolverResult.timedOut) is taken from the tripped latch, never from "elapsed > budget": a run that completed its loop and then overran while post-processing is a complete result.

Deep utilities with no options argument (multichoose, the state-space generators) call checkpoint(String), which throws LINE:numerical:Timeout, since a partially enumerated state space would silently yield wrong results.

Worker threads do not inherit the stack: a pool captures current() on the submitting thread and each task arms it with arm(Deadline); the submitter calls trip() when a task reports it stopped on the budget.

Clock comparisons use now - deadline > 0, which is correct across a System.nanoTime() wrap-around.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    LineTimeout.Deadline
    An absolute deadline, transferable to worker threads.
    static final class 
    LineTimeout.Scope
    The frame a arm(double) call pushed; closing it pops the frame.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    TIMEOUT_ID
    The error id this class raises: LINE:numerical:Timeout.

  • Method Summary

    Modifier and Type
    Method
    Description
    static LineTimeout.Scope
    arm(double budgetSeconds)
    Arm a budget of budgetSeconds for the calling solve.
    static LineTimeout.Scope
    arm(LineTimeout.Deadline d)
    Arm a deadline captured on another thread (see current()).
    static void
    check(String context)
    Non-amortised checkpoint for computations that have no valid partial result: throws LINE:numerical:Timeout when the budget has run out.
    static void
    checkpoint(String context)
    Amortised checkpoint for hot loops with no valid partial result: polls the clock once every 256 calls and throws LINE:numerical:Timeout when the armed deadline has passed.
    static LineTimeout.Deadline
    current()
    The armed deadline of this thread, or null when no budget is armed.
    static boolean
    exceeded()
    Checkpoint: true when the armed deadline has passed, in which case the top frame is marked tripped.
    static boolean
    exceeded(int stride)
    Amortised checkpoint for tight loops: reads the clock once every stride calls on this thread.
    static boolean
    isArmed()
    True when a budget is armed on this thread.
    static boolean
    isTimeout(Throwable t)
    True when t, or any throwable in its cause chain, is a LINE:numerical:Timeout.
    static double
    remaining()
    Seconds left in the armed budget; +Inf when none is armed (may be negative).
    static long
    remainingCeilSeconds()
    The JSIM -maxtime / CLI seconds for the remaining budget, rounded up and at least 1; -1 when no budget is armed.
    static LineNumericalException
    timeoutError(String message)
    The LINE:numerical:Timeout exception, with the given message.
    static void
    trip()
    Mark the top frame tripped without reading the clock: used when an engine handed the remaining budget (a subprocess, a worker thread) reports that it stopped on it.
    static boolean
    tripped()
    True when the top frame was tripped by a checkpoint or by trip().

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • TIMEOUT_ID

      public static final String TIMEOUT_ID
      The error id this class raises: LINE:numerical:Timeout.
      See Also:

  • Method Details

    • arm

      public static LineTimeout.Scope arm(double budgetSeconds)
      Arm a budget of budgetSeconds for the calling solve. The frame holds the earlier of this budget and the enclosing frame's deadline. A non-finite or non-positive budget pushes a frame only when an enclosing frame exists (sharing its deadline, with its own tripped latch).

    • arm

      public static LineTimeout.Scope arm(LineTimeout.Deadline d)
      Arm a deadline captured on another thread (see current()). A null deadline behaves as an infinite budget.

    • current

      public static LineTimeout.Deadline current()
      The armed deadline of this thread, or null when no budget is armed.

    • isArmed

      public static boolean isArmed()
      True when a budget is armed on this thread.

    • remaining

      public static double remaining()
      Seconds left in the armed budget; +Inf when none is armed (may be negative).

    • exceeded

      public static boolean exceeded()
      Checkpoint: true when the armed deadline has passed, in which case the top frame is marked tripped. False when no budget is armed.

    • exceeded

      public static boolean exceeded(int stride)
      Amortised checkpoint for tight loops: reads the clock once every stride calls on this thread.

    • tripped

      public static boolean tripped()
      True when the top frame was tripped by a checkpoint or by trip().

    • trip

      public static void trip()
      Mark the top frame tripped without reading the clock: used when an engine handed the remaining budget (a subprocess, a worker thread) reports that it stopped on it. No-op when no budget is armed.

    • timeoutError

      public static LineNumericalException timeoutError(String message)
      The LINE:numerical:Timeout exception, with the given message.

    • isTimeout

      public static boolean isTimeout(Throwable t)
      True when t, or any throwable in its cause chain, is a LINE:numerical:Timeout. A timeout is final: a caller with a fallback (another engine, another AUTO candidate) must not retry.

    • check

      public static void check(String context)
      Non-amortised checkpoint for computations that have no valid partial result: throws LINE:numerical:Timeout when the budget has run out.

    • checkpoint

      public static void checkpoint(String context)
      Amortised checkpoint for hot loops with no valid partial result: polls the clock once every 256 calls and throws LINE:numerical:Timeout when the armed deadline has passed. The stride is low because callers do heavy matrix work between calls (multichoose concatenations), so a large stride overshoots the budget by minutes.

    • remainingCeilSeconds

      public static long remainingCeilSeconds()
      The JSIM -maxtime / CLI seconds for the remaining budget, rounded up and at least 1; -1 when no budget is armed.