Preliminary. ThinkMeta ConcurrentTasks and this documentation are preliminary; everything is subject to change.

ThinkMeta ConcurrentTasks Docs

API reference / Async I/O

AsyncFile class

A file for overlapped I/O on the core's I/O completion port.

Use
import ThinkMeta.ConcurrentTasks.AsyncIo.AsyncFile;
Namespace
ThinkMeta::ConcurrentTasks::AsyncIo

Syntax

class AsyncFile

Remarks

The file is opened with FILE_FLAG_OVERLAPPED and associated with the core's port. Needs EnableAsyncIo (Core.h) before Create, and no operation may still be pending at DisableAsyncIo. All functions report errors as a Win32 error code (ERROR_SUCCESS on success; ReadAsync/WriteAsync also ERROR_IO_PENDING). Read, Write, ReadFile and WriteFile suspend the calling task while they wait, so call them from a task, or from an OS thread after ConvertThreadToTask. Completions run on the core's I/O thread (or on the calling thread when an operation completes at once). The object owns the handle and closes it on destruction. Close or destroy it only when no operation is pending. The handle has no file pointer: every operation carries its offset.

See also

AsyncFileIoRequest, Windows::File

Methods

IsValid

true if a file is open.

Syntax

bool IsValid() const noexcept;

Return value

Type: bool

true if a file is open; false before Create and after Close.

Create

Opens or creates the file.

Syntax

ErrorType Create(
    FileName fileName,
    DWORD access,
    DWORD shareMode,
    DWORD creationDisposition,
    DWORD flagsAndAttributes
) noexcept;

Parameters

fileNameFileName
Path of the file; must not be nullptr.
accessDWORD
Requested access: GENERIC_READ, GENERIC_WRITE or both.
shareModeDWORD
What other opens may do meanwhile: 0 (exclusive) or a combination of FILE_SHARE_READ, FILE_SHARE_WRITE and FILE_SHARE_DELETE.
creationDispositionDWORD
CREATE_NEW, CREATE_ALWAYS, OPEN_EXISTING, OPEN_ALWAYS or TRUNCATE_EXISTING.
flagsAndAttributesDWORD
FILE_ATTRIBUTE_* and FILE_FLAG_* values, e.g. FILE_FLAG_NO_BUFFERING or FILE_FLAG_SEQUENTIAL_SCAN; FILE_FLAG_OVERLAPPED is always added.

Return value

Type: ErrorType

ERROR_SUCCESS if the file is open and associated; otherwise the CreateFileW or association error, and no file is open.

Remarks

Calls CreateFileW with FILE_FLAG_OVERLAPPED added and associates the handle with the core's I/O completion port. Precondition: no file is open. Needs EnableAsyncIo. Does not suspend. The parameters go to CreateFileW unchanged (FILE_FLAG_NO_BUFFERING makes the buffers, offsets and sizes of all transfers subject to sector alignment). Returns the CreateFileW error, or the error of the association (AssociateHandleWithIoCompletionPort); if the association fails, the file is closed again, so after any error no file is open.

See also

Close

Close

Closes the handle (success if none is open). No operation may be pending.

Syntax

ErrorType Close() noexcept;

Return value

Type: ErrorType

ERROR_SUCCESS if the file was closed or none was open; otherwise the CloseHandle error.

See also

Create

GetSize

Gets the file size (GetFileSizeEx). Precondition: a file is open.

Syntax

ErrorType GetSize(FileSize& size) noexcept;

Parameters

sizeFileSize&
Receives the file size in bytes; unchanged on failure.

Return value

Type: ErrorType

ERROR_SUCCESS, or the Win32 error code of GetFileSizeEx.

ReadAsync

Starts an overlapped read.

Syntax

ErrorType ReadAsync(
    void* buffer,
    DWORD bytesToRead,
    AsyncFileIoRequest& asyncIoRequest
) noexcept;

Parameters

buffervoid*
Receives the data; at least bytesToRead bytes, sector-aligned with FILE_FLAG_NO_BUFFERING.
bytesToReadDWORD
Maximum number of bytes to read.
asyncIoRequestAsyncFileIoRequest&
The request; its offset is the file position to read at.

Return value

Type: ErrorType

ERROR_SUCCESS: done at once, the request is already completed (on the calling thread). ERROR_IO_PENDING: the request completes later on the I/O thread. Any other code: the read was not started and the request will not complete (reading at or beyond the end of the file can fail this way with ERROR_HANDLE_EOF).

Remarks

Never suspends. Set the offset (AsyncFileIoRequest::SetOffset, after AsyncFileIoRequest::Reset) before the call. buffer and the request belong to the caller and must stay valid and untouched until the request has completed. A completed read may be shorter than bytesToRead (end of file): check AsyncIoRequestBase::GetTransferredBytes.

See also

Read, WaitableAsyncFileIoRequest

WriteAsync

Starts an overlapped write.

Syntax

ErrorType WriteAsync(
    const void* buffer,
    DWORD bytesToWrite,
    AsyncFileIoRequest& asyncIoRequest
) noexcept;

Parameters

bufferconst void*
The data to write; at least bytesToWrite bytes, sector-aligned with FILE_FLAG_NO_BUFFERING.
bytesToWriteDWORD
Number of bytes to write.
asyncIoRequestAsyncFileIoRequest&
The request; its offset is the file position to write at.

Return value

Type: ErrorType

As ReadAsync: ERROR_SUCCESS (completed at once), ERROR_IO_PENDING, or an error (not started).

Remarks

Never suspends. Ownership and lifetime of buffer and request as for ReadAsync.

See also

Write, WaitableAsyncFileIoRequest

Read

Reads from the file and waits for the result.

Syntax

ErrorType Read(
    void* buffer,
    DWORD bytesToRead,
    DWORD& bytesRead,
    std::uint64_t filePosition,
    Duration timeout = Duration::Infinite()
) noexcept;

Parameters

buffervoid*
Receives the data; at least bytesToRead bytes, sector-aligned with FILE_FLAG_NO_BUFFERING.
bytesToReadDWORD
Maximum number of bytes to read.
bytesReadDWORD&
Bytes read (less than bytesToRead at the end of the file); 0 on error.
filePositionstd::uint64_t
File offset in bytes to read at.
timeoutDuration
Duration::Infinite: wait for the completion. Otherwise a read still pending after timeout is cancelled (CancelIoEx) and ERROR_TIMEOUT is returned, unless it completed meanwhile. A timeout needs EnableTimers; without it the wait has no limit.Default: Duration::Infinite()

Return value

Type: ErrorType

ERROR_SUCCESS if the read completed; ERROR_TIMEOUT if it was cancelled after timeout; otherwise the Win32 error code of the read (e.g. ERROR_HANDLE_EOF).

Remarks

Suspends the calling task until the read has completed (also after a timeout, until the cancellation is through), so buffer may be reused as soon as it returns.

See also

ReadAsync, Write

Write

Writes to the file and waits for the result.

Syntax

ErrorType Write(
    const void* buffer,
    DWORD bytesToWrite,
    DWORD& bytesWritten,
    std::uint64_t filePosition,
    Duration timeout = Duration::Infinite()
) noexcept;

Parameters

bufferconst void*
The data to write; at least bytesToWrite bytes, sector-aligned with FILE_FLAG_NO_BUFFERING.
bytesToWriteDWORD
Number of bytes to write.
bytesWrittenDWORD&
Bytes written; 0 on error.
filePositionstd::uint64_t
File offset in bytes to write at.
timeoutDuration
As for Read: a write still pending after timeout is cancelled and gives ERROR_TIMEOUT.Default: Duration::Infinite()

Return value

Type: ErrorType

ERROR_SUCCESS if the write completed; ERROR_TIMEOUT if it was cancelled after timeout; otherwise the Win32 error code of the write.

Remarks

Suspends the calling task until the write has completed, as Read does.

See also

WriteAsync, Read

ReadFile

Reads a whole file into sequential memory.

Syntax

static ErrorType ReadFile(
    FileName fileName,
    DWORD access,
    DWORD shareMode,
    DWORD creationDisposition,
    DWORD flagsAndAttributes,
    Memory::IWriteSequentialMemory* writeSequentialMemory,
    const BulkIoOptions& options = {}
) noexcept;

Parameters

fileNameFileName
Path of the file; must not be nullptr.
accessDWORD
Requested access, as for Create; must include GENERIC_READ.
shareModeDWORD
Share mode, as for Create.
creationDispositionDWORD
Creation disposition, as for Create; usually OPEN_EXISTING.
flagsAndAttributesDWORD
Flags and attributes, as for Create; with FILE_FLAG_NO_BUFFERING the memory's blocks and BulkIoOptions::blockSize must be sector-aligned.
writeSequentialMemoryMemory::IWriteSequentialMemory*
Receives the file content; must not be nullptr; borrowed, must outlive the call.
optionsconst BulkIoOptions&
The shape of the I/O; reading starts at BulkIoOptions::startOffset.Default: {}

Return value

Type: ErrorType

ERROR_SUCCESS if the whole file was read; otherwise the first error (see remarks).

Remarks

Opens fileName (parameters as for Create), reads it to the end into writeSequentialMemory with overlapped requests in flight, and closes it. Suspends the calling task while it waits for reads (and possibly inside the memory's Memory::IWriteSequentialMemory::RequestWriteMemory). Needs EnableAsyncIo. The memory gets Memory::IWriteSequentialMemory::Initialize(bytes to read) first, then one RequestWriteMemory/Memory::IWriteSequentialMemory::ReleaseWriteMemory per block in file order, and always Memory::IWriteSequentialMemory::SetEndOfStream at the end - also on every error. If the file cannot be opened or sized, the memory gets an empty stream (Initialize(0)). Each finished block goes to the memory at once, so a consumer can start on the first blocks while the rest is on its way; a memory with a bounded window must hold at least BulkIoOptions::blocksInFlight blocks. The memory is borrowed: it must outlive the call. Returns the first error (open, size, ERROR_NOT_ENOUGH_MEMORY for a nullptr block or the request array, or a read's Win32 error); after an error no block is released to the memory any more, but the call still waits for every read in flight before it returns.

See also

WriteFile, BulkIoOptions

WriteFile

Writes a whole file from sequential memory.

Syntax

static ErrorType WriteFile(
    FileName fileName,
    DWORD access,
    DWORD shareMode,
    DWORD creationDisposition,
    DWORD flagsAndAttributes,
    Memory::IReadSequentialMemory* readSequentialMemory,
    const BulkIoOptions& options = {}
) noexcept;

Parameters

fileNameFileName
Path of the file; must not be nullptr.
accessDWORD
Requested access, as for Create; must include GENERIC_WRITE.
shareModeDWORD
Share mode, as for Create.
creationDispositionDWORD
Creation disposition, as for Create; usually CREATE_ALWAYS.
flagsAndAttributesDWORD
Flags and attributes, as for Create; with FILE_FLAG_NO_BUFFERING the memory's blocks and BulkIoOptions::blockSize must be sector-aligned.
readSequentialMemoryMemory::IReadSequentialMemory*
Supplies the data to write; must not be nullptr; borrowed, must outlive the call.
optionsconst BulkIoOptions&
The shape of the I/O; BulkIoOptions::startOffset is ignored, writing starts at offset 0.Default: {}

Return value

Type: ErrorType

ERROR_SUCCESS if all data was written; otherwise the first error (see remarks).

Remarks

Opens fileName (parameters as for Create; use a creating disposition), writes the data of readSequentialMemory from offset 0 with overlapped requests in flight, and closes it. Suspends the calling task while it waits for writes (and possibly inside the memory's Memory::IReadSequentialMemory::RequestReadMemory). Needs EnableAsyncIo. Blocks of up to options.BulkIoOptions::blockSize are taken with RequestReadMemory until it returns nullptr or 0 bytes (end of data); each is handed back with Memory::IReadSequentialMemory::ReleaseReadMemory(bytes written) once its write has completed, in order. The file is not truncated to the written size (with OPEN_EXISTING/OPEN_ALWAYS older data beyond it stays). The memory is borrowed: it must outlive the call. Returns the first error (open, ERROR_NOT_ENOUGH_MEMORY for the request array, or a write's Win32 error); after an error no new block is requested, but the call waits for every write in flight and still releases their blocks before it returns.

See also

ReadFile, BulkIoOptions

Types

ErrorType

Win32 error code; ERROR_SUCCESS (0) on success.

Syntax

using ErrorType = Windows::ErrorCode;

FileName

Null-terminated wide path, as for CreateFileW.

Syntax

using FileName = Windows::File::FileName;

FileSize

File size in bytes.

Syntax

using FileSize = Windows::File::FileSize;

Generated from ThinkMeta.ConcurrentTasks.API @ 137ec1d (2026-10-17).