Sync SDL3 wiki -> header

[ci skip]

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 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.
+ * 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.
+ *
+ * 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
  */