Native Descriptors and Handles

A single portable native_descriptor spanning POSIX and Windows was considered and rejected. The platform gaps here are not edge cases around a shared core; they are the type’s semantics. O_NONBLOCK on a shared open file description, dup(), and a file-type reject list expressed in st_mode bits are the entire contract below. An open file description is the kernel-side object a descriptor refers to. Every dup() of a descriptor shares the same one. None of them has a Windows counterpart. A type that named both would have to either document each rule twice or say nothing precise about either.

Portability lives one layer up instead. A posix_stream_descriptor is an io_object, io_read_stream, io_write_stream, and io_stream, the same bases tcp_socket has. Like every corosio stream, it satisfies capy::Stream. That concept is what the generic algorithms are written against, so they run on a descriptor, a socket, and a tls_stream alike:

Only the handful of lines that produce the descriptor are platform-specific. TLS layers over it on the same terms.

posix_stream_descriptor::assign takes ownership: close() and the destructor close the descriptor. A failed assign() leaves the descriptor with you, so close it yourself.

An eventfd as a cross-thread wakeup:

An inotify watch. The descriptor is a stream of variable-length records, so read_some() is the whole interface you need:

Another party sometimes owns the descriptor — a C library that does its own I/O on it, or a process-wide descriptor such as STDIN_FILENO. When that happens, adopt a dup() of it rather than the descriptor itself:

Both descriptors refer to one open file description, so the duplicate reports exactly the original’s readiness. Corosio closing the duplicate can never close the original. This is the same rule Readiness Wait states for adopted sockets.

That is what makes standard input safe to adopt for readiness alone. Flipping O_NONBLOCK on it would change the terminal the parent shell is still using.

On the reactor backends corosio sets the flag once and does not check it again. If another holder clears it, the next read_some() or write_some() blocks the thread running the io_context. bash does this to the terminal when a job suspended with Ctrl-Z resumes. Asio’s posix::stream_descriptor has the same limitation.

assign() rejects regular files, block devices, and directories with a code comparing equal to errc::operation_not_supported. A reactor cannot report readiness for them. Regular files and block devices already have a home: stream_file and random_access_file adopt them. No corosio type adopts a directory.

The test is a reject list, not an accept list. The reason: the flagship descriptor kinds — eventfd, timerfd, inotify, pidfd — are anonymous inodes whose st_mode type bits are all zero. An accept list would reject the descriptors this type exists to carry.

A negative or closed descriptor fails with errc::bad_file_descriptor.

read_some() and write_some() use readv() and writev(), so one operation scatters into or gathers from up to 16 buffers of the sequence. A read that returns zero bytes, such as on a pipe whose writer has closed, completes with capy::error::eof. A write to a pipe whose reader has closed completes with errc::broken_pipe, and in the default disposition also raises SIGPIPE; see SIGPIPE.

release() cancels pending operations, deregisters the descriptor from the reactor, and hands it back without closing it. The object is left not-open. O_NONBLOCK stays set if an operation set it; release() never restores the flag.

assign() requires a closed object; on an open one it fails with error::already_open and changes nothing.

On select, a descriptor at or above FD_SETSIZE is a validation failure too. select() cannot monitor it, so assign() rejects it with errc::too_many_files_open.

Where a refusal from the kernel appears depends on the backend:

Whichever way assign() fails, the descriptor you passed is still yours to close.

Character devices that an I/O backend cannot watch, such as /dev/null, /dev/zero, and /dev/urandom on epoll, are adopted on every I/O backend. Their I/O never blocks. On epoll, io_uring, and kqueue, an operation on one that would have to wait for readiness completes with errc::operation_not_supported instead of waiting forever. The exception is a transfer on io_uring when the descriptor is blocking: it waits in a kernel worker thread, as described under Descriptor Flags. select treats every descriptor as watchable. There, reads and writes complete at once, and wait(wait_type::error) parks until cancelled. On macOS, select reports the device as exceptional, so that wait completes at once with an error.

wait(wait_type::error) is the one verb that is not uniform. A hangup or error condition that already holds completes it with errc::io_error on every backend. A wait parked before a pipe or FIFO hangup completes the same way on epoll and io_uring, but never on kqueue or select. kqueue raises an error event only for EV_ERROR or for EV_EOF with fflags != 0, and a hangup sets neither. select’s exceptional set does not cover it. On those two backends, end the wait with cancel() or a stop token. Prefer wait(wait_type::read), which is uniform — the hangup surfaces there as readiness, and the read that follows names the real failure.

Asio’s posix::stream_descriptor behaves the same way, for the same reason. Code ported from it needs no change here.

The overlapped types have no wait(). A reactor asks the kernel when a descriptor is ready, and then does the I/O itself. IOCP works the other way round. The kernel performs the I/O and reports when it is finished. IOCP has no readiness notification for an arbitrary handle, so no readiness wait can be built on it.

That gap is the reason for the platform-qualified names. A portable type would have to drop wait() on POSIX, or promise it on Windows and fail.

Portability lives one layer up, as it does for posix_stream_descriptor. A win_stream_handle is an io_stream and satisfies capy::Stream. capy::read, capy::write, and TLS layering work on it exactly as they do on a socket.

IOCP completes I/O only on a handle opened for overlapped I/O. Both overlapped types therefore reject a handle opened without FILE_FLAG_OVERLAPPED, called a synchronous-mode handle. Console handles are rejected for the same reason. So are both ends of an anonymous CreatePipe pipe, which are always synchronous:

Corosio does not emulate those handles on a thread. The substitute for CreatePipe is a named pipe whose server end is created with FILE_FLAG_OVERLAPPED. Opening the client end connects the pipe. The client end can stay synchronous. Passing it to a child process requires opening it inheritable, with a SECURITY_ATTRIBUTES whose bInheritHandle is TRUE. The read loop is an ordinary capy::read:

win_random_access_handle accepts any overlapped handle that What Is Rejected does not mark as rejected. Each operation names its own offset, so any number can be in flight:

For regular files, prefer random_access_file. It also offers size(), resize(), and the sync operations. Volume and drive handles need sector-aligned offsets, lengths, and buffers. A misaligned request fails with the kernel’s error.

While an overlapped type or a file type holds a handle, the handle is bound to the context’s completion port. Every overlapped call on it queues a packet to that port. Do not issue your own overlapped I/O on it, such as ConnectNamedPipe, WaitCommEvent, or DeviceIoControl. The exception is an OVERLAPPED whose hEvent has its low-order bit set, which suppresses the packet. Connect a pipe server before assign(). A successful release() detaches the handle, which lifts the restriction. win_object_handle never binds to the completion port.

Each type checks a handle before assign() changes anything. The file types column covers stream_file and random_access_file, which apply the same checks on Windows. A handle is in skip-on-success mode once SetFileCompletionNotificationModes has set FILE_SKIP_COMPLETION_PORT_ON_SUCCESS on it.

Every rejection in the table fails with a code comparing equal to errc::operation_not_supported. A null, invalid, or closed handle fails with errc::bad_file_descriptor. For the overlapped types, a handle already bound to another completion port fails with errc::invalid_argument.

assign() requires a closed object; on an open one it fails with error::already_open and changes nothing. Any other failure leaves the object closed and leaves you owning the handle.

Each read_some(), write_some(), read_some_at(), and write_some_at() transfers at most the first buffer of a buffer sequence. ReadFile and WriteFile take a single buffer, unlike readv() and writev(). capy::read and capy::write loop over the whole sequence, so the difference shows only when you call the operations directly.

On a message-mode pipe, a message longer than the buffer is not an error. The read returns the bytes that fit, and the rest of the message arrives on the next read.

A read that finds the peer closed completes with capy::error::eof. A write to a pipe whose reader has closed completes with errc::broken_pipe. Windows raises no signal here, so there is nothing like SIGPIPE to suppress.

release() cancels pending operations and hands the handle back without closing it. On the overlapped types, it also detaches the handle from the context’s completion port. If an operation is still in flight, or Windows refuses the detach, release() throws and the object keeps the handle. Call it again once the cancelled operations have completed. Detaching requires Windows 8.1 or later; on earlier versions release() on these types always throws errc::operation_not_supported.

win_object_handle awaits the signaled state of a process, a thread, an event, a semaphore, a waitable timer, or a job. The Windows thread pool carries the wait. The awaiting coroutine resumes on its executor as usual.

A process handle becomes signaled when the process exits:

assign() rejects a mutex. A satisfied mutex wait acquires the mutex on a pool thread, and the resuming coroutine would not own it. It rejects file objects too, because a file object signals on any I/O completion. Console input handles and directory change notification handles are file objects, so they are rejected as well. A handle without SYNCHRONIZE access cannot be waited on, so it is rejected too, as are pseudo-handles such as GetCurrentThread() and every other object type. On an io_context whose locking mode is locking_mode::unsafe, assign() rejects every handle, because the wait completes from a thread-pool thread. assign() never waits on the handle, so it never consumes a signal.

Re-waiting on an object that stays signaled — a manual-reset event, an exited process or thread, a manual-reset timer — completes again at once. Reset the object, or stop waiting, rather than looping on wait().

Only one wait may be pending. While the first is pending, a second wait() completes with errc::operation_in_progress and leaves the first undisturbed. Calling wait() concurrently on a shared object is unsafe.

wait() has no timeout parameter. Compose it with timeout or a stop token instead:

A wait cancelled before the kernel satisfied it consumed nothing. The object stays open and accepts the next wait().