---
title: "27.10 std.limit"
url: https://una-lang.org/en/docs/spec/27-tasks-and-time/10-std-limit/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/27-tasks-and-time.md
---

# 27.10 std.limit

1. **The module** (ADR 0117 rule 9). In edition `0.4`, `std.limit` is an importable standard module (`spec/10 §11` rule 10), read only by a package that imports it, the mechanism by which `std.collections` is read in edition `0.5` (`spec/28 §2`); in earlier editions an import of it is U1001 at the module path. It declares:

   ```una
   pub kind Limited = | RateLimited

   pub capability Limit
     op acquire() -> Unit
       fails Limited
       accepts internal
   ```

   and exports the handler `limiter(at_most: Int, per: Int of Millisecond, waiting: Int) for Limit`, which the runtime provides, as it provides the host capabilities (`spec/05 §7`): it has no Una source, and no `handler` declaration of it exists in Core IR (`spec/09`). `with @x = limiter(...)` and a `given` line of an example install it by the rule that a `with` or a `given` names a handler (`spec/05 §9` rule 4, U3010), and `@x.acquire()` is an operation of `Limit` like any other, with its event in the trace (`spec/11 §5`) under the instance `with:limiter#<n>` or `given:<name>`.
2. **Installing.** Each installation carries three `refinement` obligations, at the arguments: `at_most >= 1`, `per >= 1` and `waiting >= 0` (U5001, U5002). Each installation is one instance with one bucket, shared by every task that uses the binding during the statement the `with` scopes over, the started tasks of a `tasks` statement inside it included (§7 rule 2); a rebinding shares it (`spec/11 §2`). A count beyond 2^64 − 1 counts as 2^64 − 1.
3. **Dynamics.** The bucket holds `at_most` tokens and refills evenly over `per` milliseconds: a burst of up to `at_most`, then one every `per` divided by `at_most`, kept by GCRA over the run's clock as the limits on grants are (§9 rule 2). `@x.acquire()` takes a token:
   - **At once** when one is left and no call waits at the bucket; otherwise it waits in the bucket's queue, served by ticket as §9 rule 3 says, an interruptible wait (§2).
   - **A full queue.** When `waiting` calls already wait, it fails at once with `RateLimited`, joining no queue; with `waiting: 0`, a call that finds no token fails at once.
   - **Deadlines.** The deadlines of the `within`s in progress (§5) and of the `for ever within` iteration (`spec/26 §7`) bound the wait. Past the earliest, no token is taken and the call fails with `RateLimited`, the one failure `Limited` has; the `for ever within` iteration observes its deadline at the operation, and a `within` at its next check point or when its expression returns, as for a request (§9 rule 4). A host stop in the body of a `for ever` (`spec/26 §6`) ends the wait the same way, with no token taken.
   - **Cancellation.** A cancellation of its task that interrupts a waiting operation (§6 rule 7, §7 rule 4) ends the call `interrupted` and takes it out of the queue; the task stops. A deadline's cut of its `tasks` statement ends it with `RateLimited` instead (§2 rule 4).
   - **Virtual time.** Under `--virtual-time` (`spec/26 §8`) a wait for a refill moves the virtual clock to the refill, or to the earliest covering deadline when that comes first, and takes no wall time, so both engines give the same outcomes, traces and readings of `Clock.now`; in a test, the clock is the test's virtual one.
   - **Natively,** the wait happens on a helper of the I/O pool while the task parks, as a request's wait at a limit does (§9 rule 3), never on the reactor; the interpreter waits on its thread.
4. **Information flow** (ADR 0117 IF5). `acquire` accepts `internal`, so it can be called under an `internal` program counter, as the started tasks of a server run once they have branched on a network result; under a program counter above it, the call is U4003 (`spec/07 §7` rule 4). `Limited` is labeled `internal`: whether a call of `acquire` fails, and its payload, carry `internal` for the program, whatever handler serves it, as the arguments that decide a host operation's failure label it (`spec/07 §7` rule 4). So `attempt @x.acquire()` gives an `internal` `Result`, a branch on it runs under an `internal` program counter, and `if error pass` and `if error fail` are U4002 (S-46, #1563). Whether a token is left depends on the timing of the code that shares the instance: the statement the `with` scopes over, or the `do` line of the example whose `given` line installs it, and, through `τ_conc` (`spec/26 §7` rule 5), the program's other tasks. So `τ` of that statement, computed as for a `within` (§5) but with the preview's `τ_conc` until §11 names the statement (§11), the handlers the statement's bindings install included, MUST flow to `internal`: U4001 at the `with` binding, or at the `given` line, otherwise, naming what raised it. That covers `waiting: 0` as well, where one task's own timing decides whether `acquire` fails.
5. **Report.** How long a call waits is timing, out of model: the report's `out_of_model` entry "waits at limits and at `start`" (§7 rule 8) covers it. A full queue becomes a value only through `RateLimited`, which rule 4 labels.
6. **Costs** (ADR 0117 Costs). An installation takes O(1). A call served at once takes O(1) under the bucket's lock, held for that work only; a call that waits takes one queue entry, joined in O(1) and left in O(1) amortized. A package that does not import `std.limit` pays nothing: the checker does not read the module, and no Core IR changes.
