[IO_URING] Add support for pollAdd operation

[FranzBusch]

Motivation

To observe events on file descriptors IO_URING supports the pollAdd operation. This is useful when you want to observe a file descriptor becoming ready to read or write

Modifications

This PR adds a new IORing.Request.PollEvents option set to model the poll masks. Furthermore, it adds a new static func pollAdd to the IORing.Request.

Result

We can now use IO_URING to poll for events on file descriptors.

[FranzBusch]

@swift-ci please test

[FranzBusch]

@swift-ci please test

[Catfish-Man]

I had a few comments but I don't think any of them are necessarily blockers

[Catfish-Man]

Typically Swift naming style would be verb-first but if there's a good reason to have it this way it's probably fine

[FranzBusch]

I was trying to match what the io_uring operation was called. I wasn't sure how much we tried to change the naming to fit our Swift naming guidelines.

[Catfish-Man]

I guessed that was probably what you were doing. I remember this coming up during the initial proposal review and iirc folks leaned "don't try to make the names friendlier" so that looking up docs will work better. I'm still torn on it but I see the logic.

[FranzBusch]

Let me know what you prefer and I am happy to change if needed. I am open to both.

[glessard]

pollAdd is somewhat greppable with io_uring docs, but not directly since the names are usually something like io_uring_prep_poll_add or IORING_OP_POLL_ADD. This is the name for the request, so maybe just poll would be better: poll(fd, events: PollEvents, isMultiShot: Bool, context: UInt64).

A future addition would be removal of events, and the constant used for that in the C library is IORING_POLL_UPDATE_EVENTS. I don't think we would want pollUpdate or pollRemove, maybe just update.

[FranzBusch]

@swift-ci please test

[glessard]

@swift-ci please test

[FranzBusch]

@swift-ci please test

[glessard]

I'd be inclined to approve this addition if that were our process.

[FranzBusch]

@swift-ci please test

[glessard]

@swift-ci please test

[glessard]

Added cases for POLLHUP and POLLNVAL. These names are inscrutable in any situation. Should they be pollHup and pollNval, or pollHangup and pollInvalid, or hangUp and invalidDescriptor. For now I continued along with the earlier work in this PR and used what I consider to be the bad names.

Missing are POLLPRI and POLLRDHUP, which would be relevant for sockets.

Better names would be readable, writable, error, hangUp, invalidDescriptor (+ priorityData, and peerClosed)

[glessard]

@swift-ci please test

[glessard]

Public symbols added in this PR:

struct IORing.Request.PollEvents: OptionSet, Hashable, Codable, CaseIterable {
  init(rawValue: UInt32)
  static var allCases: [PollEvents]
  static var pollIn   // 0x0001
  static var pollOut  // 0x0004
  static var pollErr  // 0x0008
  static var pollHup  // 0x0010
  static var pollNval // 0x0020
}

extension IORing.Request {
  static func pollAdd(_:pollEvents:isMultiShot:context:)
}

Let's figure out whether these are the names we want.

I think the presence of poll on everything is a distraction. PollEvents is fine, but the 5 flags could have better names. I'm also not convinced by pollAdd as a case name on Request.

I believe having some accessors on Completion to obtain information would be useful. Something coarse would be a Result<PollEvents, Errno>-returning accessor. Any Completion improvements can be separate, but we can note that the usage examples (tests) don't look ergonomic.

Many more additions made, requested a new review.

[FranzBusch]

I think the presence of poll on everything is a distraction. PollEvents is fine, but the 5 flags could have better names.

I think this is a good suggestion and just renaming them to .in, .out, .error, .hub, etc would be better. I am not sure if we should give them completely new names such as readable or writable. Users of this API are most likely looking at man pages for liburing and there is a lot of value sticking close to that documentation.

I'm also not convinced by pollAdd as a case name on Request.

Similarly here I personally think that sticking as close to the libuiring and ops code naming is beneficial when it comes to discovery.