SDL_ReadAsyncIO(3)

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

✨ NAME ✨

SDL_ReadAsyncIO — start an async read. periodt 💅

This is the tea from the SDL3 FUNCTIONS manual, page SDL_ReadAsyncIO(3), and bestie we are gonna get you reading async like a main character. 🫶

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_asyncio.h>

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

🦋 DESCRIPTION 🦋

okay so literally, this function reads up to size bytes from offset position in the data source to the area pointed at by ptr. Important: this function may read less bytes than requested. not a bug, just how it is, iykyk.

This function returns as quickly as possible; it does not wait for the read to complete. On a successful return, this work will continue in the background. If the work begins, even failure is asynchronous: a failing return value from this function only means the work couldn't start at all. the way that is so real.

ptr must remain available until the work is done, and may be accessed by the system at any time until then. Do not allocate it on the stack, as this might take longer than the life of the calling function to complete! 🚨

An SDL_AsyncIOQueue must be specified. The newly-created task will be added to it when it completes its work. slay, queue behavior understood. ✨

🎀 FUNCTION PARAMETERS 🎀

  • asyncio — a pointer to an SDL_AsyncIO structure. the source of the vibes.
  • ptr — a pointer to a buffer to read data into. keep it alive, bestie!
  • offset — the position to start reading in the data source. where the read begins.
  • size — the number of bytes to read from the data source. the amount, the quantity, the requested bytes.
  • queue — a queue to add the new SDL_AsyncIO to. task drop-off spot.
  • userdata — an app-defined pointer that will be provided with the task results. your little custom note passed along.

💖 RETURN VALUE 💖

Returns true on success or false on failure; call SDL_GetError() for more information. so if it's giving false, go ask SDL_GetError() what happened. 😭

🔥 THREAD SAFETY 🔥

It is safe to call this function from any thread. any thread! no cap! 🧚

👑 AVAILABILITY 👑

This function is available since SDL 3.2.0. ⭐

🌈 SEE ALSO 🌈

and that's the whole page, bestie! 💖 This iconic little manual moment comes from Simple Directmedia Layer, version SDL 3.4.18, and it is literally the SDL_ReadAsyncIO(3) page. bye bye, go read async responsibly! 🎀🦋💅

📦 where this page comes from