Efficient IO in Linux with io_uring [pdf] (2019)

Actually, io_uring has received around 500 commits just in 2022. Here's a list of interesting feature additions(this year),

- https://www.phoronix.com/news/Linux-LPC2022-io_uring_spawn

- https://www.phoronix.com/news/Linux-520-XFS-uring-Async-Buff

- https://www.phoronix.com/news/Linux-5.20-IO_uring-ZC-Send

- https://www.phoronix.com/news/Linux-5.19-IO_uring

io_uring like API was also adopted by Windows recently. Lots of fun.

The logging system was implemented in a module which was inserted into the kernel and then used the calling thread to run a service. The module provided a device and some ioctls. Processes used the ioctls to attach circular buffers to the device, which was mapped into kernel space using get_user_pages.

Processes would just place messages into their circular buffers and update an index variable in the buffer header. The kernel would automatically pick up the message, without any system call. There was a wakeup ioctl to poke the kernel thread, which was used upon hitting a high water mark (buffer getting near full). This is the basic intuition behind io_uring.

The kernel thread collected messages from multiple buffers and sent them into several destination (files and sockets).

I do not have most of this code, but some of it survived, including a kernel mutex and condition variable library featuring a function that lets you give up a mutex to wait on a condition variable, while also polling any mixture of kernel file and socket handles, with a timeout. This function at the core of the kernel thread's loop.

The nice thing was that when processes crashed, their buffer would not go away immediately. Of course their own address space would be gone, but the kernel's mapping of the shared buffer mapping would gracefully persist, until the thread emptied the buffer; everything put into the buffer before the crash was safe. Empty buffers belonging to processes that had died would then be cleaned away.

I had a utility program that would list the buffers and the PIDs of their processes, and provide stats, like outstanding bytes, and is that process still alive.

(The one inefficiency in logging was that log messages need time stamps. Depending on where you get a time stamp from, that requires a trip to the kernel. I can't remember what I did about that.)

A bit of a difficulty in the whole approach is that I wasn't getting a linear mapping of the user pages in the kernel. So I wrote the grotty C code (kernel side) to pull the messages correctly from a scrambled buffer whose pages are out of order, without making an extra copy.

> To find the index of an event, the application must mask the current tail index with the size mask of the ring. This commonly looks something like the below:

  unsigned head;
  head = cqring→head;
  read_barrier();
  if (head != cqring→tail) {
    struct io_uring_cqe *cqe;
    unsigned index;
    index = head & (cqring→mask);
    cqe = &cqring→cqes[index];
    /* process completed cqe here */
    ...
    /* we've now consumed this entry */
    head++;
  }
  cqring→head = head;
  write_barrier();

If you plan on using it, or just want to learn more about it, check this out:

https://github.com/espoal/awesome-iouring