io_uring_prep_poll_update(3)

💅 io_uring_prep_poll_update — bestie, we're updating a poll request

okay so this one's from the liburing manual, page io_uring_prep_poll_update(3), and it's literally about changing your mind about a poll request you already submitted. no cancel-and-rearm drama (well, sometimes drama, we'll get there). let's go 🎀

✨ NAME ✨

io_uring_prep_poll_update — update an existing poll request

🌸 SYNOPSIS 🌸

#include <poll.h>
#include <liburing.h>

void io_uring_prep_poll_update(struct io_uring_sqe *sqe,
                               __u64 old_user_data,
                               __u64 new_user_data,
                               unsigned poll_mask,
                               unsigned flags);

🦋 DESCRIPTION 🦋

okay so the io_uring_prep_poll_update(3) function preps a poll update request, periodt. it takes your submission queue entry sqe and sets it up to update a poll request that it finds by old_user_data, swapping in the new_user_data info instead. the poll_mask argument is the shiny new mask your poll request is gonna use, and the flags argument is the modifier flags that tell io_uring which fields you actually want updated. iykyk 💅

the flags modifier flags situation is a bitmask, and it can contain an OR'ed mask of these lil guys:

• IORING_POLL_UPDATE_EVENTS — if you set this, the poll update request replaces the events currently being waited on with the ones you put in the poll_mask argument. heads up though: only the lower 16 bits of events can be updated, so that's stuff like EPOLLIN and EPOLLOUT. higher order masks/settings live as internal state and cannot be modified — that includes settings like EPOLLONESHOT, EPOLLEXCLUSIVE, and EPOLLET. if an application wants to change those, it has to cancel/remove the existing poll request and arm a whole new one. no shortcuts bestie 😭
• IORING_POLL_UPDATE_USER_DATA — if you set this, the poll update request updates the existing user_data of the request with whatever value you passed in as the new_user_data argument. 🫶
• IORING_POLL_ADD_MULTI — if you set this, it flips the poll request from a singleshot to a multishot request. this one must be used along with IORING_POLL_UPDATE_EVENTS, because the event field has to be updated to enable multishot. they're a package deal, no solo acts ✨

💖 RETURN VALUE 💖

None. that's it, that's the whole section. it's a void function, she returns nothing and she's thriving 🌈

🔥 ERRORS 🔥

these are the errors reported in the CQE res field. on success, 0 is returned. 👑

• -ENOENT — the request identified by user_data could not be located. this could be because it completed before the cancelation request was issued, or because you used an invalid identifier. it's giving "who? never heard of her" 💀
• -EINVAL — one of the fields set in the SQE was invalid. 🙈
• -EALREADY — the execution state of the request has progressed far enough that cancelation is no longer possible. this should normally mean it'll complete shortly — either successfully, or interrupted due to the cancelation. so like, it's already out the door bestie, you can't call it back 🏃♀️
• -ECANCELED — IORING_POLL_UPDATE_EVENTS was set and an error occurred re-arming the poll request with the new mask. the original poll request is terminated if this happens, and that termination CQE will contain the reason for the error re-arming. so yeah, when this hits, the original is gone and the CQE tells you why 😭

👑 SEE ALSO 👑

io_uring_get_sqe(3), io_uring_submit(3), io_uring_prep_poll_add(3), io_uring_prep_poll_multishot(3)

and that's the whole page, bestie! this one shipped with liburing-2.2, dated March 12, 2022 — go forth and update your polls responsibly 💜✨🎀