From 31d09909b67408c22509e94d10283aef7ae501f5 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Tue, 3 Dec 2024 23:04:47 +0000
Subject: [PATCH] Sync SDL3 wiki -> header
[ci skip]
---
include/SDL3/SDL_asyncio.h | 203 +++++++++++++++++++------------------
1 file changed, 103 insertions(+), 100 deletions(-)
diff --git a/include/SDL3/SDL_asyncio.h b/include/SDL3/SDL_asyncio.h
index 77f7c242d2d40..9498964340fef 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 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
*/