Class AsyncIO

Namespace

Sdl3Sharp.IO

Assembly

Sdl3Sharp.dll

An asynchronous I/O stream handle

public sealed class AsyncIO : IDisposable

Inheritance

object

AsyncIO

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

AsyncIO(string, FileAccess, FileMode, AsyncIOQueue?, bool)

Creates a new AsyncIO instance for the specified file name, access, and mode

public AsyncIO(string fileName, FileAccess access, FileMode mode, AsyncIOQueue? closeOnDisposeQueue = null, bool closeOnDisposeFlush = true)

Parameters

fileName string

The name of the file to open

access FileAccess

The FileAccess value representing the access mode

mode FileMode

The FileMode value representing the file mode

closeOnDisposeQueue AsyncIOQueue

A value indicating whether to flush the AsyncIO when automatically closing it. Has no effect if closeOnDisposeQueue is null. This parameter is reflected by the CloseOnDisposeFlush property. Changing the value of the CloseOnDisposeFlush property after construction also changes the automatic closing behavior.

closeOnDisposeFlush bool

A value indicating whether to flush the AsyncIO when automatically closing it. Has no effect if closeOnDisposeQueue is null. This parameter is reflected by the CloseOnDisposeFlush property. Changing the value of the CloseOnDisposeFlush property after construction also changes the automatic closing behavior.

Remarks

Opening a file is not an asynchronous operation under the assumption that doing so is generally a fast operation. Future reading and writing operations to the AsyncIO will be asynchronous though.

There's no support for specifying a FileKind value, as all asynchronous file I/O is performed in binary mode, and there's no support for Append, since you specify offsets explicitly when reading and writing.

Exceptions

SdlException

The AsyncIO could not be created (check TryGet(out string?) for more information)

ArgumentException

The combination of access and mode is invalid

AsyncIO(string, string, AsyncIOQueue?, bool)

Creates a new AsyncIO instance for the specified file name and mode string

public AsyncIO(string fileName, string modeString, AsyncIOQueue? closeOnDisposeQueue = null, bool closeOnDisposeFlush = true)

Parameters

fileName string

The name of the file to open

modeString string

The mode string to use when opening the file

closeOnDisposeQueue AsyncIOQueue

An AsyncIOQueue to use if the newly created AsyncIO should be automatically closed when disposed. Set to null to disable automatic closing behavior. This parameter is reflected by the CloseOnDisposeQueue property. Changing the value of the CloseOnDisposeQueue property after construction also changes the automatic closing behavior.

closeOnDisposeFlush bool

A value indicating whether to flush the AsyncIO when automatically closing it. Has no effect if closeOnDisposeQueue is null. This parameter is reflected by the CloseOnDisposeFlush property. Changing the value of the CloseOnDisposeFlush property after construction also changes the automatic closing behavior.

Remarks

Opening a file is not an asynchronous operation under the assumption that doing so is generally a fast operation. Future reading and writing operations to the AsyncIO will be asynchronous though.

The mode strings used by this method are roughly the same as the ones used by the C standard library's fopen function with some exceptions. You can use TryGetModeString(FileAccess, FileMode, out string?) to construct valid mode strings. There's no support for binary/text modes ("b"/"t"), as all asynchronous file I/O is performed in binary mode, and there's no support for appending mode ("a"), since you specify offsets explicitly when reading and writing.

Exceptions

SdlException

The AsyncIO could not be created (check TryGet(out string?) for more information)

Properties

CloseOnDisposeFlush

Gets or sets a value indicating whether to flush the AsyncIO when automatically closing it

public bool CloseOnDisposeFlush { get; set; }

Property Value

bool

A value indicating whether to flush the AsyncIO when automatically closing it

Remarks

The value of this property has no effect if the value of the CloseOnDisposeQueue property is null.

CloseOnDisposeQueue

Gets or sets an AsyncIOQueue to use if the AsyncIO should be automatically closed when disposed

public AsyncIOQueue? CloseOnDisposeQueue { get; set; }

Property Value

AsyncIOQueue

An AsyncIOQueue to use if the AsyncIO should be automatically closed when disposed

Remarks

If the value of this property is null, the AsyncIO will not be automatically closed when disposed. Changing the value of this property will also change the automatic closing behavior.

CloseOnDisposeUserdata

Gets or sets user-defined data to associate if the AsyncIO should be automatically closed when disposed

public object? CloseOnDisposeUserdata { get; set; }

Property Value

object

User-defined data to associate if the AsyncIO should be automatically closed when disposed

Remarks

The value of this property will be provided as the Userdata property's value of the AsyncIOOutcome returned by the automatic closing operation.

IsValid

Gets a value indicating whether the AsyncIO is valid

public bool IsValid { get; }

Property Value

bool

A value indicating whether the AsyncIO is valid

Remarks

An AsyncIO becomes invalid after it has been closed or disposed.

Length

Gets the length, in bytes, of the underlying data stream

public long Length { get; }

Property Value

long

The length, in bytes, of the underlying data stream, or -1 if the length could not be determined (check TryGet(out string?) for more information)

Remarks

Obtaining the length of the underlying data stream is not an asynchronous operation under the assumption that it is non-blocking in most reasonable scenarios.

SdlAsyncIO

Gets a pointer to the underlying SDL SDL_AsyncIO that the AsyncIO represents

public nint SdlAsyncIO { get; }

Property Value

nint

A pointer to the underlying SDL SDL_AsyncIO that the AsyncIO represents. This can be cast to a SDL SDL_AsyncIO*.

Methods

Dispose()

Disposes the AsyncIO and potentially closes it asynchronously

public void Dispose()

Remarks

If the CloseOnDisposeQueue property is set to a non-null value, the AsyncIO will be automatically closed when this method is called. The automatic closing behavior of the AsyncIO (if any) will always just attempt a single try to initiate a closing operation.

~AsyncIO()

protected ~AsyncIO()

TryClose(bool, AsyncIOQueue, object?)

Tries to asynchronously close the AsyncIO

public bool TryClose(bool flush, AsyncIOQueue queue, object? userdata = null)

Parameters

flush bool

A value indicating whether to flush the AsyncIO before closing it

queue AsyncIOQueue

The AsyncIOQueue to add the asynchronous closing operation to

userdata object

User-defined data to associate with the asynchronous closing operation. This will be provided as the Userdata property's value of the AsyncIOOutcome returned by the operation.

Returns

bool

true, if the asynchronous closing operation was initiated successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

Closing an AsyncIO is also an asynchronous operation.

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 method with the flush argument 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. Set the flush argument to false for temporary files, caches, and unimportant data, and definitely set it to true for crucial irreplaceable files, like game saves.

This method guarantees that the closing operation will happen after any other pending tasks to the AsyncIO. So it's safe to open a file, start several operations, close the AsyncIO immediately, then check for all results later. This method will not block until the tasks have completed.

Once this method returns true, the AsyncIO is no longer valid, regardless of any future outcomes. Any completed operation might still point to this AsyncIO in their AsyncIOOutcome, in case it's used to track information, but it should not be used again.

If this method returns false, the closing operation wasn't initiated at all, and it's safe to attempt to close again later. The automatic closing behavior of the AsyncIO (if any) will always just attempt a single try to initiate a closing operation.

The newly created asynchronous closing operation will be added to the specified queue.

TryGetModeString(FileAccess, FileMode, out string?)

Tries to get the mode string for the specified access and mode

public static bool TryGetModeString(FileAccess access, FileMode mode, out string? modeString)

Parameters

access FileAccess

The FileAccess value representing the access mode

mode FileMode

The FileMode value representing the file mode

modeString string

The resulting mode string, when this method returns true; otherwise, null

Returns

bool

true, if the mode string was successfully retrieved; otherwise, false

Remarks

A mode string constructed by this method is roughly the same as the ones used by the C standard library's fopen function with some exceptions. There's no support for appending mode ("a"), since you specify offsets explicitly when reading and writing in asynchronous file I/O.

TryRead(NativeMemory, ulong, AsyncIOQueue, object?)

Tries to asynchronously read data from the AsyncIO

public bool TryRead(NativeMemory data, ulong offset, AsyncIOQueue queue, object? userdata = null)

Parameters

data NativeMemory

The memory buffer to read data into

offset ulong

The offset within underlying data stream to start reading from

queue AsyncIOQueue

The AsyncIOQueue to add the asynchronous reading operation to

userdata object

User-defined data to associate with the asynchronous reading operation. This will be provided as the Userdata property's value of the AsyncIOOutcome returned by the operation.

Returns

bool

true, if the reading operation was initiated successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The asynchronous reading operation might read less bytes than requested by data's Length property.

This method returns as quickly as possible; it does not wait for the reading operation to complete. On a successful return, this work will continue in the background. If the work begins, even a failure is asynchronous: a failing return value from this method only means the reading operation couldn't get initiated.

This method will pin the specified data until the AsyncIOOutcome of the reading operation is disposed.

The newly created asynchronous reading operation will be added to the specified queue.

TryRead(Memory<byte>, ulong, AsyncIOQueue, object?)

Tries to asynchronously read data from the AsyncIO

public bool TryRead(Memory<byte> data, ulong offset, AsyncIOQueue queue, object? userdata = null)

Parameters

data Memory<byte>

The Memory<T> to read data into

offset ulong

The offset within underlying data stream to start reading from

queue AsyncIOQueue

The AsyncIOQueue to add the asynchronous reading operation to

userdata object

User-defined data to associate with the asynchronous reading operation. This will be provided as the Userdata property's value of the AsyncIOOutcome returned by the operation.

Returns

bool

true, if the reading operation was initiated successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The asynchronous reading operation might read less bytes than requested by data's Length property.

This method returns as quickly as possible; it does not wait for the reading operation to complete. On a successful return, this work will continue in the background. If the work begins, even a failure is asynchronous: a failing return value from this method only means the reading operation couldn't get initiated.

This method will pin the specified data until the AsyncIOOutcome of the reading operation is disposed.

The newly created asynchronous reading operation will be added to the specified queue.

TryRead(void*, ulong, ulong, AsyncIOQueue, object?)

Tries to asynchronously read data from the AsyncIO

public bool TryRead(void* data, ulong offset, ulong size, AsyncIOQueue queue, object? userdata = null)

Parameters

data void*

A pointer to the unmananged memory to read data into

offset ulong

The offset within underlying data stream to start reading from

size ulong

The number of bytes to read

queue AsyncIOQueue

The AsyncIOQueue to add the asynchronous reading operation to

userdata object

User-defined data to associate with the asynchronous reading operation. This will be provided as the Userdata property's value of the AsyncIOOutcome returned by the operation.

Returns

bool

true, if the reading operation was initiated successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The asynchronous reading operation might read less bytes than requested by size.

This method returns as quickly as possible; it does not wait for the reading operation to complete. On a successful return, this work will continue in the background. If the work begins, even a failure is asynchronous: a failing return value from this method only means the reading operation couldn't get initiated.

The unmanaged memory pointed to by data must be safely dereferencable for at least size bytes and must remain valid until the AsyncIOOutcome of the reading operation is disposed.

The newly created asynchronous reading operation will be added to the specified queue.

TryUnsafeClose(bool, AsyncIOQueue, void*)

Tries to asynchronously close the AsyncIO

public bool TryUnsafeClose(bool flush, AsyncIOQueue queue, void* userdata = null)

Parameters

flush bool

A value indicating whether to flush the AsyncIO before closing it

queue AsyncIOQueue

The AsyncIOQueue to add the asynchronous closing operation to

userdata void*

A pointer to unmanaged user-defined data to associate with the asynchronous closing operation. This will be provided as the UnsafeUserdata property's value of the AsyncIOOutcome returned by the operation.

Returns

bool

true, if the asynchronous closing operation was initiated successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

Closing an AsyncIO is also an asynchronous operation.

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 method with the flush argument 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. Set the flush argument to false for temporary files, caches, and unimportant data, and definitely set it to true for crucial irreplaceable files, like game saves.

This method guarantees that the closing operation will happen after any other pending tasks to the AsyncIO. So it's safe to open a file, start several operations, close the AsyncIO immediately, then check for all results later. This method will not block until the tasks have completed.

Once this method returns true, the AsyncIO is no longer valid, regardless of any future outcomes. Any completed operation might still point to this AsyncIO in their AsyncIOOutcome, in case it's used to track information, but it should not be used again.

If this method returns false, the closing operation wasn't initiated at all, and it's safe to attempt to close again later. The automatic closing behavior of the AsyncIO (if any) will always just attempt a single try to initiate a closing operation.

The unmanaged user-defined data pointed to by userdata must remain valid until the AsyncIOOutcome of the reading operation is disposed.

The newly created asynchronous closing operation will be added to the specified queue.

TryUnsafeRead(void*, ulong, ulong, AsyncIOQueue, void*)

Tries to asynchronously read data from the AsyncIO

public bool TryUnsafeRead(void* data, ulong offset, ulong size, AsyncIOQueue queue, void* userdata = null)

Parameters

data void*

A pointer to the unmananged memory to read data into

offset ulong

The offset within underlying data stream to start reading from

size ulong

The number of bytes to read

queue AsyncIOQueue

The AsyncIOQueue to add the asynchronous reading operation to

userdata void*

A pointer to unmanaged user-defined data to associate with the asynchronous reading operation. This will be provided as the UnsafeUserdata property's value of the AsyncIOOutcome returned by the operation.

Returns

bool

true, if the reading operation was initiated successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The asynchronous reading operation might read less bytes than requested by size.

This method returns as quickly as possible; it does not wait for the reading operation to complete. On a successful return, this work will continue in the background. If the work begins, even a failure is asynchronous: a failing return value from this method only means the reading operation couldn't get initiated.

The unmanaged memory pointed to by data must be safely dereferencable for at least size bytes and must remain valid until the AsyncIOOutcome of the reading operation is disposed.

The unmanaged user-defined data pointed to by userdata must remain valid until the AsyncIOOutcome of the reading operation is disposed.

The newly created asynchronous reading operation will be added to the specified queue.

TryUnsafeWrite(void*, ulong, ulong, AsyncIOQueue, void*)

Tries to asynchronously write data to the AsyncIO

public bool TryUnsafeWrite(void* data, ulong offset, ulong size, AsyncIOQueue queue, void* userdata = null)

Parameters

data void*

A pointer to the unmananged memory containing all the data to be written to the AsyncIO

offset ulong

The offset within underlying data stream to start writing to

size ulong

The size, in bytes, of the data to be written

queue AsyncIOQueue

The AsyncIOQueue to add the asynchronous writing operation to

userdata void*

A pointer to unmanaged user-defined data to associate with the asynchronous writing operation. This will be provided as the UnsafeUserdata property's value of the AsyncIOOutcome returned by the operation.

Returns

bool

true, if the writing operation was initiated successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The asynchronous writing operation tries to write size bytes from buffer pointed to by data to the AsyncIO.

This method returns as quickly as possible; it does not wait for the writing operation to complete. On a successful return, this work will continue in the background. If the work begins, even a failure is asynchronous: a failing return value from this method only means the writing operation couldn't get initiated.

The unmanaged memory pointed to by data must be safely dereferencable for at least size bytes and must remain valid until the AsyncIOOutcome of the writing operation is disposed.

The unmanaged user-defined data pointed to by userdata must remain valid until the AsyncIOOutcome of the writing operation is disposed.

The newly created asynchronous writing operation will be added to the specified queue.

TryWrite(ReadOnlyNativeMemory, ulong, AsyncIOQueue, object?)

Tries to asynchronously write data to the AsyncIO

public bool TryWrite(ReadOnlyNativeMemory data, ulong offset, AsyncIOQueue queue, object? userdata = null)

Parameters

data ReadOnlyNativeMemory

The memory buffer containing all the data to be written to the AsyncIO

offset ulong

The offset within underlying data stream to start writing to

queue AsyncIOQueue

The AsyncIOQueue to add the asynchronous writing operation to

userdata object

User-defined data to associate with the asynchronous writing operation. This will be provided as the Userdata property's value of the AsyncIOOutcome returned by the operation.

Returns

bool

true, if the writing operation was initiated successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The asynchronous writing operation tries to write the whole data buffer to the AsyncIO.

This method returns as quickly as possible; it does not wait for the writing operation to complete. On a successful return, this work will continue in the background. If the work begins, even a failure is asynchronous: a failing return value from this method only means the writing operation couldn't get initiated.

This method will pin the specified data until the AsyncIOOutcome of the writing operation is disposed.

The newly created asynchronous writing operation will be added to the specified queue.

TryWrite(ReadOnlyMemory<byte>, ulong, AsyncIOQueue, object?)

Tries to asynchronously write data to the AsyncIO

public bool TryWrite(ReadOnlyMemory<byte> data, ulong offset, AsyncIOQueue queue, object? userdata = null)

Parameters

data ReadOnlyMemory<byte>

The ReadOnlyMemory<T> containing all the data to be written to the AsyncIO

offset ulong

The offset within underlying data stream to start writing to

queue AsyncIOQueue

The AsyncIOQueue to add the asynchronous writing operation to

userdata object

User-defined data to associate with the asynchronous writing operation. This will be provided as the Userdata property's value of the AsyncIOOutcome returned by the operation.

Returns

bool

true, if the writing operation was initiated successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The asynchronous writing operation tries to write the whole data buffer to the AsyncIO.

This method returns as quickly as possible; it does not wait for the writing operation to complete. On a successful return, this work will continue in the background. If the work begins, even a failure is asynchronous: a failing return value from this method only means the writing operation couldn't get initiated.

This method will pin the specified data until the AsyncIOOutcome of the writing operation is disposed.

The newly created asynchronous writing operation will be added to the specified queue.

TryWrite(void*, ulong, ulong, AsyncIOQueue, object?)

Tries to asynchronously write data to the AsyncIO

public bool TryWrite(void* data, ulong offset, ulong size, AsyncIOQueue queue, object? userdata = null)

Parameters

data void*

A pointer to the unmananged memory containing all the data to be written to the AsyncIO

offset ulong

The offset within underlying data stream to start writing to

size ulong

The size, in bytes, of the data to be written

queue AsyncIOQueue

The AsyncIOQueue to add the asynchronous writing operation to

userdata object

User-defined data to associate with the asynchronous writing operation. This will be provided as the Userdata property's value of the AsyncIOOutcome returned by the operation.

Returns

bool

true, if the writing operation was initiated successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The asynchronous writing operation tries to write size bytes from buffer pointed to by data to the AsyncIO.

This method returns as quickly as possible; it does not wait for the writing operation to complete. On a successful return, this work will continue in the background. If the work begins, even a failure is asynchronous: a failing return value from this method only means the writing operation couldn't get initiated.

The unmanaged memory pointed to by data must be safely dereferencable for at least size bytes and must remain valid until the AsyncIOOutcome of the writing operation is disposed.

The newly created asynchronous writing operation will be added to the specified queue.