mirror of
https://github.com/libsdl-org/SDL.git
synced 2025-05-28 07:29:09 +00:00
Sync SDL3 wiki -> header
[ci skip]
This commit is contained in:
SDL Wiki Bot
parent
1377cdb3f2
commit
31d09909b6
1 changed files with 101 additions and 98 deletions
|
|
@ -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
|
||||
*/
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue