|
|
@@ -0,0 +1,506 @@
|
|
|
+/*
|
|
|
+ Simple DirectMedia Layer
|
|
|
+ Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
|
|
|
+
|
|
|
+ This software is provided 'as-is', without any express or implied
|
|
|
+ warranty. In no event will the authors be held liable for any damages
|
|
|
+ arising from the use of this software.
|
|
|
+
|
|
|
+ Permission is granted to anyone to use this software for any purpose,
|
|
|
+ including commercial applications, and to alter it and redistribute it
|
|
|
+ freely, subject to the following restrictions:
|
|
|
+
|
|
|
+ 1. The origin of this software must not be misrepresented; you must not
|
|
|
+ claim that you wrote the original software. If you use this software
|
|
|
+ in a product, an acknowledgment in the product documentation would be
|
|
|
+ appreciated but is not required.
|
|
|
+ 2. Altered source versions must be plainly marked as such, and must not be
|
|
|
+ misrepresented as being the original software.
|
|
|
+ 3. This notice may not be removed or altered from any source distribution.
|
|
|
+*/
|
|
|
+
|
|
|
+/* WIKI CATEGORY: AsyncIO */
|
|
|
+
|
|
|
+/**
|
|
|
+ * # 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.
|
|
|
+ *
|
|
|
+ * 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
|
|
|
+ * framerate drops as the hard drive catches up, etc.
|
|
|
+ *
|
|
|
+ * The general usage pattern for async I/O is:
|
|
|
+ *
|
|
|
+ * - Create one or more SDL_AsyncIOQueue objects.
|
|
|
+ * - 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!
|
|
|
+ *
|
|
|
+ * 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.
|
|
|
+ * - When shutting down, call SDL_SignalAsyncIOQueue to unblock any sleeping
|
|
|
+ * 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.
|
|
|
+ */
|
|
|
+
|
|
|
+#ifndef SDL_asyncio_h_
|
|
|
+#define SDL_asyncio_h_
|
|
|
+
|
|
|
+#include <SDL3/SDL_stdinc.h>
|
|
|
+
|
|
|
+#include <SDL3/SDL_begin_code.h>
|
|
|
+/* Set up for C function definitions, even when using C++ */
|
|
|
+#ifdef __cplusplus
|
|
|
+extern "C" {
|
|
|
+#endif
|
|
|
+
|
|
|
+/**
|
|
|
+ * The asynchronous I/O operation structure.
|
|
|
+ *
|
|
|
+ * This operates as an opaque handle. One can then request read or write
|
|
|
+ * operations on it.
|
|
|
+ *
|
|
|
+ * \since This struct is available since SDL 3.0.0.
|
|
|
+ *
|
|
|
+ * \sa SDL_AsyncIOFromFile
|
|
|
+ */
|
|
|
+typedef struct SDL_AsyncIO SDL_AsyncIO;
|
|
|
+
|
|
|
+/**
|
|
|
+ * Types of asynchronous I/O tasks.
|
|
|
+ *
|
|
|
+ * \since This enum is available since SDL 3.0.0.
|
|
|
+ */
|
|
|
+typedef enum SDL_AsyncIOTaskType
|
|
|
+{
|
|
|
+ SDL_ASYNCIO_TASK_READ, /**< A read operation. */
|
|
|
+ SDL_ASYNCIO_TASK_WRITE, /**< A write operation. */
|
|
|
+ SDL_ASYNCIO_TASK_CLOSE /**< A close operation. */
|
|
|
+} SDL_AsyncIOTaskType;
|
|
|
+
|
|
|
+/**
|
|
|
+ * Possible outcomes of an asynchronous I/O task.
|
|
|
+ *
|
|
|
+ * \since This enum is available since SDL 3.0.0.
|
|
|
+ */
|
|
|
+typedef enum SDL_AsyncIOResult
|
|
|
+{
|
|
|
+ SDL_ASYNCIO_COMPLETE, /**< request was completed without error */
|
|
|
+ SDL_ASYNCIO_FAILURE, /**< request failed for some reason; check SDL_GetError()! */
|
|
|
+ SDL_ASYNCIO_CANCELLED /**< request was cancelled before completing. */
|
|
|
+} SDL_AsyncIOResult;
|
|
|
+
|
|
|
+/**
|
|
|
+ * Information about a completed asynchronous I/O request.
|
|
|
+ *
|
|
|
+ * \since This struct is available since SDL 3.0.0.
|
|
|
+ */
|
|
|
+typedef struct SDL_AsyncIOOutcome
|
|
|
+{
|
|
|
+ SDL_AsyncIO *asyncio; /**< what generated this task. This pointer will be invalid if it was closed! */
|
|
|
+ SDL_AsyncIOTaskType type; /**< What sort of task was this? Read, write, etc? */
|
|
|
+ SDL_AsyncIOResult result; /**< the result of the work (success, failure, cancellation). */
|
|
|
+ void *buffer; /**< buffer where data was read/written. */
|
|
|
+ Uint64 offset; /**< offset in the SDL_AsyncIO where data was read/written. */
|
|
|
+ Uint64 bytes_requested; /**< number of bytes the task was to read/write. */
|
|
|
+ Uint64 bytes_transferred; /**< actual number of bytes that were read/written. */
|
|
|
+ void *userdata; /**< pointer provided by the app when starting the task */
|
|
|
+} SDL_AsyncIOOutcome;
|
|
|
+
|
|
|
+/**
|
|
|
+ * An opaque handle for asynchronous I/O tasks.
|
|
|
+ *
|
|
|
+ * Each asynchronous read or write operation generates a task, which will
|
|
|
+ * complete at some time in the future. This handle is used to track the
|
|
|
+ * progress of that task.
|
|
|
+ *
|
|
|
+ * Tasks are added to an SDL_AsyncIOQueue, where they can be queried for
|
|
|
+ * completion later.
|
|
|
+ *
|
|
|
+ * \since This struct is available since SDL 3.0.0.
|
|
|
+ *
|
|
|
+ * \sa SDL_ReadAsyncIO
|
|
|
+ * \sa SDL_WriteAsyncIO
|
|
|
+ */
|
|
|
+typedef struct SDL_AsyncIOTask SDL_AsyncIOTask;
|
|
|
+
|
|
|
+/**
|
|
|
+ * A queue of completed asynchronous I/O tasks.
|
|
|
+ *
|
|
|
+ * 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.
|
|
|
+ *
|
|
|
+ * \since This struct is available since SDL 3.0.0.
|
|
|
+ *
|
|
|
+ * \sa SDL_CreateAsyncIOQueue
|
|
|
+ * \sa SDL_ReadAsyncIO
|
|
|
+ * \sa SDL_WriteAsyncIO
|
|
|
+ * \sa SDL_GetAsyncIOResult
|
|
|
+ * \sa SDL_WaitAsyncIOResult
|
|
|
+ */
|
|
|
+typedef struct SDL_AsyncIOQueue SDL_AsyncIOQueue;
|
|
|
+
|
|
|
+/**
|
|
|
+ * Use this function to create a new SDL_AsyncIO object for reading from
|
|
|
+ * and/or writing to a named file.
|
|
|
+ *
|
|
|
+ * 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.
|
|
|
+ * - "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
|
|
|
+ * the same name already exists its content is erased and the file is
|
|
|
+ * treated as a new empty file.
|
|
|
+ *
|
|
|
+ * There is no "b" mode, as there is only "binary" style I/O, and no "a" mode
|
|
|
+ * for appending, since you specify the position when starting a task.
|
|
|
+ *
|
|
|
+ * This function supports Unicode filenames, but they must be encoded in UTF-8
|
|
|
+ * format, regardless of the underlying operating system.
|
|
|
+ *
|
|
|
+ * This call is _not_ asynchronous; it will open the file before returning,
|
|
|
+ * under the assumption that doing so is generally a fast operation. Future
|
|
|
+ * reads and writes to the opened file will be async, however.
|
|
|
+ *
|
|
|
+ * \param file a UTF-8 string representing the filename to open.
|
|
|
+ * \param mode an ASCII string representing the mode to be used for opening
|
|
|
+ * the file.
|
|
|
+ * \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.
|
|
|
+ *
|
|
|
+ * \sa SDL_CloseAsyncIO
|
|
|
+ * \sa SDL_ReadAsyncIO
|
|
|
+ * \sa SDL_WriteAsyncIO
|
|
|
+ */
|
|
|
+extern SDL_DECLSPEC SDL_AsyncIO * SDLCALL SDL_AsyncIOFromFile(const char *file, const char *mode);
|
|
|
+
|
|
|
+/**
|
|
|
+ * 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.
|
|
|
+ *
|
|
|
+ * \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
|
|
|
+ * negative error code 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.
|
|
|
+ */
|
|
|
+extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetAsyncIOSize(SDL_AsyncIO *asyncio);
|
|
|
+
|
|
|
+/**
|
|
|
+ * Start an async read.
|
|
|
+ *
|
|
|
+ * This function reads up to `size` bytes from `offset` position in the data
|
|
|
+ * 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
|
|
|
+ * 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.
|
|
|
+ *
|
|
|
+ * `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 SDL_AsyncIOTask
|
|
|
+ * will be added to it when it completes its work.
|
|
|
+ *
|
|
|
+ * \param asyncio a pointer to an SDL_AsyncIO structure.
|
|
|
+ * \param ptr a pointer to a buffer to read data into.
|
|
|
+ * \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.
|
|
|
+ * \returns A new task handle if a task was started, NULL on complete 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.
|
|
|
+ *
|
|
|
+ * \sa SDL_WriteAsyncIO
|
|
|
+ * \sa SDL_CreateAsyncIOQueue
|
|
|
+ * \sa SDL_GetAsyncIOTaskResult
|
|
|
+ */
|
|
|
+extern SDL_DECLSPEC SDL_AsyncIOTask * SDLCALL SDL_ReadAsyncIO(SDL_AsyncIO *asyncio, void *ptr, Uint64 offset, Uint64 size, SDL_AsyncIOQueue *queue, void *userdata);
|
|
|
+
|
|
|
+/**
|
|
|
+ * 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 returns as quickly as possible; it does not wait for the
|
|
|
+ * write 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.
|
|
|
+ *
|
|
|
+ * `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 SDL_AsyncIOTask
|
|
|
+ * will be added to it when it completes its work.
|
|
|
+ *
|
|
|
+ * \param asyncio a pointer to an SDL_AsyncIO structure.
|
|
|
+ * \param ptr a pointer to a buffer to write data from.
|
|
|
+ * \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.
|
|
|
+ * \returns A new task handle if a task was started, NULL on complete 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.
|
|
|
+ *
|
|
|
+ * \sa SDL_ReadAsyncIO
|
|
|
+ * \sa SDL_CreateAsyncIOQueue
|
|
|
+ * \sa SDL_GetAsyncIOTaskResult
|
|
|
+
|
|
|
+ */
|
|
|
+extern SDL_DECLSPEC SDL_AsyncIOTask * 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.
|
|
|
+ *
|
|
|
+ * 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.
|
|
|
+ *
|
|
|
+ * If this function returns NULL, the close wasn't started at all, and
|
|
|
+ * it's safe to attempt to close again later.
|
|
|
+ *
|
|
|
+ * \param asyncio a pointer to an SDL_AsyncIO structure to close.
|
|
|
+ * \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.
|
|
|
+ * \returns A new task handle if a task was started, NULL on complete 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.
|
|
|
+ *
|
|
|
+ * \since This function is available since SDL 3.0.0.
|
|
|
+ */
|
|
|
+extern SDL_DECLSPEC SDL_AsyncIOTask * SDLCALL SDL_CloseAsyncIO(SDL_AsyncIO *asyncio, 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.
|
|
|
+ *
|
|
|
+ * \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.
|
|
|
+ *
|
|
|
+ * \sa SDL_DestroyAsyncIOQueue
|
|
|
+ * \sa SDL_GetAsyncIOResult
|
|
|
+ * \sa SDL_WaitAsyncIOResult
|
|
|
+ */
|
|
|
+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.
|
|
|
+ *
|
|
|
+ * Any pending reads from SDL_LoadFileAsync() that are still in this queue
|
|
|
+ * will have their buffers deallocated by this function, to prevent a memory
|
|
|
+ * leak.
|
|
|
+ *
|
|
|
+ * Once this function is called, the queue is no longer valid and should not
|
|
|
+ * be used, including by other threads that might access it while destruction
|
|
|
+ * is blocking on pending tasks.
|
|
|
+ *
|
|
|
+ * 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.
|
|
|
+ *
|
|
|
+ * \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.
|
|
|
+ *
|
|
|
+ * \since This function is available since SDL 3.0.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 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.
|
|
|
+ *
|
|
|
+ * 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.
|
|
|
+ *
|
|
|
+ * \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.
|
|
|
+ * \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.
|
|
|
+ *
|
|
|
+ * \sa SDL_WaitAsyncIOResult
|
|
|
+ */
|
|
|
+extern SDL_DECLSPEC bool SDLCALL SDL_GetAsyncIOResult(SDL_AsyncIOQueue *queue, SDL_AsyncIOOutcome *outcome);
|
|
|
+
|
|
|
+/**
|
|
|
+ * 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.
|
|
|
+ *
|
|
|
+ * 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
|
|
|
+ * finished, this function will return false.
|
|
|
+ *
|
|
|
+ * 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.
|
|
|
+ *
|
|
|
+ * 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.
|
|
|
+ *
|
|
|
+ * 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
|
|
|
+ * 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 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.
|
|
|
+ *
|
|
|
+ * \sa SDL_SignalAsyncIOQueue
|
|
|
+ */
|
|
|
+extern SDL_DECLSPEC bool SDLCALL SDL_WaitAsyncIOResult(SDL_AsyncIOQueue *queue, SDL_AsyncIOOutcome *outcome, Sint32 timeoutMS);
|
|
|
+
|
|
|
+/**
|
|
|
+ * 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.
|
|
|
+ *
|
|
|
+ * 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.
|
|
|
+ *
|
|
|
+ * \sa SDL_WaitAsyncIOResult
|
|
|
+ */
|
|
|
+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
|
|
|
+ * 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 data is allocated with a zero byte at the end (null terminated) for
|
|
|
+ * convenience. This extra byte is not included in SDL_AsyncIOOutcome's
|
|
|
+ * bytes_transferred value.
|
|
|
+ *
|
|
|
+ * This function will allocate the buffer to contain the file. It must be
|
|
|
+ * deallocated by calling SDL_free() on SDL_AsyncIOOutcome's buffer field
|
|
|
+ * after completion.
|
|
|
+ *
|
|
|
+ * An SDL_AsyncIOQueue must be specified. The newly-created SDL_AsyncIOTask
|
|
|
+ * will be added to it when it completes its work.
|
|
|
+ *
|
|
|
+ * \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.
|
|
|
+ * \returns an async task, to be queried for results later.
|
|
|
+ *
|
|
|
+ * \since This function is available since SDL 3.0.0.
|
|
|
+ *
|
|
|
+ * \sa SDL_LoadFile_IO
|
|
|
+ */
|
|
|
+extern SDL_DECLSPEC SDL_AsyncIOTask * SDLCALL SDL_LoadFileAsync(const char *file, SDL_AsyncIOQueue *queue, void *userdata);
|
|
|
+
|
|
|
+/* Ends C function definitions when using C++ */
|
|
|
+#ifdef __cplusplus
|
|
|
+}
|
|
|
+#endif
|
|
|
+#include <SDL3/SDL_close_code.h>
|
|
|
+
|
|
|
+#endif /* SDL_asyncio_h_ */
|
Ryan C. Gordon