SDL_WriteAsyncIO(3)

📦
version 3.4.18 · 9 versions
, in fedora 43, fedora 44

💫 SDL_WriteAsyncIO — NAME 💫

okay bestie, welcome to the SDL3 FUNCTIONS corner of the manual, this one's called SDL_WriteAsyncIO and it's literally here to Start an async write. that's it, that's the whole vibe. ✨

🦋 SYNOPSIS 🦋

#include <SDL3/SDL_asyncio.h>

bool SDL_WriteAsyncIO(SDL_AsyncIO *asyncio, void *ptr, Uint64 offset, Uint64 size, SDL_AsyncIOQueue *queue, void *userdata);

look at her. six parameters. main character energy fr fr. 💅

🌸 DESCRIPTION 🌸

so what's actually happening here? this function writes size bytes, starting from the offset position in the data source, into the area pointed at by ptr. iconic. 🎀

the whole point is that this function returns as quickly as possible — it does not sit around waiting for the write to finish. on a successful return, the work just keeps going in the background like it's got its own little life. and here's the twist that lowkey trips people up: if the work does begin, then even failure is asynchronous. a failing return value from this function only means the work couldn't start at all. periodt. 💀

⚠️ bestie listen. ptr must remain available until the work is done, and it may be accessed by the system at any time until then. Do not allocate it on the stack — this might take longer than the life of the calling function to complete! 🙈 that's a real "not me getting a dangling pointer" moment and we are NOT doing that.

an SDL_AsyncIOQueue must be specified — no queue, no service. the newly-created task gets added to it when it completes its work. 🫶

🧚 FUNCTION PARAMETERS 🧚

  • asyncio — a pointer to an SDL_AsyncIO structure. the source of truth, the data source in question.
  • ptr — a pointer to a buffer to write data from. (yes, from — keep it alive, see the warning above 🫣)
  • offset — the position to start writing to the data source.
  • size — the number of bytes to write to the data source.
  • queue — a queue to add the new SDL_AsyncIO to.
  • userdata — an app-defined pointer that will be provided with the task results. your little note-to-self that comes back to you later. 💌

⭐ RETURN VALUE ⭐

returns true on success or false on failure; call SDL_GetError() for more information. and remember the lore from above: a false here means the work couldn't start, not necessarily that the write failed. iykyk. 🔥

🔒 THREAD SAFETY 🔒

It is safe to call this function from any thread. yes queen, any thread, go off. 👑

🌈 AVAILABILITY 🌈

This function is available since SDL 3.2.0. glow-up complete. ✨

👀 SEE ALSO 👀

and that's the whole page, bestie!! 💖 brought to you by the lovely folks at Simple Directmedia Layer, this edition stamped SDL 3.4.18 — thanks for reading, mwah, slay, bye!! 🎀🦋💅

📦 where this page comes from