SDL_CloseAsyncIO(3)

💅 SDL_CloseAsyncIO(3) — SDL3 FUNCTIONS 💅

okay bestie, welcome to the SDL_CloseAsyncIO(3) page from the SDL3 FUNCTIONS manual. we are closing async I/O objects today, and the vibe check says: asynchronous close is real. ✨

---

🎀 NAME 🎀

SDL_CloseAsyncIO — close and free any allocated resources for an async I/O object. periodt.

✨ SYNOPSIS ✨

literally the include and the signature, no cap:

#include <SDL3/SDL_asyncio.h>

bool SDL_CloseAsyncIO(SDL_AsyncIO *asyncio, bool flush, SDL_AsyncIOQueue *queue, void *userdata);

🦋 DESCRIPTION 🦋

Closing a file is also an asynchronous task! not me thinking close was a quick little side quest — if a write failure were to happen during the closing process, for example, the task results will report it as usual. so yeah, the close can spill tea too. 😭

Closing a file that has been written to does not guarantee the data has made it to physical media; it may remain in the operating system's file cache, for later writing to disk. This means that a successfully-closed file can be lost if the system crashes or loses power in this small window. that's the danger zone, bestie. To prevent this, call this function with the flush parameter set to true. This will make the operation take longer, and perhaps increase system load in general, but a successful result guarantees that the data has made it to physical storage. Don't use this for temporary files, caches, and unimportant data, and definitely use it for crucial irreplaceable files, like game saves. game saves are sacred, iykyk.

This function guarantees that the close will happen after any other pending tasks to asyncio, so it's safe to open a file, start several operations, close the file immediately, then check for all results later. This function will not block until the tasks have completed. so you can set it up and keep it moving, fr fr.

Once this function returns true, asyncio is no longer valid, regardless of any future outcomes. Any completed tasks might still contain this pointer in their SDL_AsyncIOOutcome data, in case the app was using this value to track information, but it should not be used again. do not reuse it, that's the rule.

If this function returns false, the close wasn't started at all, and it's safe to attempt to close again later.

An SDL_AsyncIOQueue must be specified. The newly-created task will be added to it when it completes its work. queue is mandatory, no skipping.

🌸 FUNCTION PARAMETERS 🌸

• asyncio — a pointer to an SDL_AsyncIO structure to close.
• flush — true if data should sync to disk before the task completes.
• queue — a queue to add the new SDL_AsyncIO to.
• userdata — an app-defined pointer that will be provided with the task results.

💖 RETURN VALUE 💖

Returns true on success or false on failure; call SDL_GetError() for more information. if it's giving false, go read the error, bestie.

🔒 THREAD SAFETY 🔒

It is safe to call this function from any thread, but two threads should not attempt to close the same object. do not let two threads try to close the same object — that's not the move.

📅 AVAILABILITY 📅

This function is available since SDL 3.2.0. periodt.

---

sign-off: source/version: Simple Directmedia Layer, SDL 3.4.18; date: not printed in the footer; page: SDL_CloseAsyncIO(3). mwah 💋