ioring

nimony/lib/std/ioring.nim

• proc initIoRing()

  Bring the default ring up. Idempotent, and it has to be: this module already initialises the ring at import time, so a second call — the usage example above tells callers to make one — would otherwise re-run initOpQueues/initSlots/gCq = newSeq while worker threads are live inside poll, holding indices into the seqs being replaced. That is a use-after-free plus the loss of every op in flight.

• proc shutdown()

  Stop the pool first, then tear the backend down: close closes the epoll/kqueue/io_uring descriptors the workers poll, so closing them while a worker is still inside poll leaves it waiting on — or re-registering against — a descriptor number the OS is free to hand to something else.

  Call it from a non-worker thread: it joins the workers, and a worker that joins itself deadlocks. It also stops the pool for everyone (std/parfor included), and the ring cannot be brought back up afterwards.

• proc submitNop(deadline: Deadline; cont: Continuation; resPtr: ptr int64): uint32
• proc submitTimeout(deadline: Deadline; cont: Continuation; resPtr: ptr int64): uint32

  Complete once deadline passes, with no I/O at all. Unlike every other op, reaching the deadline is this one's success: it completes with 0 rather than IoTimedOut.

  This is how a loop gets a turn on a schedule — next(e, deadline) in the HTTP design is one of these plus whatever else is pending.

• proc submitRead(fd: int32; buf: pointer not nil; len: int64; deadline: Deadline; cont: Continuation; resPtr: ptr int64): uint32

  Read up to len bytes into buf. Completes with the byte count (0 is end of file) or a negated error. On the readiness backends fd must be O_NONBLOCK (submitSetNonBlocking); on iouring an `ONONBLOCK fd can complete with -EAGAIN` (see the module docs).

• proc submitWrite(fd: int32; buf: pointer not nil; len: int64; deadline: Deadline; cont: Continuation; resPtr: ptr int64): uint32

  Write up to len bytes from buf. Completes with the byte count, which may be less than len, or a negated error. On the readiness backends fd must be O_NONBLOCK (submitSetNonBlocking); on iouring an `ONONBLOCK fd can complete with -EAGAIN` (see the module docs).

• proc submitOpen(path: cstring not nil; mode: FileMode; permissions: set[FilePermission]; deadline: Deadline; cont: Continuation; resPtr: ptr int64): uint32

  Open path and complete with the fd (or a negated errno). The work is made by the backend, on the polling thread: opening here would block the caller, and opening has no readiness for the ring to park on anywhere else. On Windows the same op performs the backend's CreateFileW (see backends/files.nim); each backend translates mode into its platform's arguments, and permissions only matters on POSIX.

  path must stay valid until the op completes — it is read by the backend, not copied. The ring copies OpContext by value, and a string inside it would be shared across threads for no reason; the caller's frame is parked for the duration, so a cstring out of it is safe (the same arrangement as submitRead's buffer).

• proc submitSocket(domain: Domain; typ: SockType; proto: Protocol; deadline: Deadline; cont: Continuation; resPtr: ptr int64): uint32

  Create a socket and complete with its fd, or a negated error. The call is made by the backend: on the readiness backends the polling thread performs socket(2) exactly like submitOpen; on iouring it is a `IORINGOP_SOCKET` SQE and the fd arrives in the CQE.

• proc submitSetSockOpt(fd: int32; level: int32; optName: int32; optVal: pointer not nil; optLen: uint32; deadline: Deadline; cont: Continuation; resPtr: ptr int64): uint32

  Set a socket option (setsockopt(2)/Winsock setsockopt) and complete with 0 or a negated error. Configuration, not I/O — and on iouring a `IORINGOPURINGCMD + SOCKETURINGOPSETSOCKOPT SQE (kernel 6.7+) rather than a syscall. optVal` is read while the op runs (during submission on the readiness backends, at issue by the ring on iouring), so it must stay valid until the op completes — like a submitRead buffer; the suspended .passive caller's frame is parked exactly that long.

• proc setNoDelay(fd: int32; on: bool)

  Nagle's algorithm off (or on) for a TCP socket: whether the kernel may hold a small write back until the previous one has been acknowledged.

  Off is what a server that answers in small messages wants. With it on, a reply of a few hundred bytes waits a whole round trip for the peer's ACK, and the cost is invisible in CPU: an echo server writing ~20 small frames per burst measured 676k messages/s with Nagle and 1.05M without it, idle in both cases, because every reply was held one ACK. Node, nginx and Bun all turn it off on accept; a server moving bulk data does not care either way.

  One ring op (IORING_OP_URING_CMD + SOCKET_URING_OP_SETSOCKOPT, kernel 6.7+) or one setsockopt on the readiness backends. Best effort: an error — including a kernel with no ring form for it — leaves the socket's default in place rather than failing the accept.

• proc submitBind(fd: int32; sa: Sockaddr_storage; saLen: uint32; deadline: Deadline; cont: Continuation; resPtr: ptr int64): uint32

  Bind fd to sa and complete with 0 or the negated errno. The address is copied into the op, so it does not need to outlive the call; the backend performs bind(2) on its polling thread — one instant syscall, nothing to wait on — making a fully passive socket creation possible.

• proc submitSetNonBlocking(fd: int32; deadline: Deadline; cont: Continuation; resPtr: ptr int64): uint32

  Make fd non-blocking (fcntl(FSETFL, ... | ONONBLOCK) / ioctlsocket FIONBIO) and complete with 0 or a negated error. The non-blocking half of socket creation, as its own op: the readiness backends set the flags on the polling thread at issue time (a poller cannot watch for "not blocking"); the iouring backend needs no syscall for it at all — its ring-created sockets are non-blocking from birth (`SOCKNONBLOCK in the IORINGOPSOCKET type, accepted sockets inherit it), so the op completes 0` on arrival there.

• proc submitReadAt(fd: int32; buf: pointer not nil; len: int64; offset: int64; deadline: Deadline; cont: Continuation; resPtr: ptr int64): uint32

  Read at an explicit byte offset without changing the file cursor. Keep the buffer live until completion. Short reads and EOF are legal; offsets and lengths must be nonnegative. Synchronous fallbacks occupy the polling lane and cannot be interrupted once the transfer starts. fd must be a regular file; on Windows that is a file from submitOpen. illumos runs these as POSIX AIO: a non-regular fd fails with ENOTSUP, and more than 64 MiB in flight per lane with EAGAIN.

• proc submitWriteAt(fd: int32; buf: pointer not nil; len: int64; offset: int64; deadline: Deadline; cont: Continuation; resPtr: ptr int64): uint32

  Positioned counterpart of submitWrite; does not move the file cursor. Same fd rules as submitReadAt. A write that times out or is cancelled after it started completes with what really happened, which can be success: the deadline stops the waiting, not a write already issued.

• proc submitAccept(listenFd: int32; deadline: Deadline; cont: Continuation; resPtr: ptr int64; peer: ptr Sockaddr_storage): uint32

  Accept one connection. Completes with the accepted fd, or a negative result.

  On the readiness backends (epoll, kqueue) listenFd must be O_NONBLOCK; a wake that finds no connection leaves the accept pending.

  peer, when given, receives the address that connected — the kernel fills it as part of the accept, so asking costs no syscall. It is written only when the accept succeeds, and it must outlive the op: the completion writes through it from whichever lane ran the accept.

  Without it the address is dropped, which is what an access log, a rate limiter and every X-Forwarded-For trust decision need and cannot reconstruct afterwards.

• proc submitConnect(fd: int32; sa: Sockaddr_storage; saLen: uint32; deadline: Deadline; cont: Continuation; resPtr: ptr int64): uint32

  Connect fd to sa. Completes with 0 on success, or the negated errno — a refused connection is -ECONNREFUSED, not a generic -1, because the caller usually wants to tell "nobody listening" from "the network ate it".

  fd must already be non-blocking (setNonBlocking). The attempt is started on the polling thread, not here, so that the fd is being watched from the moment it is connecting.

  A connect with no deadline is the classic way to hold a slot forever: a SYN into a black hole never answers. Hence the parameter, and hence no default for it.

• proc submitRecvFrom(fd: int32; buf: pointer not nil; len: int64; deadline: Deadline; cont: Continuation; resPtr: ptr int64; peer: ptr Sockaddr_storage): uint32

  Receive one datagram into buf. Completes with the number of bytes received, or a negative result. On the readiness backends fd must be O_NONBLOCK.

  peer, when given, receives the sender's address — the kernel fills it as part of the recvfrom, so asking costs no syscall beyond the one that receives the datagram. It is written only when the receive succeeds and it must outlive the op, like submitAccept's peer.

• proc submitSendTo(fd: int32; buf: pointer not nil; len: int64; sa: Sockaddr_storage; saLen: uint32; deadline: Deadline; cont: Continuation; resPtr: ptr int64): uint32

  Send buf as one datagram to sa. Completes with the number of bytes sent, or a negative result. On the readiness backends fd must be O_NONBLOCK. The address is copied into the op, so it does not need to outlive the call the way submitConnect's does.

• proc submitPollAdd(fd: int32; deadline: Deadline; events: set[IoEvent]; cont: Continuation; resPtr: ptr int64): uint32

  Register oneshot readiness interest in fd without issuing any I/O. When the fd becomes ready in one of the events directions a single completion fires whose op is opPollAdd and whose readyEvents are the directions that fired. Unlike submitRead/submitWrite, no transfer is performed — the caller decides what to do with the ready fd (e.g. libcurl's multi-socket engine). This is oneshot: complete frees the slot, so re-arm by calling submitPollAdd again after handling the event.

  Pass the direction you actually want. The default watches both, which is right for a probe with no preference — but a caller waiting to read a socket is woken by mere writability on every arm (a connected socket is writable nearly always), and because the op is oneshot its re-arm then spins as fast as the loop can poll. libcurl's multi-socket engine always states its direction (CURL_POLL_IN/CURL_POLL_OUT); pass it through.

  A resPtr receives the same directions as a bit mask instead of a set, being a ptr int; decode it with toIoEvents.

• proc pollCompletions(comps: var openArray[IoCompletion]): int64

  Non-blocking: drive this lane's backend once — issue the ops queued on it and collect whatever the kernel has finished — then hand back up to comps.len completions from the shared queue. Returns 0 when nothing has completed. It used to only drain the queue, so a caller that submitted and then polled had not issued anything, and a closeFd in between found no slot to cancel.

• proc waitCompletions(comps: var openArray[IoCompletion]): int64

  pollCompletions until at least one completion has landed.

• proc submitPollRemove(fd: int32): int64

  Cancel without closing. Take back every op this lane still has in flight on fd — each completes with ECancelled, so its continuation is resumed and its slot released — and drop the backend's per-fd registration. fd itself is left open. Returns how many ops were cancelled; 0 means nothing was armed, which is the common case.

  closeFd was the only way to cancel, and it also closes the descriptor — no use to a library that owns its own sockets and merely wants to stop watching one (libcurl's CURL_POLL_REMOVE, whose slots leak for the life of the process without this; harness doc/ioring-2390-port.md).

  Named for IORING_OP_POLL_REMOVE, but it is not a submit* in behaviour: those enqueue an op and return a SeqNum to wait on. Cancelling is not something you wait for, so this acts on THIS lane and answers at once.

  ⚠ This lane only, exactly like closeFd — see cancelPendingOps.

  ⚠ The drain is load-bearing; do not remove it. submitPollAdd only ENQUEUES, and the op becomes a slot when the lane next polls. Without the drain an op submitted moments ago has no slot yet: this reports 0, the op is armed immediately afterwards, and the slot leaks — the exact bug the proc exists to fix. pollCompletions drains for the same reason. (closeFd drains only on illumos; elsewhere it keeps that narrow gap.)

• proc setNonBlocking(fd: int32)
• proc closeFdRaw(fd: int32)
• proc closeFd(fd: int32)

  Close fd: cancel this lane's in-flight ops on it (see cancelPendingOps), deregister it from the backend, then close(2).

• proc socketNonBlocking(): int32

  A non-blocking TCP socket, which is what submitConnect requires: a blocking one would finish the connect inside the syscall and there would be nothing for the ring to wait on.

• proc loopbackAddr(sa: var Sockaddr_storage; saLen: var uint32; port: uint16)

  Fill sa with 127.0.0.1:port, ready for submitConnect.

• proc boundPort(fd: int32): uint16

  The port fd is actually bound to. With listenTcp(0) the kernel picks one, and asking for it afterwards is the only way a test can listen without inventing a fixed number that a parallel run — or a socket still in TIME_WAIT — will collide with.

• proc listenTcp(port: uint16; backlog: int64): int32