Specification for the Demo

This helper library provides a thin wrapper to encapsulate most of the minute technical details related to the ringbuffers. The kernel interface as such is defined in a rather indirect way, so that most data definitions are exposed dynamically, at runtime in the form of relative field offsets. Also the structure of the ringbuffers is not defined directly as a data type; rather the well-known low-level C implementation of a index based ringbuffer is assumed like a coding template. Working with such a structure requires solid knowledge in system programming, including the proper usage of memory barriers. The Liburing handles all those tricky details behind a function based interface, that should be much more familiar to most programmers.

To avoid a performance penalty due to this indirection and encapsulation, Liburing is defined to a large extent in the form of static inline functions. A variant called liburing-ffi is provided as alternative for cross-language bindings and for usage with older compilers, providing an definition and binary symbol for each function; obviously using these explicit calls adds a noticeable penalty.

It is instructive to contrast two patterns for event-driven I/O. In the Reactor pattern the program waits for a resource to become ready and then performs the operation itself, synchronously, from within the event handler. In the Proactor pattern the operation is initiated up front, the operating system carries it out, and a handler is invoked on completion — with the result already available. While io_uring in itself is an abstraction and hides the actual I/O handling in the kernel, the form of the interface fits well into the Proactor pattern: a read operation is submitted, the kernel performs it, and a completion can later be received to follow-up with processing of the retrieved data.

The demo realises this pattern with a single dedicated »Proactor« thread (UringVideoPlayer::playVideo()). Its whole life is one loop around io_uring_wait_cqe(): block until the next completion arrives, dispatch it to a handler based on a tag carried in the CQE user_data, then re-supply further work items and submit. Two kinds of completion are multiplexed onto the same ring and told apart by that tag:

The code is deliberately split so that the io_uring logic stands apart from the display machinery:

Two threads are involved: the GTK/GUI main thread and the Proactor thread. The player is constructed on the GUI thread and — following a RAII pattern — immediately launches the Proactor thread from its constructor. Note that proactorThread_ is declared last among the members, so by C++'s declaration-order construction rule all the buffers, state and the display connection machinery are fully initialised before the thread can observe them. Data flows in one direction: the Proactor reads blocks of raw video data from the file into buffers and publishes a ready frame; the GUI thread uploads that frame into a GPU texture and draws it.

The two threads share the buffer array, which raises two questions of cross-thread visibility:

Rather than making the entire state array atomic, or sharing cursor indices across the boundary, the design funnels the whole cross-thread contract through a single atomic — std::atomic<Buffer*> toDisplay_ — which is the payload rather than a key to look it up:

The Proactor publishes with a release-store; the GUI picks the pointer up with an acquire-load and thereby is guaranteed to see the buffer contents written before the store. When finished, the GUI writes nullptr with a release-store, which the Proactor observes with an acquire-load before reclaiming the slot. This is the classic single-slot, single-producer/single-consumer mailbox handoff: the two release/acquire pairs establish the happens-before relations that carry buffer-content visibility in both directions. Everything else — the BuffState array and the frame cursors — is confined to the Proactor thread alone and therefore needs no synchronisation at all.

A fixed set of RING_SIZ frame-sized buffers is held in a unique_ptr<Buffer[]> and used as a ring: the slot for a frame can be accessed by taking frameNr % RING_SIZ. Frame numbers themselves are monotonic, unbounded counters — nextRead_ for the production side and nextShow_ for the consumption side — so the modulo maps an ever-growing frame index onto the small cyclic set of buffers. The same running frame number does double duty: as the SQE user_data tag that later identifies the completed read, and (via modulo) as the slot index. A similar addressing scheme is also employed to access a state flag, that is associated with each buffer slot. Notably the io_uring kernel queues are sized as RING_SIZ+1, the one extra entry accommodating the always-present timer event.