SDL_WaitAsyncIOResult(3)

💖 SDL_WaitAsyncIOResult 💖

okay bestie, welcome to the SDL_WaitAsyncIOResult(3) page — this one lives in the SDL3 FUNCTIONS section of the manual and it's literally the "girl just go to sleep until the work is done" function 🛌✨

---

✨ NAME ✨

SDL_WaitAsyncIOResult — block until an async I/O task queue has a completed task. no cap, that's the whole job 💅

---

🎀 SYNOPSIS 🎀

#include <SDL3/SDL_asyncio.h>

bool SDL_WaitAsyncIOResult(SDL_AsyncIOQueue *queue, SDL_AsyncIOOutcome *outcome, Sint32 timeoutMS);

---

🦋 DESCRIPTION 🦋

so here's the vibe: this function puts the calling thread to sleep 😴 until there's a task assigned to the queue that has finished. that's it, that's the function.

if a task assigned to the queue has finished, it returns true and fills in outcome with the details of the task. if no task in the queue has finished, this function returns false. simple as 🍓

if a task has completed, this function will free its resources and the task pointer will no longer be valid. the task will be removed from the queue. so like, don't go touching that pointer after, bestie, it's gone 👻

it is safe for multiple threads to call this function on the same queue at once; a completed task will only go to one of the threads. teamwork, but make it mutually exclusive 🫶

⚠️ note that by the nature of various platforms, more than one waiting thread may wake to handle a single task, but only one will obtain it — so timeoutMS is a maximum wait time, and this function may return false sooner. it's giving "false alarm, go back to bed" 😭

this function may return false if there was a system error, the OS inadvertently awoke multiple threads, or if SDL_SignalAsyncIOQueue() was called to wake up all waiting threads without a finished task. so false doesn't always mean timeout, iykyk 💀

a timeout can be used to specify a maximum wait time, but rather than polling, it is possible to have a timeout of -1 to wait forever, and use SDL_SignalAsyncIOQueue() to wake up the waiting threads later. obsessed with that pattern fr fr 🌈

---

🌸 FUNCTION PARAMETERS 🌸

• queue — the async I/O task queue to wait on. the one we're stanning 🎯
• outcome — details of a finished task will be written here. May not be NULL. not me stressing this, it's literally in the docs 🙈
• timeoutMS — the maximum time to wait, in milliseconds, or -1 to wait indefinitely. the "how long am I willing to be patient" number ⏳

---

👑 RETURN VALUE 👑

returns true if task has completed, false otherwise. binary. iconic. periodt 💅

---

⭐ THREAD SAFETY ⭐

it is safe to call this function from any thread. every thread is the main character here, we don't gatekeep 🌟

---

💜 AVAILABILITY 💜

this function is available since SDL 3.2.0. so if you're on something older... bestie, update 😭

---

🔥 SEE ALSO 🔥

• SDL_SignalAsyncIOQueue(3) — the "wake up babe, new task dropped" bestie to this function 🫶

---

and that's the page, my love 💖 written for Simple Directmedia Layer, SDL 3.4.18 edition — go forth, wait on your queues responsibly, and remember: -1 means forever, and forever is a long time 🌙✨