io_uring_cancelation(7)

💖 io_uring_cancelation 💖

okay bestie, so this is io_uring_cancelation from the Linux Programmer's Manual — section 7, the deep lore shelf where all the io_uring overview pages live. it's giving "how do i make my in-flight requests just… stop" and honestly? iconic. 🦋

---

✨ DESCRIPTION ✨

so io_uring gives you ways to cancel in-flight requests before they complete naturally. the way that this matters: timeouts, connection drops, closing connections that ghost you, or just… a request you don't need anymore. it's the "nvm actually" of the kernel world 💅

🌸 Why cancel requests? 🌸

the scenarios where you'd be reaching for cancelation, fr fr:

• Timeouts — cancel a read or an accept that's been pending way too long
• Connection management — cancel pending operations when a connection is closed
• Resource cleanup — cancel operations on a file descriptor that's being closed
• Multishot termination — stop a multishot operation that is no longer needed

🎀 Basic cancelation 🎀

the main character here is IORING_OP_ASYNC_CANCEL (you set it up with io_uring_prep_cancel(3) or its related functions). by default, it cancels a request matching a specific user_data:

/* Submit a read with user_data = 1234 */
sqe = io_uring_get_sqe(ring);
io_uring_prep_read(sqe, fd, buf, len, 0);
io_uring_sqe_set_data64(sqe, 1234);
io_uring_submit(ring);

/* Later, cancel it */
sqe = io_uring_get_sqe(ring);
io_uring_prep_cancel64(sqe, 1234, 0);
io_uring_submit(ring);

like, tag it, then un-tag it. cute. 🫶

💜 Cancelation results 💜

when a cancelation is submitted, two CQEs get generated. not one. two. keep up bestie:

the canceled request's CQE:

• res is set to -ECANCELED (or occasionally -EINTR if the operation was already in progress)
• the user_data identifies which request was canceled

the cancel request's CQE:

• res is 0 on success (the request was found and canceled)
• res is -ENOENT if no matching request was found
• res is -EALREADY if the request was found but already completing

the order of these CQEs is not guaranteed 😭 you may get the cancel CQE before or after the canceled request's CQE. so don't you dare assume an order.

⭐ Cancelation flags ⭐

various flags modify cancelation behavior. vibe check:

• IORING_ASYNC_CANCEL_ALL — cancel all matching requests, not just the first one found. the cancel CQE's res tells you how many requests were canceled.
• IORING_ASYNC_CANCEL_FD — match requests by file descriptor instead of user_data. it cancels requests operating on the specified fd:

io_uring_prep_cancel_fd(sqe, fd, IORING_ASYNC_CANCEL_FD);

• IORING_ASYNC_CANCEL_ANY — cancel any single request, ignoring user_data matching. super useful for draining a ring of all pending requests when you combine it with IORING_ASYNC_CANCEL_ALL.
• IORING_ASYNC_CANCEL_FD_FIXED — the file descriptor is a fixed file (a registered file index) rather than a regular fd.

and yes, flags can be combined 🧚:

/* Cancel all requests on a specific fd */
io_uring_prep_cancel_fd(sqe, fd,
    IORING_ASYNC_CANCEL_FD | IORING_ASYNC_CANCEL_ALL);

/* Cancel all pending requests in the ring */
io_uring_prep_cancel(sqe, NULL,
    IORING_ASYNC_CANCEL_ANY | IORING_ASYNC_CANCEL_ALL);

💀 Race conditions 💀

cancelation is inherently racy. periodt. between submitting the cancel request and the kernel actually processing it:

• the target request may complete successfully
• the target request may fail for another reason
• the target request may already be in a non-cancelable state

so your application must handle all of these cases:

io_uring_wait_cqe(ring, &cqe);

if (cqe->user_data == cancel_user_data) {
    /* This is the cancel operation's result */
    if (cqe->res == -ENOENT) {
        /* Request already completed or not found */
    } else if (cqe->res == -EALREADY) {
        /* Request was found but completing */
    } else if (cqe->res >= 0) {
        /* Successfully canceled res requests */
    }
} else {
    /* This is the original request's result */
    if (cqe->res == -ECANCELED) {
        /* Request was canceled */
    } else {
        /* Request completed normally (or with error) */
    }
}

🦋 Link timeouts 🦋

ngl, for timing out a single operation, link timeouts are often simpler than explicit cancelation. see io_uring_linked_requests(7) for the details:

sqe = io_uring_get_sqe(ring);
io_uring_prep_read(sqe, fd, buf, len, 0);
sqe->flags |= IOSQE_IO_LINK;

sqe = io_uring_get_sqe(ring);
io_uring_prep_link_timeout(sqe, &timeout, 0);

the kernel handles the cancelation automatically if the timeout expires. no notes. 👑

🌈 Canceling multishot requests 🌈

multishot requests (peep io_uring_multishot(7)) keep generating completions until they're canceled or an error occurs. to stop a multishot request:

/* Cancel a multishot accept */
io_uring_prep_cancel64(sqe, accept_user_data, 0);

after cancelation:

• the multishot generates a final CQE with -ECANCELED
• the IORING_CQE_F_MORE flag is not set on this final CQE
• the cancel CQE indicates success

🍓 Canceling by file descriptor 🍓

okay this one's a big deal. when a file descriptor is closed (either via close(2) or IORING_OP_CLOSE), pending requests operating on that fd are not automatically canceled. this differs from synchronous I/O behavior and is a common source of confusion. 💀

in synchronous I/O, closing a file descriptor is typically the last reference to the underlying file, so the close completes any pending operations. however, io_uring holds its own reference to the file for each pending request. closing the application's fd does not release these references — the pending read, recv, or other operation continues to hold a reference and will not automatically complete or fail.

so if an application expects a pending read on an fd to post a completion when the fd is closed — that will not happen. the request must be explicitly canceled:

/* Cancel all operations on fd before closing */
sqe = io_uring_get_sqe(ring);
io_uring_prep_cancel_fd(sqe, fd,
    IORING_ASYNC_CANCEL_FD | IORING_ASYNC_CANCEL_ALL);
io_uring_submit(ring);

/* Wait for cancelations, then close */

🌸 Shutdown cancelation 🌸

when an io_uring instance is closed (via io_uring_queue_exit(3) or closing the ring file descriptor), all pending requests are automatically canceled. manual cancelation before shutdown is not required. you're free 🫶

but — if the application needs to ensure all requests are completed before proceeding (like, to process their results or free associated resources), you can use explicit cancelation:

/* Cancel everything */
sqe = io_uring_get_sqe(ring);
io_uring_prep_cancel(sqe, NULL,
    IORING_ASYNC_CANCEL_ANY | IORING_ASYNC_CANCEL_ALL);
io_uring_submit(ring);

/* Wait for all CQEs */
while (pending_count > 0) {
    io_uring_wait_cqe(ring, &cqe);
    pending_count--;
    io_uring_cqe_seen(ring, cqe);
}

✨ Synchronous cancelation ✨

for when the application needs to cancel requests and wait for the cancelation to complete in a single blocking call, io_uring_register_sync_cancel(3) gives you a synchronous interface:

struct io_uring_sync_cancel_reg reg = {
    .addr = user_data,
    .timeout.tv_sec = 5,
};

ret = io_uring_register_sync_cancel(ring, &reg);

this blocks until the matching request is canceled or the timeout expires. it's useful when the application can't easily integrate asynchronous cancelation into its event loop. main character energy for event loops that simply cannot. 💅

---

👑 NOTES 👑

• not all operations are cancelable. operations that have already been submitted to hardware (e.g., disk I/O in progress) typically cannot be canceled.
• cancelation is asynchronous. the cancel request itself may take time to complete.
• when using IORING_ASYNC_CANCEL_ALL, the cancel CQE's res field contains the count of canceled requests.
• fixed files can be canceled using IORING_ASYNC_CANCEL_FD_FIXED with the file index instead of a regular fd.
• poll operations and multishot requests are generally good candidates for cancelation. completed disk I/O is not. 🙈

---

🌟 SEE ALSO 🌟

io_uring(7), io_uring_linked_requests(7), io_uring_multishot(7), io_uring_prep_cancel(3), io_uring_prep_cancel64(3), io_uring_prep_cancel_fd(3), io_uring_prep_link_timeout(3), io_uring_register_sync_cancel(3)

---

and that's the whole page, bestie!! 🌈✨ this one's from the Linux crew, version dated January 18, 2025, and it lives at io_uring_cancelation(7) — go forth and cancel responsibly, no cap 💖🎀🦋