Home / Docs / Specification / 27. Tasks and time

27.9 Limits on grants

Release v0.4.0
  1. Syntax (ADR 0117 rule 8). In edition 0.4, an http grant MAY carry limits. In ita.una they are lines under the grant (spec/30 §2):

    ebnf
    limit_line = "at" "most" int_lit ( "per" ( "second" | "minute" | "hour" ) | "at" "once" ) NEWLINE
               | "waiting" "at" "most" int_lit NEWLINE ;
    una
    run
      grants
        http "https://api.payments.example" get, post
          at most 100 per minute
          at most 8 at once
          waiting at most 1000

    In the text form of a grant spec (spec/13 §5), as --grant takes it, they are suffixes after the methods, each ; and one of <n>/second, <n>/minute, <n>/hour, <n>/once and waiting=<n>, in any order: http:https://api.payments.example:get,post;100/minute;8/once;waiting=1000.

    • Errors. Each of these is U7008 at its line in ita.una, and makes a --grant spec invalid, a usage error: a limit line of another form, or one with lines below it; a count below 1 or above 2^31 − 1; a limit on a grant other than http; a kind of limit given twice on one grant, two rates counting as one kind whatever their periods.
    • Editions. Limits exist in edition 0.4 and later only: una.toml (editions 0.1 to 0.3) has no form of them, and a limited --grant for a package of an earlier edition, or for an executable that embeds no L_lim (rule 5), is a usage error, exit code 2, before main starts.
  2. Meaning.

    • Per period: at most n requests per second, minute or hour, in a burst of up to n, then one every period divided by n: a token bucket kept by GCRA, the generic cell rate algorithm, over the run's clock (spec/26 §8): the monotonic clock from the run's start, or the virtual clock of --virtual-time. A wait for a refill is a wait on time: under virtual time, where a host operation runs without parking, it moves the virtual clock to the refill, or to the request's deadline when that comes first (rule 4), so both engines give the same outcomes and readings of Clock.now, and the run takes no wall time to wait.
    • At once: at most n requests of the grant in flight.
    • Waiting: at most n requests waiting at the grant's limits, 1024 without the line.
    • Several grants. A request is charged to every grant that allows it (spec/24 §2 rule 2), so a broader grant without limits does not bypass a narrower one with limits. Each hop of a redirect chain (spec/24 §2 rule 3) is a request of its own, charged to the grants that allow its target.
    • Below every handler. The limits are enforced in the host layer that both engines share, below every handler and every rebinding: a rebinding shares the instance (spec/11 §2), so with @x = @y and with @x = @y[ops] stay limited.
    • Scope. Limits are per run: several processes, or a restart, each have their own.
  3. No deadlock.

    • A request takes the tokens and slots of every grant that allows its target all at once, or none, holds its slots while it is in flight, and releases them when its response is read, before a redirect asks for its own.
    • A request holds nothing while it waits, and a request that holds slots never waits for a limit, so no cycle of waits can form.
    • First come, first served. A request that must wait gets a ticket, and is served when, for every limited grant it needs, it has the lowest ticket among that grant's waiters and the grant has a token and a slot free. A new request is served at once only when no request waits at any grant it needs. So the waiter with the lowest ticket waits only for capacity, and no waiter starves.
    • A request in a run where a grant carries limits never parks on the reactor: it runs on a helper of the I/O pool (§2 rule 3), and holds its slots until the helper returns, so the count in flight is never understated; and its wait at a limit holds its helper (spec/24 §4 rule 4). An exchange whose task was canceled ends at its next I/O step (§2 rule 4, ADR 0116 amendment P9, ADR 0117 amendment of 2026-10-27), and its helper returns then: its slots are released at that moment, not when the peer would have answered, and a request waiting for them before that still waits.
  4. Waiting. A request over a limit waits in the grant's queue, an interruptible wait:

    • A full queue. When a queue it must join holds waiting requests, it fails at once with HttpError.RateLimited, a variant HttpError has in edition 0.4 and later only, after Interrupted (spec/24 §1 rule 3). The interpreter runs started tasks and the branches of a race one at a time, with host operations on its one thread (§1 rule 5, §8 rule 2), and so does native code under --virtual-time (§8 rule 3): there a grant never has two requests in flight or one waiting, so a full queue, and its RateLimited, occur only natively on the real clock, one of the outcomes the timing allows (§8 rule 4), and in the interpreter in a run that serves live peers and has a tasks statement, whose requests on helper threads and the one on its thread share the run's limits and can wait at them together (§8 rule 2, ADR 0117 amendment of 2026-11-09).
    • Time. --http-timeout covers the time it waits (spec/24 §4 rule 2), and so do the deadlines of a within (§5) and of a for ever within iteration (spec/26 §7): past the earliest, it fails with HttpError.TimedOut, without being sent.
    • Cancellation and stops. A cancellation of its task that interrupts a waiting operation (§6 rule 7, §7 rule 4) ends it interrupted and takes it out of the queue, never sent, which a deadline's cut of its tasks statement does not: the wait ends at that deadline with its time-out failure (§2 rule 4); a host stop in the body of a for ever ends it with HttpError.Interrupted (spec/26 §6).
  5. Information flow (ADR 0117 IF4). Whether a queue is full depends on when every request on its grant was made. A grant's bucket and slots are shared by every request of the run, so the time between two requests counts too (ADR 0116 P10, P11). L_lim is the meet of two labels, each of which covers that history:

    • P10's, over the ancestors: the join, over every site s that performs an operation of Http, of τ⁰ of the body of every node from which the function holding s can be reached in the call graph of ADR 0116 P1, that function included (functions, the operations of handlers, which a call reaches through an operation of the handler's capability, and every lambda, which a call of a function value reaches), and of τ_conc at s (§11). Code that runs between two requests of one task lies in the body of such an ancestor of the later request, or in what it calls. At a site in a function's body, τ_conc never exceeds the ancestors' τ⁰.
    • P11's, over the code between requests (issue #1155): the join of Gap(f) over every function, operation of a handler and lambda f that can reach a request, of the driver's gaps in a driven run (all of τ⁰(step), Suf(init) ⊔ Pre(step) and Pre(on_stop)), and of τ_conc at every site. Pre(f), Suf(f) and Gap(f) are the labels of the code from f's entry to its first request, from a request to its exit, and between two of its requests, over a control-flow graph of f's Core IR whose nodes are its steps of evaluation (spec/11): failure edges lead from each step that can fail to its handling clause or to the exit, every step inside e within d has an edge to the deadline's cut, loops have their back edges, start and the task constructs are calls of their tasks, and a prelude function that applies a function argument takes the summaries of every lambda, with τ⁰ of its arguments in its Gap. A call that reaches a request adds its callee's Pre, Suf and Gap; a loop whose body reaches a request counts its whole body; within one strongly connected component of the call graph every summary is τ⁰ of the component's bodies. Gap also joins the label of the failure of every step that can fail, and the whole τ⁰ of every step inside a within with the label its time-out carries, from which a request can be reached, since they decide whether a later request happens. Code before a run's first request that decides nothing, as let spent = crunch(key), is not counted: every bucket starts full. A type that holds a type parameter, a binding whose label Core IR does not give, or a callee it does not hold counts as ⊤, and P10's label then decides.

    Both labels are sound, so their meet is. The checker builds Core IR for P11 only when P10's label is above internal. L_lim also joins L_res (spec/26 §7 rule 5, item 6), since a request left on a helper by a canceled task holds its slots, and the helper, until its exchange returns. RateLimited, and the TimedOut of a wait at a limit, are labeled with the join of internal and L_lim, so a program whose grants carry limits MUST have L_lim at most internal:

    • una check reports U4001, when a grant of run grants carries limits and L_lim is above internal, at each Http site whose own P10 label is above internal in a body whose Gap is above it, or at every such site when no body's Gap is; the message names the code between two requests that raised it (in the site's own function when that one did), the driver's gap, the tasks that can run beside it when τ_conc raised it, or the construct whose requests can be left running when L_res raised it;
    • una build embeds L_lim in the executable of an edition 0.4 package;
    • una run and the executable refuse a --grant with limits when L_lim is above internal: a usage error, exit code 2, before main starts, with the message "the grant <spec> has limits, but this program's requests are timed by <label> data".

    P10's label is computed in one pass over the strongly connected components of the call graph, linear in the functions, handlers, operations and edges of the package; P11's in one walk per body to build its graph, four searches over it and one pass over the components: O(V + E) in the steps of the package. τ_conc at a request in a function's body is that of §11; at a request in a lambda's body or in a handler's operation it is ⊤, as the ancestors of such a request are not one function's (issue #1154). So a server whose requests run in started tasks beside work on public and internal data keeps L_lim at internal, and its grants can carry limits.

  6. Report. How long a request waits at a limit is timing, out of model: the report's out_of_model list (spec/13 §6) holds "waits at limits and at start" (§7 rule 8). A full queue becomes a value only through RateLimited, which rule 5 labels.

  7. Costs (ADR 0117 Costs). Finding the grants that allow a request takes O(G) for its G grants of Http, as before. Charging it takes O(1) per limited grant that allows it, under one lock per run held for that work only; a request that waits takes one queue entry per such grant, joined in O(1) and left in O(1) amortized. A run without limits pays nothing more.