diff --git a/include/SDL3/SDL_asyncio.h b/include/SDL3/SDL_asyncio.h index 77f7c242d2..9498964340 100644 --- a/include/SDL3/SDL_asyncio.h +++ b/include/SDL3/SDL_asyncio.h @@ -24,12 +24,12 @@ /** * # CategoryAsyncIO * - * SDL offers a way to perform I/O asynchronously. This allows an app to - * read or write files without waiting for data to actually transfer; the - * functions that request I/O never block while the request is fulfilled. + * SDL offers a way to perform I/O asynchronously. This allows an app to read + * or write files without waiting for data to actually transfer; the functions + * that request I/O never block while the request is fulfilled. * - * Instead, the data moves in the background and the app can check for - * results at their leisure. + * Instead, the data moves in the background and the app can check for results + * at their leisure. * * This is more complicated that just reading and writing files in a * synchronous way, but it can allow for more efficiency, and never having @@ -41,15 +41,14 @@ * - Open files with SDL_AsyncIOFromFile. * - Start I/O tasks to the files with SDL_ReadAsyncIO or SDL_WriteAsyncIO, * putting those tasks into one of the queues. - * - Later on, use SDL_GetAsyncIOResult on a queue to see if any task - * is finished without blocking. Tasks might finish in any order with - * success or failure. - * - When all your tasks are done, close the file with SDL_CloseAsyncIO. - * This also generates a task, since it might flush data to disk! + * - Later on, use SDL_GetAsyncIOResult on a queue to see if any task is + * finished without blocking. Tasks might finish in any order with success + * or failure. + * - When all your tasks are done, close the file with SDL_CloseAsyncIO. This + * also generates a task, since it might flush data to disk! * - * This all works, without blocking, in a single thread, but one can also - * wait on a queue in a background thread, sleeping until new results - * have arrived: + * This all works, without blocking, in a single thread, but one can also wait + * on a queue in a background thread, sleeping until new results have arrived: * * - Call SDL_WaitAsyncIOResult from one or more threads to efficiently block * until new tasks complete. @@ -57,9 +56,9 @@ * threads despite there being no new tasks completed. * * And, of course, to match the synchronous SDL_LoadFile, we offer - * SDL_LoadFileAsync as a convenience function. This will handle allocating - * a buffer, slurping in the file data, and null-terminating it; you still - * get a task handle to check later. + * SDL_LoadFileAsync as a convenience function. This will handle allocating a + * buffer, slurping in the file data, and null-terminating it; you still get a + * task handle to check later. */ #ifndef SDL_asyncio_h_ @@ -131,8 +130,8 @@ typedef struct SDL_AsyncIOOutcome * * When starting an asynchronous operation, you specify a queue for the new * task. A queue can be asked later if any tasks in it have completed, - * allowing an app to manage multiple pending tasks in one place, in - * whatever order they complete. + * allowing an app to manage multiple pending tasks in one place, in whatever + * order they complete. * * \since This struct is available since SDL 3.0.0. * @@ -151,7 +150,8 @@ typedef struct SDL_AsyncIOQueue SDL_AsyncIOQueue; * The `mode` string understands the following values: * * - "r": Open a file for reading only. It must exist. - * - "w": Open a file for writing only. It will create missing files or truncate existing ones. + * - "w": Open a file for writing only. It will create missing files or + * truncate existing ones. * - "r+": Open a file for update both reading and writing. The file must * exist. * - "w+": Create an empty file for both reading and writing. If a file with @@ -174,7 +174,7 @@ typedef struct SDL_AsyncIOQueue SDL_AsyncIOQueue; * \returns a pointer to the SDL_AsyncIO structure that is created or NULL on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_CloseAsyncIO * \sa SDL_ReadAsyncIO @@ -185,8 +185,8 @@ extern SDL_DECLSPEC SDL_AsyncIO * SDLCALL SDL_AsyncIOFromFile(const char *file, /** * Use this function to get the size of the data stream in an SDL_AsyncIO. * - * This call is _not_ asynchronous; it assumes that obtaining this info - * is a non-blocking operation in most reasonable cases. + * This call is _not_ asynchronous; it assumes that obtaining this info is a + * non-blocking operation in most reasonable cases. * * \param asyncio the SDL_AsyncIO to get the size of the data stream from. * \returns the size of the data stream in the SDL_IOStream on success or a @@ -195,7 +195,7 @@ extern SDL_DECLSPEC SDL_AsyncIO * SDLCALL SDL_AsyncIOFromFile(const char *file, * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetAsyncIOSize(SDL_AsyncIO *asyncio); @@ -206,8 +206,8 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetAsyncIOSize(SDL_AsyncIO *asyncio); * source to the area pointed at by `ptr`. This function may read less bytes * than requested. * - * 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 + * 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. * @@ -223,13 +223,14 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetAsyncIOSize(SDL_AsyncIO *asyncio); * \param offset the position to start reading in the data source. * \param size the number of bytes to read from the data source. * \param queue a queue to add the new SDL_AsyncIO to. - * \param userdata an app-defined pointer that will be provided with the task results. + * \param userdata an app-defined pointer that will be provided with the task + * results. * \returns true on success or false on failure; call SDL_GetError() for more * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WriteAsyncIO * \sa SDL_CreateAsyncIOQueue @@ -240,8 +241,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadAsyncIO(SDL_AsyncIO *asyncio, void *ptr /** * Start an async write. * - * This function writes `size` bytes from `offset` position in the data - * source to the area pointed at by `ptr`. + * This function writes `size` bytes from `offset` position in the data source + * to the area pointed at by `ptr`. * * This function returns as quickly as possible; it does not wait for the * write to complete. On a successful return, this work will continue in the @@ -260,54 +261,51 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadAsyncIO(SDL_AsyncIO *asyncio, void *ptr * \param offset the position to start writing to the data source. * \param size the number of bytes to write to the data source. * \param queue a queue to add the new SDL_AsyncIO to. - * \param userdata an app-defined pointer that will be provided with the task results. + * \param userdata an app-defined pointer that will be provided with the task + * results. * \returns true on success or false on failure; call SDL_GetError() for more * information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_ReadAsyncIO * \sa SDL_CreateAsyncIOQueue * \sa SDL_GetAsyncIOTaskResult - */ extern SDL_DECLSPEC bool SDLCALL SDL_WriteAsyncIO(SDL_AsyncIO *asyncio, void *ptr, Uint64 offset, Uint64 size, SDL_AsyncIOQueue *queue, void *userdata); /** * Close and free any allocated resources for an async I/O object. * - * Closing a file is _also_ an asynchronous task! If a write failure - * were to happen during the closing process, for example, the - * task results will report it as usual. + * Closing a file is _also_ an asynchronous task! If a write failure were to + * happen during the closing process, for example, the task results will + * report it as usual. * - * 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. 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. + * 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. + * 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. * - * 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. + * 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. * * Once this function returns non-NULL, `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. + * 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. * - * If this function returns false, the close wasn't started at all, and - * it's safe to attempt to close again later. + * 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. @@ -315,29 +313,30 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteAsyncIO(SDL_AsyncIO *asyncio, void *pt * \param asyncio a pointer to an SDL_AsyncIO structure to close. * \param flush true if data should sync to disk before the task completes. * \param queue a queue to add the new SDL_AsyncIO to. - * \param userdata an app-defined pointer that will be provided with the task results. + * \param userdata an app-defined pointer that will be provided with the task + * results. * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \threadsafety It is safe to call this function from any thread, but - * two threads should not attempt to close the same object. + * \threadsafety It is safe to call this function from any thread, but two + * threads should not attempt to close the same object. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC bool SDLCALL SDL_CloseAsyncIO(SDL_AsyncIO *asyncio, bool flush, SDL_AsyncIOQueue *queue, void *userdata); /** * Create a task queue for tracking multiple I/O operations. * - * Async I/O operations are assigned to a queue when started. The - * queue can be checked for completed tasks thereafter. + * Async I/O operations are assigned to a queue when started. The queue can be + * checked for completed tasks thereafter. * * \returns a new task queue object or NULL if there was an error; call * SDL_GetError() for more information. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyAsyncIOQueue * \sa SDL_GetAsyncIOResult @@ -349,8 +348,8 @@ extern SDL_DECLSPEC SDL_AsyncIOQueue * SDLCALL SDL_CreateAsyncIOQueue(void); * Destroy a previously-created async I/O task queue. * * If there are still tasks pending for this queue, this call will block until - * those tasks are finished. All those tasks will be deallocated. Their results - * will be lost to the app. + * those tasks are finished. All those tasks will be deallocated. Their + * results will be lost to the app. * * Any pending reads from SDL_LoadFileAsync() that are still in this queue * will have their buffers deallocated by this function, to prevent a memory @@ -362,24 +361,25 @@ extern SDL_DECLSPEC SDL_AsyncIOQueue * SDLCALL SDL_CreateAsyncIOQueue(void); * * Do not destroy a queue that still has threads waiting on it through * SDL_WaitAsyncIOResult(). You can call SDL_SignalAsyncIOQueue() first to - * unblock those threads, and take measures (such as SDL_WaitThread()) to make sure - * they have finished their wait and won't wait on the queue again. + * unblock those threads, and take measures (such as SDL_WaitThread()) to make + * sure they have finished their wait and won't wait on the queue again. * * \param queue the task queue to destroy. * * \threadsafety It is safe to call this function from any thread, so long as - * no other thread is waiting on the queue with SDL_WaitAsyncIOResult. + * no other thread is waiting on the queue with + * SDL_WaitAsyncIOResult. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAsyncIOQueue(SDL_AsyncIOQueue *queue); /** * Query an async I/O task queue for completed tasks. * - * If a task assigned to this queue has finished, this will return true and fill in - * `outcome` with the details of the task. If no task in the queue has finished, - * this function will return false. This function does not block. + * If a task assigned to this queue has finished, this will return true and + * fill in `outcome` with the details of the task. If no task in the queue has + * finished, this function will return false. This function does not block. * * 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. @@ -388,12 +388,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAsyncIOQueue(SDL_AsyncIOQueue *queue * once; a completed task will only go to one of the threads. * * \param queue the async I/O task queue to query. - * \param outcome details of a finished task will be written here. May not be NULL. + * \param outcome details of a finished task will be written here. May not be + * NULL. * \returns true if task has completed, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WaitAsyncIOResult */ @@ -402,8 +403,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetAsyncIOResult(SDL_AsyncIOQueue *queue, S /** * Block until an async I/O task queue has a completed task. * - * This function puts the calling thread to sleep until there a task assigned to - * the queue that has finished. + * This function puts the calling thread to sleep until there a task assigned + * to the queue that has finished. * * If a task assigned to the queue has finished, this will return true and * fill in `outcome` with the details of the task. If no task in the queue has @@ -415,28 +416,29 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetAsyncIOResult(SDL_AsyncIOQueue *queue, S * 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. * - * 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. + * 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. * * 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. * - * 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 + * 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. * * \param queue the async I/O task queue to wait on. - * \param outcome details of a finished task will be written here. May not be NULL. + * \param outcome details of a finished task will be written here. May not be + * NULL. * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait * indefinitely. * \returns true if task has completed, false otherwise. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalAsyncIOQueue */ @@ -446,21 +448,21 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WaitAsyncIOResult(SDL_AsyncIOQueue *queue, * Wake up any threads that are blocking in SDL_WaitAsyncIOResult(). * * This will unblock any threads that are sleeping in a call to - * SDL_WaitAsyncIOResult for the specified queue, and cause them to - * return from that function. + * SDL_WaitAsyncIOResult for the specified queue, and cause them to return + * from that function. * - * This can be useful when destroying a queue to make sure nothing is - * touching it indefinitely. In this case, once this call completes, the - * caller should take measures to make sure any previously-blocked threads - * have returned from their wait and will not touch the queue again (perhaps - * by setting a flag to tell the threads to terminate and then using - * SDL_WaitThread() to make sure they've done so). + * This can be useful when destroying a queue to make sure nothing is touching + * it indefinitely. In this case, once this call completes, the caller should + * take measures to make sure any previously-blocked threads have returned + * from their wait and will not touch the queue again (perhaps by setting a + * flag to tell the threads to terminate and then using SDL_WaitThread() to + * make sure they've done so). * * \param queue the async I/O task queue to signal. * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_WaitAsyncIOResult */ @@ -469,8 +471,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SignalAsyncIOQueue(SDL_AsyncIOQueue *queue) /** * Load all the data from a file path, asynchronously. * - * 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 + * 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. * @@ -487,11 +489,12 @@ extern SDL_DECLSPEC void SDLCALL SDL_SignalAsyncIOQueue(SDL_AsyncIOQueue *queue) * * \param file the path to read all available data from. * \param queue a queue to add the new SDL_AsyncIO to. - * \param userdata an app-defined pointer that will be provided with the task results. + * \param userdata an app-defined pointer that will be provided with the task + * results. * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.0.0. + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadFile_IO */