Home / Docs / Specification / 27. Tasks and time

27.2 Waiting

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

  2. Helper pools. A host operation of a task that may block runs on a helper thread while the task parks:

    • Files.read and Files.write, on the file pool of --file-threads threads;
    • a Console.print whose 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 Http operation, on the I/O pool of --io-threads threads (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 a Files operation 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.

  3. The reactor. The rest of an Http operation 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, through kqueue on macOS and epoll on 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 its tasks statement, 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, for Files, Console and 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 a Files operation 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's next of HttpServer (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 in next holds a helper of the I/O pool that the Http operations of other tasks need (#1723); only when the reactor cannot hold the wait does it wait on a helper. The reactor's thread starts before main in a run whose grants include Http or serve: 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 before main with U6003, as a worker that cannot start does.

  4. 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 tasks statement 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 with poll instead, 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_res covers, 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 a for ever body, which the wake pipe may not tell, is looked at every 100 ms (spec/26 §6). At most --io-threads helpers can each be in such a step. That bound is a measure of cost; what makes the rule sound is the residue label L_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 within around a tasks statement 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 own TimedOut; on the reactor, its waits run to their own time-out, the same deadline, and the request fails with TimedOut there 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 with TimedOut as well, and an acquire of std.limit queued the same way with RateLimited (§10).
    • One outcome at the cut (#1266). A request that a within's cut of its tasks statement ends fails with TimedOut, its event that time-out failure, on every path: parked on the reactor, running on a helper, or still queued for one, never interrupted, 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-threads and 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 on secret data, can move. TimedOut is 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, which L_res covers. The cut meant here is a within's around the statement: the deadline of a for ever within iteration cancels no task, and a tasks statement in such a body is counted by L_res whatever 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 what L_res labels.
  5. 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.