Home / Docs / Specification / 27. Tasks and time
27.10 std.limit
-
The module (ADR 0117 rule 9). In edition
0.4,std.limitis an importable standard module (spec/10 §11 rule 10), read only by a package that imports it, the mechanism by whichstd.collectionsis read in edition0.5(spec/28 §2); in earlier editions an import of it is U1001 at the module path. It declares:unapub kind Limited = | RateLimited pub capability Limit op acquire() -> Unit fails Limited accepts internaland 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 nohandlerdeclaration of it exists in Core IR (spec/09).with @x = limiter(...)and agivenline of an example install it by the rule that awithor agivennames a handler (spec/05 §9 rule 4, U3010), and@x.acquire()is an operation ofLimitlike any other, with its event in the trace (spec/11 §5) under the instancewith:limiter#<n>orgiven:<name>. -
Installing. Each installation carries three
refinementobligations, at the arguments:at_most >= 1,per >= 1andwaiting >= 0(U5001, U5002). Each installation is one instance with one bucket, shared by every task that uses the binding during the statement thewithscopes over, the started tasks of atasksstatement inside it included (§7 rule 2); a rebinding shares it (spec/11 §2). A count beyond 2^64 − 1 counts as 2^64 − 1. -
Dynamics. The bucket holds
at_mosttokens and refills evenly overpermilliseconds: a burst of up toat_most, then one everyperdivided byat_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
waitingcalls already wait, it fails at once withRateLimited, joining no queue; withwaiting: 0, a call that finds no token fails at once. - Deadlines. The deadlines of the
withins in progress (§5) and of thefor ever withiniteration (spec/26 §7) bound the wait. Past the earliest, no token is taken and the call fails withRateLimited, the one failureLimitedhas; thefor ever withiniteration observes its deadline at the operation, and awithinat its next check point or when its expression returns, as for a request (§9 rule 4). A host stop in the body of afor 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
interruptedand takes it out of the queue; the task stops. A deadline's cut of itstasksstatement ends it withRateLimitedinstead (§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 ofClock.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.
-
Information flow (ADR 0117 IF5).
acquireacceptsinternal, so it can be called under aninternalprogram 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).Limitedis labeledinternal: whether a call ofacquirefails, and its payload, carryinternalfor the program, whatever handler serves it, as the arguments that decide a host operation's failure label it (spec/07 §7 rule 4). Soattempt @x.acquire()gives aninternalResult, a branch on it runs under aninternalprogram counter, andif error passandif error failare U4002 (S-46, #1563). Whether a token is left depends on the timing of the code that shares the instance: the statement thewithscopes over, or thedoline of the example whosegivenline installs it, and, throughτ_conc(spec/26 §7 rule 5), the program's other tasks. Soτof that statement, computed as for awithin(§5) but with the preview'sτ_concuntil §11 names the statement (§11), the handlers the statement's bindings install included, MUST flow tointernal: U4001 at thewithbinding, or at thegivenline, otherwise, naming what raised it. That coverswaiting: 0as well, where one task's own timing decides whetheracquirefails. -
Report. How long a call waits is timing, out of model: the report's
out_of_modelentry "waits at limits and atstart" (§7 rule 8) covers it. A full queue becomes a value only throughRateLimited, which rule 4 labels. -
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.limitpays nothing: the checker does not read the module, and no Core IR changes.