Waiting on a descriptor
Many C network libraries (libpq, curl multi, hiredis) have a non-blocking mode: the library says which socket it waits for, and your program waits. Native.wait_readable(fd, timeout_ms) and Native.wait_writable(fd, timeout_ms) park the task until the descriptor can be read or written, while the other tasks go on. Both give a Result[Void].
extern "libc.so.6"
def eventfd(initval: C.Int32, flags: C.Int32) -> C.Int32
def eventfd_write(fd: C.Int32, value: C.Int64) -> C.Int32
end
def ring(fd: Int) -> Int
Task.sleep(50)
eventfd_write(fd, 1)
end
def main() -> Void
fd = eventfd(0, 0)
bell = Task.spawn(&ring, fd)
puts(Native.wait_readable(fd, 1_000)) # ok() once the other task writes
puts(Task.await(bell))
endA library’s connect loop waits the same way, with try Native.wait_readable(socket, 5_000) between its polls.
- After
timeout_ms(positive) the result iserror("native: timed out"). A timeout that is not positive, a negative descriptor, and one that cannot be polled (closed, a regular file,/dev/nullon Linux) give an error that starts withnative:. On macOS/dev/nullis always ready. - An error or a hang-up on the descriptor ends the wait with
ok, aspoll(2)does: the library’s next call reports it. - The wait watches a copy of the descriptor (a new open of its file,
/proc/self/fdorF_GETPATHon macOS, or a duplicate for a socket, a terminal master, an eventfd and a macOS pipe), so the library keeps its descriptor and its flags, and two tasks may wait on one descriptor. - If the library closes the descriptor during a wait, the wait goes on and ends at its timeout (
native: timed out) unless the file becomes ready. - A cancel stops the wait; the end of the program does not wait for it.
- On Windows only a socket can be waited on: the number is the library’s Winsock
SOCKET, watched through a duplicate socket. That puts the socket in non-blocking mode for good, since Winsock cannot read the mode back. One socket handle takes one wait at a time: a second wait on the same handle value while one is waiting gives an error that starts withnative:, and the value of a closed socket may stay busy until its wait ends. Any other value (a C runtime descriptor, a file or pipe handle) gives such an error too, and so does a closed socket, usually (Windows reuses handle values). --deny-nativerefuses them too: a descriptor comes from native code.