Functions and constants functions
Free functions and constants of Core.
- Use
#include <ThinkMeta.ConcurrentTasks/Core.h>- Namespace
ThinkMeta::ConcurrentTasks
Functions
CreateTaskScheduler
Creates a scheduler.
Syntax
ITaskScheduler* CreateTaskScheduler(
SchedulerKind kind,
const SchedulerInfo* info
) noexcept;Parameters
kindSchedulerKind- The scheduler implementation; see
SchedulerKind. infoconst SchedulerInfo*- The scheduler's parameters; required. The core copies the struct, so it need only be valid during the call.
Return value
Type: ITaskScheduler*
The scheduler, or nullptr if info is null, its version is unknown, kind needs a field that is not set, SchedulerInfo::taskQueueCapacity is too large, or the queues cannot be allocated.
See also
GetTaskScheduler
Returns the scheduler running the calling task.
Syntax
ITaskScheduler* GetTaskScheduler() noexcept;Return value
Type: ITaskScheduler*
The scheduler; owned by its creator, not by the caller.
Remarks
Only in a task or a converted thread (ConvertThreadToTask).
GetCurrentTask
Returns the handle of the calling task.
Syntax
TaskHandle GetCurrentTask() noexcept;Return value
Type: TaskHandle
The calling task's handle, valid as long as the task (or converted thread) exists.
Remarks
Only in a task or a converted thread (ConvertThreadToTask); on any other thread the result is undefined and the call may crash.
See also
GetTask
Returns the task object behind a handle.
Syntax
ITask* GetTask(TaskHandle task) noexcept;Parameters
taskTaskHandle- A task's handle (a
SuspendedTaskconverts to it);nullptrstands for the calling task.
Return value
Type: ITask*
The ITask the handle runs; owned by whoever added the task.
See also
SuspendTask
Suspends the calling task.
Syntax
void SuspendTask(ISuspendCallback* callback) noexcept;Parameters
callbackISuspendCallback*- Receives the task's handle once the task is off the processor; required, and must stay valid until
ISuspendCallback::OnSuspendedhas returned.
Remarks
The core calls back into ISuspendCallback::OnSuspended with the task's handle once the task is off the processor, so the waiter can publish it.
See also
ResumeTask
Makes a suspended task runnable again.
Syntax
void ResumeTask(SuspendedTask suspendedTask) noexcept;Parameters
suspendedTaskSuspendedTask- Handle received by
ISuspendCallback::OnSuspended;nullptris ignored.
Remarks
The task runs on the scheduler that suspended it. Callable from any task or OS thread, also from a completion routine on the core's I/O thread; never blocks. Resume each suspension exactly once.
See also
YieldTask
Gives up the processor without suspending the calling task.
Syntax
void YieldTask(YieldFlags yieldFlags) noexcept;Parameters
yieldFlagsYieldFlags- How to yield; see
YieldFlags.
See also
SetTaskPriority
Sets the priority of the calling task.
Syntax
void SetTaskPriority(TaskPriority priority) noexcept;Parameters
priorityTaskPriorityTaskPriority::NormalorTaskPriority::High;TaskPriority::Defaultis not meaningful here.
See also
ConvertThreadToTask
Lets the calling OS thread act as a task.
Syntax
void ConvertThreadToTask() noexcept;Remarks
The thread can then use the synchronization primitives. ConvertTaskToThread reverses it.
ConvertTaskToThread
Reverses ConvertThreadToTask on the calling thread.
Syntax
void ConvertTaskToThread() noexcept;Remarks
Releases the thread's task state. Call it on the same thread, once no other task can still resume this thread's task.
EnableTimers
Starts the core's timer thread.
Syntax
bool EnableTimers() noexcept;Return value
Type: bool
true if timers are enabled; false only if the thread could not be started.
Remarks
The timer thread starts tasks added by ITaskScheduler::AddTimedTask, wakes sleeping tasks and ends waits that time out. Calls are counted like AsyncIo::EnableAsyncIo.
See also
DisableTimers
Takes back one EnableTimers.
Syntax
bool DisableTimers() noexcept;Return value
Type: bool
true on success; false if timers were not enabled.
Remarks
The last one ends what is still waiting: tasks not yet started exit without running (INotifyTaskStateChange::OnTaskExited, on their scheduler, which must still run), sleeping tasks wake, and waits with a timeout time out. No other thread may use timers meanwhile.
SleepTask
Suspends the calling task for a while.
Syntax
Parameters
Return value
Type: bool
true after the sleep; false at once if timers are not enabled.
Remarks
Its thread runs other tasks meanwhile. Nothing cuts the sleep short; to wait for something with a time limit, wait on it with a timeout.
See also
SuspendTaskFor
Suspends the calling task with a timeout.
Syntax
bool SuspendTaskFor(ISuspendCallback* callback, Duration timeout) noexcept;Parameters
callbackISuspendCallback*- Receives the task's handle (
ISuspendCallback::OnSuspended) and, on timeout, theISuspendCallback::OnTimeoutcall; required, and must stay valid until this call returns. timeoutDuration- Longest time to stay suspended;
Duration::Infinitewaits without a timeout.
Return value
Type: bool
true if a ResumeTask ended the wait, false if it timed out: then the core has called ISuspendCallback::OnTimeout on callback, which took the task back from where ISuspendCallback::OnSuspended had published it.
Remarks
Like SuspendTask, but the wait ends after timeout at the latest. The waiter's state (the callback) is never touched again once the task runs. Without EnableTimers, or with Duration::Infinite, it waits without a timeout.
CancelTimedTask
Takes back a timed task that has not started yet.
Syntax
bool CancelTimedTask(ITask* task) noexcept;Parameters
taskITask*- A task added by
ITaskScheduler::AddTimedTask.
Return value
Type: bool
Whether the task was waiting to start; false if it had started or was not timed.
Remarks
The task (added by ITaskScheduler::AddTimedTask) exits without running, so its INotifyTaskStateChange::OnTaskExited is called (on its scheduler) and only then may the task object go away or be added again. Never blocks.
See also
ScheduleTimedTask
Starts a timed task now instead of later.
Syntax
bool ScheduleTimedTask(ITask* task) noexcept;Parameters
taskITask*- A task added by
ITaskScheduler::AddTimedTask.
Return value
Type: bool
true if the task was queued now; false if it was not waiting to start.
Remarks
Never blocks.
See also
AsyncIo::EnableAsyncIo
Starts the core's I/O completion port and the thread draining it.
Syntax
bool EnableAsyncIo() noexcept;Return value
Type: bool
true if asynchronous I/O is enabled; false only if they could not be started.
Remarks
Calls are counted: only the first one starts them, so a library and the application can both enable asynchronous I/O.
See also
AsyncIo::DisableAsyncIo
Takes back one EnableAsyncIo.
Syntax
bool DisableAsyncIo() noexcept;Return value
Type: bool
true on success; false if asynchronous I/O was not enabled.
Remarks
The last one stops the port and its thread, and by then no operation may be pending.
AsyncIo::AssociateHandleWithIoCompletionPort
Associates a file or socket handle with the core's completion port.
Syntax
bool AssociateHandleWithIoCompletionPort(
HANDLE handle,
IoCompletionRoutine completionRoutine
) noexcept;Parameters
handleHANDLE- A file or socket handle opened for overlapped I/O (
FILE_FLAG_OVERLAPPED); borrowed, it stays associated until it is closed. completionRoutineIoCompletionRoutine- Called for every completion packet of
handle; required.
Return value
Type: bool
true on success; false if it failed (GetLastError has the reason; ERROR_NOT_READY when EnableAsyncIo has not been called).
Remarks
The routine is stored as the handle's completion key, so the core needs no knowledge of the caller's types.
See also
Constants
SchedulerVersion
ABI version this header describes.
Syntax
inline constexpr unsigned long SchedulerVersion = 1;Remarks
Passed in SchedulerInfo::version; the core accepts only its own version.
See also
DefaultTaskQueueCapacity
Default task queue capacity.
Syntax
inline constexpr unsigned long DefaultTaskQueueCapacity = 4096;Remarks
Used when SchedulerInfo::taskQueueCapacity is 0.
MaximumTaskQueueCapacity
Largest task queue capacity CreateTaskScheduler accepts.
Syntax
inline constexpr unsigned long MaximumTaskQueueCapacity = 1UL << 20;Generated from ThinkMeta.ConcurrentTasks.API @ 137ec1d (2026-10-17).