Documentation

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.

file

a UTF-8 string representing the filename to open.

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.

Thread safety

It is safe to call this function from any thread.

See also

sDL_CloseAsyncIO, sDL_ReadAsyncIO, sDL_WriteAsyncIO

C declaration

SDL_AsyncIOFromFile, defined at SDL3/SDL_asyncio.h 224:43

Since: 3.2.0

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.

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.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetAsyncIOSize, defined at SDL3/SDL_asyncio.h 241:36

Since: 3.2.0

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 task will be added to it when it completes its work.

asyncio

a pointer to an SDL_AsyncIO structure.

ptr

a pointer to a buffer to read data into.

offset

the position to start reading in the data source.

size

the number of bytes to read from the data source.

queue

a queue to add the new SDL_AsyncIO to.

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.

Thread safety

It is safe to call this function from any thread.

See also

sDL_WriteAsyncIO, sDL_CreateAsyncIOQueue

C declaration

SDL_ReadAsyncIO, defined at SDL3/SDL_asyncio.h 279:34

Since: 3.2.0

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 task will be added to it when it completes its work.

asyncio

a pointer to an SDL_AsyncIO structure.

ptr

a pointer to a buffer to write data from.

offset

the position to start writing to the data source.

size

the number of bytes to write to the data source.

queue

a queue to add the new SDL_AsyncIO to.

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.

Thread safety

It is safe to call this function from any thread.

See also

sDL_ReadAsyncIO, sDL_CreateAsyncIOQueue

C declaration

SDL_WriteAsyncIO, defined at SDL3/SDL_asyncio.h 316:34

Since: 3.2.0

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.

Once this function returns true, 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 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.

asyncio

a pointer to an SDL_AsyncIO structure to close.

flush

true if data should sync to disk before the task completes.

queue

a queue to add the new SDL_AsyncIO to.

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.

Thread safety

It is safe to call this function from any thread, but two threads should not attempt to close the same object.

C declaration

SDL_CloseAsyncIO, defined at SDL3/SDL_asyncio.h 365:34

Since: 3.2.0

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.

Thread safety

It is safe to call this function from any thread.

See also

sDL_DestroyAsyncIOQueue, sDL_GetAsyncIOResult, sDL_WaitAsyncIOResult

C declaration

SDL_CreateAsyncIOQueue, defined at SDL3/SDL_asyncio.h 384:48

Since: 3.2.0

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.

queue

the task queue to destroy.

Thread safety

It is safe to call this function from any thread, so long as no other thread is waiting on the queue with SDL_WaitAsyncIOResult.

C declaration

SDL_DestroyAsyncIOQueue, defined at SDL3/SDL_asyncio.h 414:34

Since: 3.2.0

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.

queue

the async I/O task queue to query.

outcome

details of a finished task will be written here. May not be NULL.

Returns

true if a task has completed, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

sDL_WaitAsyncIOResult

C declaration

SDL_GetAsyncIOResult, defined at SDL3/SDL_asyncio.h 440:34

Since: 3.2.0

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.

queue

the async I/O task queue to wait on.

outcome

details of a finished task will be written here. May not be NULL.

timeoutMS

the maximum time to wait, in milliseconds, or -1 to wait indefinitely.

Returns

true if task has completed, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SignalAsyncIOQueue

C declaration

SDL_WaitAsyncIOResult, defined at SDL3/SDL_asyncio.h 484:34

Since: 3.2.0

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).

queue

the async I/O task queue to signal.

Thread safety

It is safe to call this function from any thread.

See also

sDL_WaitAsyncIOResult

C declaration

SDL_SignalAsyncIOQueue, defined at SDL3/SDL_asyncio.h 508:34

Since: 3.2.0

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 task will be added to it when it completes its work.

file

the path to read all available data from.

queue

a queue to add the new SDL_AsyncIO to.

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.

Thread safety

It is safe to call this function from any thread.

See also

SDL_LoadFile_IO

C declaration

SDL_LoadFileAsync, defined at SDL3/SDL_asyncio.h 542:34

Since: 3.2.0