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

ThinkMeta ConcurrentTasks Docs

API reference / Windows

IoCompletionPort class

Owns one I/O completion port handle and closes it on destruction.

Use
import ThinkMeta.ConcurrentTasks.Windows.IoCompletionPort;
Namespace
ThinkMeta::ConcurrentTasks::Windows

Syntax

class IoCompletionPort

Remarks

Holds nullptr when no port is open. Members report failures as a Win32 error code (ErrorCode, ERROR_SUCCESS on success). The Win32 port calls are thread-safe, so several threads may post and dequeue at once; Create, Close and moves must not race with them. The dequeue functions (GetQueuedCompletionStatus) block the calling OS thread (a task calling them blocks its scheduler thread). Applications normally use the core's port instead (AsyncIo::EnableAsyncIo).

See also

AsyncIo::AssociateHandleWithIoCompletionPort

Constructors

IoCompletionPort

Creates an object without a port.

Syntax

IoCompletionPort() noexcept = default;

Remarks

Call Create to open one.

Takes over another object's port.

Syntax

IoCompletionPort(IoCompletionPort&& other) noexcept;

Parameters

otherIoCompletionPort&&
The object to take the port from; holds no port afterwards.

Remarks

other is left without one.

~IoCompletionPort

Closes the port.

Syntax

~IoCompletionPort() noexcept;

Remarks

A failure is ignored. Associated handles should be closed first.

Methods

operator=

Takes over another object's port.

Syntax

IoCompletionPort& operator=(IoCompletionPort&& other) noexcept;

Parameters

otherIoCompletionPort&&
The object to take the port from; holds no port afterwards.

Return value

Type: IoCompletionPort&

This object.

Remarks

Closes the own port first (ignoring a failure); other is left without one. A self-move changes nothing.

IsValid

true if a port is held.

Syntax

bool IsValid() const noexcept;

Return value

Type: bool

true if a port is held; false if the object holds nullptr.

Create

Creates a new port.

Syntax

ErrorCode Create(DWORD numberOfConcurrentThreads) noexcept;

Parameters

numberOfConcurrentThreadsDWORD
Threads the port lets run at once; 0: one per processor.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

Remarks

Precondition: none is held.

See also

Close

Associate

Associates a handle with the port.

Syntax

ErrorCode Associate(HANDLE handle, DWORD_PTR completionKey) noexcept;

Parameters

handleHANDLE
A handle opened for overlapped I/O.
completionKeyDWORD_PTR
Carried by every packet of the handle.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code (e.g. ERROR_INVALID_PARAMETER if already associated).

Remarks

A handle can be associated with one port only, for its lifetime.

Close

Closes the port.

Syntax

ErrorCode Close() noexcept;

Return value

Type: ErrorCode

ERROR_SUCCESS if the port was closed or none was held; otherwise the CloseHandle error.

Remarks

Success if none is held. On failure the handle is kept.

See also

Create

GetQueuedCompletionStatus

Dequeues one packet (GetQueuedCompletionStatus).

Syntax

ErrorCode GetQueuedCompletionStatus(
    DWORD& numberOfBytes,
    ULONG_PTR& completionKey,
    OVERLAPPED*& overlapped,
    DWORD milliseconds
) noexcept;

Parameters

numberOfBytesDWORD&
Receives the number of bytes the dequeued operation transferred.
completionKeyULONG_PTR&
Receives the completion key of the handle (or the posted key).
overlappedOVERLAPPED*&
Receives the OVERLAPPED of the dequeued operation; nullptr if no packet was dequeued.
millisecondsDWORD
How long to wait at most; INFINITE: no limit.

Return value

Type: ErrorCode

ERROR_SUCCESS for a packet of a successful operation; the operation's error for a failed one; WAIT_TIMEOUT if none arrived in time; otherwise the Win32 error code of the call.

Remarks

Returns the packet's own error for a failed I/O operation; then overlapped is non-null and numberOfBytes and completionKey are valid. WAIT_TIMEOUT with a nullptr overlapped means no packet arrived in time. The error is returned here because the thread's last error may be overwritten by any later call.

See also

PostQueuedCompletionStatus

Dequeues several packets at once (GetQueuedCompletionStatusEx).

Syntax

ErrorCode GetQueuedCompletionStatus(
    OVERLAPPED_ENTRY* completionPortEntries,
    ULONG count,
    ULONG& numEntriesRemoved,
    DWORD milliseconds,
    BOOL alertable
) noexcept;

Parameters

completionPortEntriesOVERLAPPED_ENTRY*
Receives the dequeued packets; at least count entries.
countULONG
Maximum number of packets to dequeue.
numEntriesRemovedULONG&
Receives the number of entries filled in.
millisecondsDWORD
How long to wait at most; INFINITE: no limit.
alertableBOOL
TRUE to let queued APCs run during the wait (it then ends with WAIT_IO_COMPLETION); FALSE otherwise.

Return value

Type: ErrorCode

ERROR_SUCCESS if at least one packet was dequeued, WAIT_TIMEOUT, WAIT_IO_COMPLETION, or another Win32 error code.

Remarks

The per-packet result is not returned: read each entry's Internal (an NTSTATUS) and dwNumberOfBytesTransferred. WAIT_TIMEOUT if none arrived; WAIT_IO_COMPLETION if an APC ended an alertable wait.

See also

PostQueuedCompletionStatus

PostQueuedCompletionStatus

Posts a packet with the given values.

Syntax

ErrorCode PostQueuedCompletionStatus(
    DWORD numberOfBytesTransferred,
    ULONG_PTR completionKey,
    OVERLAPPED* overlapped
) noexcept;

Parameters

numberOfBytesTransferredDWORD
Delivered to the dequeuer as the transferred byte count.
completionKeyULONG_PTR
Delivered to the dequeuer as the completion key.
overlappedOVERLAPPED*
Delivered to the dequeuer as the OVERLAPPED pointer; may be nullptr or any value the dequeuer understands, it is not dereferenced by the system.

Return value

Type: ErrorCode

ERROR_SUCCESS, or the Win32 error code of the failed call.

Remarks

Any thread; never blocks.

See also

GetQueuedCompletionStatus

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