Home / Docs / Specification / 27. Tasks and time

27.5 within

Release v0.4.0
  1. Grammar (ADR 0117 rule 5). In edition 0.4, a statement's expression MAY take a deadline after its with clause, and attempt MAY take one:

    ebnf
    handled      = line_expr [ with_clause ] [ "within" add_expr ] NEWLINE [ INDENT handling { handling } DEDENT ] ;
    attempt_expr = "attempt" postfix [ "within" add_expr ] ;
    • The word. within is the word of a deadline right after for ever (spec/26 §7) and right after a token that ends an expression: a name, a capability reference, a literal, ) or ]. Anywhere else it stays reserved (U0103), so it is never a name. Before edition 0.4 it is a name, and a name after an expression is U0101.
    • After attempt. In let r = attempt f(x) within d, the attempt takes the deadline, so its Result holds the time-out. A with clause then follows the deadline: attempt f(x) within d with @h = @g. A handled whose expression is an attempt with its own within takes no second one (U0101).
    una
    import std.time (millisecond, second)
    
    let quote = fetch_quote() within 2 * second
      if error use cached_quote
  2. The deadline. d is an Int of Millisecond, with Millisecond of std.time: a deadline in seconds, a unitless Int or another unit is U2028, and a type that is not an integer is U2001. It MUST be at least 1, a refinement obligation at d (spec/12 §3): within 0 * millisecond is U5001. It is evaluated first, before the with clause and the expression.

  3. The failure kinds. std.time declares pub kind Timed[E] = TimedOut | Failed(error: E) and pub kind Deadline = | Expired, a sum of one variant (spec/02 §2). When e can fail with E, e within d fails with Timed[E]: TimedOut when the deadline passed, Failed(error: x) when e failed with x in time. When e cannot fail, it fails with Deadline.Expired. attempt e within d gives Result[T, Timed[E]], or Result[T, Deadline]. A variant resolves by the kind its context gives (spec/10 §11 rule 3).

  4. Handling (spec/06 §3). e within d can always fail, so without an if error clause, and outside attempt, it is U3007. if error use v and if error fail V(...) take any failure. if error pass is legal when the function's error kind declares a variant TimedOut without fields, and e either cannot fail or fails with that same kind: TimedOut passes as the function's TimedOut, and Failed(error: x) as x. Otherwise it is U3008. No fails clause takes type arguments.

    una
    pub kind RouteError = NoPath | TimedOut
    
    plan(graph: Graph, start: Node, goal: Node) -> Route
      fails RouteError
    =
      let route = shortest(graph, start: start, goal: goal) within 50 * millisecond
        if error pass                       -- TimedOut passes as RouteError.TimedOut
      route
  5. Dynamics.

    • The deadline is d after the run's clock reads at the within, real or virtual (spec/26 §8). It belongs to this within.
    • In nanoseconds (ADR 0116 amendment, P13). On the real clock the deadline is armed on a reading of the monotonic clock in nanoseconds, and every reading compared with it is one too: e within d has exactly d from the moment it was armed, to the resolution of the system's clock and sleep. A reading in whole milliseconds would give it between d - 1 and d milliseconds, by the phase within a millisecond that earlier code left, possibly code on secret data. The timer thread fires each deadline at its own nanosecond: its timing wheel counts nanoseconds, with slots of one nanosecond at its finest level, and the thread sleeps until the wheel's next expiration, never to the end of a millisecond. Virtual time moves in whole milliseconds, and Clock.now reads milliseconds, as before.
    • Past the deadline, every interruptible operation waiting inside e, and every one that starts later, fails with its time-out failure, HttpError.TimedOut for Http (§6); e is canceled at its next check point (spec/11 §7): each call, operation and loop iteration, as a canceled task is (spec/19 §6 rule 4). An operation in progress completes first, its handler's code included. Nothing inside it runs further: no handling clause, no inner within. Tasks started inside e, by together or together for, are canceled with it, and e ends once they have stopped. A for ever inside e ends as after a failure: its on stop runs on the state from before the loop, shielded from the deadline, and the cancellation then goes on (ADR 0116 rule 15). The cancellation leaves every frame of e as a failure does, releasing the values each one holds, so a program whose deadlines keep passing holds no more memory than one whose expressions fail.
    • The outcome. e within d succeeds only when e returns before its deadline, checked once more when e returns: an expression that returns at its deadline, or later, has missed it. Otherwise the result is TimedOut or Expired, even when e returned a value or a failure, which is dropped. In every outcome but success, e's edit arguments keep their values from before the statement, as for any failure (spec/17 §7 rule 1), and effects already performed stay (rule 2).
    • Nesting. An inner within whose own deadline has not passed never reports a time-out because an outer one passed: the outer cancellation goes through it, and only the outermost within whose deadline passed reports its time-out.
    • Virtual time. Under virtual time only the run's own waits move the clock (spec/26 §8), so a deadline passes inside e only through such a wait, as std.testing.elapse in a test's handler.
  6. Interruption (ADR 0117 rule 4). In this edition the interruptible operations are those of Http. A request waits no longer than the earliest deadline that covers it, of a within or of a for ever within iteration, and fails with HttpError.TimedOut when it passes: its exchange ends at that deadline, at its next I/O step, on its helper or, parked on the reactor, on its task (§2 rules 3 and 4). What a request sent before its deadline passed stays sent, on either path, so an interrupted request is an effect in doubt.

    • Never before the deadline. An interruptible operation that a covering deadline ends, with its time-out failure (RateLimited for acquire of std.limit, §10), returns only once the run's clock has reached that deadline, in both engines, whatever unit a wait inside it counts in: a wait at a limit that reads the deadline in whole milliseconds reads the first millisecond at or after it, never one before. So when a within's deadline cut an operation inside e, the within always finds its deadline passed when e returns, and times out with its timeout event (rule 7): a cut operation's TimedOut is never the failure of a within that succeeded in time.
  7. Trace. A within that times out appends one event {"seq": n, "outcome": {"kind": "timeout"}}, with the task of its task and no operation, after the outcomes of the operations it interrupted, whose own events show their time-out failures (spec/11 §5), unless quiet code that is not quiet timing performed them (below). An operation in progress completes (spec/19 §6 rule 4): the code of a handler serving an operation inside e is not cut by a deadline that was running when the operation began, so its event keeps its outcome, and e is canceled at the next check point after it. The outcome {"kind": "interrupted"} of ADR 0117 rule 10 belongs to an interruptible operation whose task is canceled while it waits, which first of brings (ADR 0117 amendment of 2026-10-19). Code inside a quiet expression appends no timeout and no cancelled event of its own, nor, unless the mark is quiet timing (spec/09 §2), the events of the operations it performs in a run's trace, and takes no seq for them (S-42, spec/26 §6 rule 4).

    • Canceled tasks. When the cut stops a block of together or together for, or a first of (§6), inside e, every task of that block that has not returned ends with its event {"seq": n, "task": "<path>", "outcome": {"kind": "cancelled"}} (spec/19 §7 rule 3), whether it had started or the cut kept it from starting, in the order of the tasks' paths, after the events the block's tasks wrote, and before the within's timeout event. The start of each task is a check point for this rule, in both engines. So the events do not depend on the number of workers, nor on how many tasks had started: in both engines, a task that had not returned when the deadline passed gets exactly one cancelled event.
    • Timing information (ADR 0116 rule 21, IF5). Whether a within timed out, so its timeout event and the cancelled events of its tasks, and which tasks had returned when it did, depend on timing: on τ(e), which may be above public. The trace records them as it records every outcome (spec/11 §5), under the accepted trace design of ADR 0116, as it records the timeout events of for ever within: an operator who reads a trace of a within whose τ is secret reads a bit of secret timing. The report's timing list names every such within (rule 9). Under virtual time a deadline passes inside e only through the run's own waits, a wait for a refill at a limit among them (§10), and both engines read the clock at every check point, so they cut e at the same one: these events, and the trace, are the same in every run and in both engines (§8 rule 3).
  8. Information flow (ADR 0117 IF2). Let t = τ(e), the timing label of spec/26 §7 rule 5, computed by the same rule, with ℓ(d) included and with τ_conc(e) as §11 computes it.

    • The failure is labeled t, joined with the label of e's own failure: if error use v runs under it and its value is raised by it (spec/07 §7 rule 3), and if error pass and if error fail are U4002 when it is above public.
    • The places e updates, its edit arguments and the target of an assignment, MUST be labeled at least t (U4001 at the place, with the within as a related location).
    • The timing floor. Every operation inside e, and every call inside e with effects, is checked as if it ran under pc ⊔ t: the sinks of spec/07 §7 rule 4 (U4003), and the effect bound of each call (U4002). Failures inside e keep the ordinary program counter.
    • Residue. t includes L_res (spec/26 §7 rule 5, item 6), whether or not e makes a request: in a program whose started tasks or races make requests, every within is at least internal. A message about a label that L_res raised names the construct whose requests can be left running.
    • Interruptible operations. An Http operation that e can reach declares its failure internal (spec/24 §5), so t above internal is U4001 at the within (ADR 0116 IF8). A time-out over Http is therefore at least internal: it can be recovered from with use, attempt or fail under an internal handler, never passed on to a public failure.
    • Computing t. t depends on the whole package's call graph, so the checker computes it from a probe of its own checks, repeated until no label rises, and confirms after checking that no label it used was too low (U8001 otherwise).
  9. Report (ADR 0117 rule 13). The report's information.timing list (spec/13 §6) holds each within whose t is above public, with its function and t, beside each for ever within.

  10. Core (spec/09). e within d is within(d, C_t, [C_w]) e, with d an atom bound before it.

  11. Costs. A within arms a timer in O(1) and ends it in O(1), in a timing wheel of 11 levels of 64 slots over nanoseconds of the monotonic clock, the finest slot one nanosecond wide, which covers about 584 years (ADR 0117 Costs; ADR 0116 amendment, P13). A timer fires in O(1) amortized: it moves down the levels at most 10 times, each move O(1), inside passes the timer thread makes at the start of a slot that holds it. Removal is eager: a canceled timer leaves the wheel at once, so after any history of armed and canceled timers the wheel holds only its live timers. Under the real clock, one thread per run, started before main (§1 rule 4), fires the timers, with one mutex that each within takes to arm and to cancel its timer. The thread wakes only at the next expiration, which is always a live timer's: its exact deadline, or the start of a slot that holds it, where it is cascaded, at most 10 times per timer and shared by the timers of that slot; when a timer earlier than that moment is armed; and when the timer it waits for is canceled, to wait for the next one instead. Arming moves the wheel's time to the moment of arming, so the moments a timer wakes the thread follow from its own arming moment and deadline, never from earlier code. Canceled timers cause no later wake; a task's check points see a passed deadline as a cancellation, so the check point's fast path is that of a task (ADR 0102). In the interpreter, each check point inside a within reads the clock once.