Skip to content

TSdlAsyncIO

The asynchronous I/O operation structure.

This operates as an opaque handle. One can then request read or write operations on it.

Definition

Unit: Neslib.Sdl3.IO

type TSdlAsyncIO = record ... end;

Properties

Name Description
Size The size of the data stream.

Constructors

Name Description
Create Create a new TSdlAsyncIO object for reading from and/or writing to a named file.

Operators

Name Description
Equal(TSdlAsyncIO, TSdlAsyncIO) Used to compare against another TSdlAsyncIO.
Equal(TSdlAsyncIO, Pointer) Used to compare against nil.
Implicit Used to set the value to nil.
NotEqual(TSdlAsyncIO, TSdlAsyncIO) Used to compare against another TSdlAsyncIO.
NotEqual(TSdlAsyncIO, Pointer) Used to compare against nil.

Methods

Name Description
Free Close and free any allocated resources for an async I/O object.
Read Start an async read.
Write Start an async write.

Property Descriptions

Size

The size of the data stream.

This call is not asynchronous; it assumes that obtaining this info is a non-blocking operation in most reasonable cases.

property Size: Int64 read GetSize

Type: Int64

Exceptions

ESdlError: Raised on failure.

Remarks

It is safe to use this property from any thread

Constructor Descriptions

Create

Create a new TSdlAsyncIO object for reading from and/or writing to a named file.

The AMode string understands the following values:

  • 'r': Open a file for reading. The file 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 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.

constructor Create(const AFilename, AMode: String)

Parameters

AFilename: String : The filename to open.

AMode: String : String representing the mode to be used for opening the file.

Exceptions

ESdlError: Raised on failure.

See Also

Operator Descriptions

Equal(TSdlAsyncIO, TSdlAsyncIO)

Used to compare against another TSdlAsyncIO.

class operator Equal(const ALeft, ARight: TSdlAsyncIO): Boolean; inline; static

Parameters

ALeft: TSdlAsyncIO

ARight: TSdlAsyncIO

Returns

Boolean

Equal(TSdlAsyncIO, Pointer)

Used to compare against nil.

class operator Equal(const ALeft: TSdlAsyncIO; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlAsyncIO

ARight: Pointer

Returns

Boolean

Implicit(Pointer)

Used to set the value to nil.

class operator Implicit(const AValue: Pointer): TSdlAsyncIO; inline; static

Parameters

AValue: Pointer

Returns

TSdlAsyncIO

NotEqual(TSdlAsyncIO, TSdlAsyncIO)

Used to compare against another TSdlAsyncIO.

class operator NotEqual(const ALeft, ARight: TSdlAsyncIO): Boolean; inline; static

Parameters

ALeft: TSdlAsyncIO

ARight: TSdlAsyncIO

Returns

Boolean

NotEqual(TSdlAsyncIO, Pointer)

Used to compare against nil.

class operator NotEqual(const ALeft: TSdlAsyncIO; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlAsyncIO

ARight: Pointer

Returns

Boolean

Method Descriptions

Free(Boolean, TSdlAsyncIOQueue, Pointer)

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 method with the AFlush 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 method guarantees that the close will happen after any other pending tasks, so it's safe to open a file, start several operations, close the file immediately, then check for all results later. This method will not block until the tasks have completed.

Once this method returns, this object is no longer valid, regardless of any future outcomes. Any completed tasks might still contain this pointer in their TSdlAsyncIOOutcome data, in case the app was using this value to track information, but it should not be used again.

If this function raises an error, the close wasn't started at all, and it's safe to attempt to close again later.

A TSdlAsyncIOQueue must be specified. The newly-created task will be added to it when it completes its work.

procedure Free(const AFlush: Boolean; const AQueue: TSdlAsyncIOQueue; const AUserData: Pointer); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AFlush: Boolean : True if data should sync to disk before the task completes.

AQueue: TSdlAsyncIOQueue : A queue to add the TSdlAsyncIO to.

AUserData: Pointer : An app-defined pointer that will be provided with the task results.

Remarks

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

Read(Pointer, Int64, Int64, TSdlAsyncIOQueue, Pointer)

Start an async read.

This method reads up to ASize bytes from AOffset position in the data source to the area pointed at by APtr. This method may read less bytes than requested.

This method 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 method only means the work couldn't start at all.

APtr 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 method to complete!

A TSdlAsyncIOQueue must be specified. The newly-created task will be added to it when it completes its work.

procedure Read(const APtr: Pointer; const AOffset, ASize: Int64; const AQueue: TSdlAsyncIOQueue; const AUserData: Pointer); inline

Exceptions

ESdlError: Raised on failure.

Parameters

APtr: Pointer : A pointer to a buffer to read data into.

AOffset: Int64 : The position to start reading in the data source.

ASize: Int64 : The number of bytes to read from the data source.

AQueue: TSdlAsyncIOQueue : A queue to add the TSdlAsyncIO to.

AUserData: Pointer : An app-defined pointer that will be provided with the task results.

See Also

Remarks

It is safe to call this method from any thread

Write(Pointer, Int64, Int64, TSdlAsyncIOQueue, Pointer)

Start an async write.

This method writes ASize bytes from AOffset position in the data source to the area pointed at by APtr.

This method 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 method only means the work couldn't start at all.

APtr 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 method to complete!

A TSdlAsyncIOQueue must be specified. The newly-created task will be added to it when it completes its work.

procedure Write(const APtr: Pointer; const AOffset, ASize: Int64; const AQueue: TSdlAsyncIOQueue; const AUserData: Pointer); inline

Exceptions

ESdlError: Raised on failure.

Parameters

APtr: Pointer : A pointer to a buffer to write data from.

AOffset: Int64 : The position to start writing to the data source.

ASize: Int64 : The number of bytes to write to the data source.

AQueue: TSdlAsyncIOQueue : A queue to add the TSdlAsyncIO to.

AUserData: Pointer : An app-defined pointer that will be provided with the task results.

See Also

Remarks

It is safe to call this method from any thread