Home / Docs / Specification / 27. Tasks and time
27.2 Waiting
-
Joins park. A task that waits for the tasks of its block, at their fork or at their join, parks: its worker runs other tasks until the wait ends. So a join never holds a worker that its own tasks need, and a run cannot deadlock on its workers, with
--workers 1included. -
Helper pools. A host operation of a task that may block runs on a helper thread while the task parks:
Files.readandFiles.write, on the file pool of--file-threadsthreads;- a
Console.printwhose output cannot take the line without waiting, on the same pool; a line that stdout can take at once is written by the task's worker; - the name resolution and the connection of an
Httpoperation, on the I/O pool of--io-threadsthreads (rule 3).
Both pools start at their full sizes before
main, as the timer thread of §5 does (§1 rule 4). Each pool serves its operations first in, first out. The pools are separate, so requests never delay aFilesoperation or a print of another task. Only the operation's arguments and result cross to a helper; the task's heap, trace and state stay on its worker. -
The reactor. The rest of an
Httpoperation of a task runs on the task's own worker, and each wait on its connection parks the task on the reactor: one thread of the process that waits on every parked connection at once, throughkqueueon macOS andepollon Linux, and makes a task ready again when its connection is ready, when its deadline passes, when a host stop reaches it (ADR 0116 rule 12), or when its task is canceled (§5, §6, §7), but for a deadline's cut of itstasksstatement, which wakes no parked task (rule 4). So a request that waits on a server that never answers holds no thread. The sockets of such requests are capped for the process at its soft limit of open descriptors less a reserve of a quarter of it, and at least 64, forFiles,Consoleand the runtime: a request holds one place from its first connection to its end, and one that finds none free waits for one, first come, first served, a wait that its deadline and a cancellation cut. So requests can never take the descriptors that aFilesoperation of another task needs. The wait of the connection step in the I/O pool is covered by the request's deadline too. An interrupted request's connection is closed when its task resumes, before the task goes on. If the reactor cannot start, the whole operation runs on the I/O pool instead, with the same meaning. A task'snextofHttpServer(spec/31 §1) that waits for a request parks on the reactor too, woken by the serve engine's signal for one waiter, by its deadline, or by its cancellation, so no number of tasks waiting innextholds a helper of the I/O pool that theHttpoperations of other tasks need (#1723); only when the reactor cannot hold the wait does it wait on a helper. The reactor's thread starts beforemainin a run whose grants includeHttporserve:and whose program holds a task construct (§1 rule 4, ADR 0116 amendment P8), never at a task's first wait, and none starts under--virtual-time, where no task parks on it; a reactor that cannot start stops the run beforemainwith U6003, as a worker that cannot start does. -
An interrupted exchange (ADR 0116 amendment, P9, #1148). A request that runs on a helper of the I/O pool, without the reactor or with a grant that carries limits (rule 3), runs there until its exchange returns, so what the helper does after its task was canceled is bounded as follows. On the reactor, a cancellation that wakes the parked task (rule 3) raises the request's abandon too, so its exchange stops in the same way, on its task, and a job of it still waiting on the lookup or connect pools ends at once; a deadline's cut of its
tasksstatement wakes no parked task and raises no abandon (last item).- On the pools, non-blocking. A helper's request runs on its helper of the I/O pool, but for the lookup of its name and its connection, which it hands to the bounded lookup and connect pools of spec/24 §4 rule 2 and waits for only until its deadline or its abandon. The client starts no thread per request, so a run's requests never take more than
2 × --io-threads + max(2, --io-threads / 4)threads. From the connection on, the request never blocks on its socket: every read, write and step of the TLS handshake that would block waits withpollinstead, for the time left before its deadline. - The cancellation reaches the exchange, with no polling. A cancellation of the task that interrupts its waiting request (§6 rule 7, §7 rule 4) abandons the request: a wait at a limit leaves its queues, never sent (§9 rule 4), and an exchange in progress is abandoned at its next I/O step. Its socket is shut down, which ends a wait on it at once; its wait for a lookup or a connection ends at once, which run on to their end on their pool's thread, residue that
L_rescovers, at most the pools' sizes, a connection job looking at the cancellation only between two addresses and each attempt bounded by the request's deadline; the flag is checked after each step, before the response is parsed to its end and before its body is decoded, so an abandoned exchange takes neither; it fails, its result dropped, and its connection is closed. On its helper, an abandoned exchange does at most one I/O step more: one read or write of at most 16 KiB, decrypted and parsed, or one step of the TLS handshake. A lookup or a connection it left in flight holds one pool thread until it returns, and that thread then closes what it reached: pool residue, bounded by the pools' sizes. No wait looks at the cancellation in slices: only a host stop in afor everbody, which the wake pipe may not tell, is looked at every 100 ms (spec/26 §6). At most--io-threadshelpers can each be in such a step. That bound is a measure of cost; what makes the rule sound is the residue labelL_res(spec/26 §7 rule 5), which every timing site joins. - A deadline is the request's own time-out. A request waits no longer than the earliest deadline that covers it (§5 rule 6). The runtime passes that deadline to the helper as an instant of the monotonic clock, never as a duration counted from when the helper starts, so a request that waited for a free helper still ends at it, at its next I/O step.
- A task that a deadline cancels waits for its request. When the deadline of a
withinaround atasksstatement cuts its block, its started tasks share that deadline (§5 rule 5), and a task parked on a request is not woken: on a helper, it waits for its helper, whose exchange ends at the same deadline, at its next I/O step, with its ownTimedOut; on the reactor, its waits run to their own time-out, the same deadline, and the request fails withTimedOutthere too (#1266). The task then stops at its next check point. So the statement ends only once nothing of its work is left on a helper. Only a job that has begun on its helper is waited for: a task whose request is still queued for a helper is woken at once, and its request is never sent; it fails withTimedOutas well, and anacquireofstd.limitqueued the same way withRateLimited(§10). - One outcome at the cut (#1266). A request that a
within's cut of itstasksstatement ends fails withTimedOut, its event that time-out failure, on every path: parked on the reactor, running on a helper, or still queued for one, neverinterrupted, which belongs to the other cancellations below. Whether a cut came, and so this outcome, is timing information (§5 rule 7, ADR 0116 rule 21): it MUST NOT depend on which path ran the request, which the grants' limits,--io-threadsand the load of the pool decide, nor on whether the task or the statement saw the deadline first, a decision of the schedule that earlier code, possibly code onsecretdata, can move.TimedOutis the outcome that the request's own deadline, the same one, gives without the cut, the one the interpreter gives, and the one that waits for the helper instead of leaving residue on it. The runtime marks the cut on the statement's count of cancellation with a value of its own, so every wait tells it from another cancellation in O(1). A lookup or a connection that the deadline cuts may still hold a pool thread until it returns, bounded by the pools' sizes, whichL_rescovers. The cut meant here is awithin's around the statement: the deadline of afor ever withiniteration cancels no task, and atasksstatement in such a body is counted byL_reswhatever ends it. A task canceled otherwise, by a failure of the block, a race that its task lost or a cancellation from outside it, is woken at once, as §7 rule 4 says, and its request's residue is whatL_reslabels.
- On the pools, non-blocking. A helper's request runs on its helper of the I/O pool, but for the lookup of its name and its connection, which it hands to the bounded lookup and connect pools of spec/24 §4 rule 2 and waits for only until its deadline or its abandon. The client starts no thread per request, so a run's requests never take more than
-
Meaning. Parking and helpers change when an operation runs, never what it does: its grants, its outcome, its event and its failure are those of spec/14 and spec/24.