---
title: "27.5 within"
url: https://una-lang.org/en/docs/spec/27-tasks-and-time/5-within/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/27-tasks-and-time.md
---

# 27.5 within

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.
