[pdpix] API is Currently Missing a Way to Pass Through a User Context

Current Situation

In the current API, demi_wait_any() closely resembles the "select" API from BSD Sockets, which was designed before multi-threading (or async) was common. It allows you wait on a set of queue descriptors (file descriptors) and lets you know which one had some I/O complete on it. But applications which have some state associated with that queue/file descriptor are left to their own devices when it comes to mapping that queue/file descriptor back to that state.

More recent APIs, such as Window's I/O Completion Ports, or Linux's similar io_uring, allow the user to associate a pointer-sized (user-defined) value with the descriptor or I/O request, and return that value along with the descriptor on I/O request completion. This allows applications to avoid an extra (hash table or similar) lookup to get the associated state on every I/O call. It would be nice if our API had similar functionality.

Proposed Solution

Add a way to associate an opaque (to the system) value (large enough to hold a pointer) with a queue descriptor or even a specific I/O request. And include that value in the queue result that is returned by demi_wait_any().

Start by reading the demi_wait_any() API and its queue descriptor and result definitions; the issue does not name files or tests. Define how an opaque pointer-sized context is associated with a descriptor or I/O request and returned in the queue result, then verify the behavior through the relevant API tests.