Home / Docs / Specification / 27. Tasks and time

27.10 std.limit

Release v0.4.0
  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 withins 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.