Threading¶

Threading library for managing concurrent and scheduled tasks. Includes a thread pool for executing asynchronous operations and a scheduler for recurring tasks with priority queuing and built-in error handling.

Credits: Developed by TazE

type PThreadTask¶

A pointer to a TThreadTask record.

type PThreadWorker¶

A pointer to a TThreadWorker record.

type PThreadPool¶

A pointer to a TThreadPool record.

type EDebugLevel¶

An enumeration defining the verbosity level for logging.

EDebugLevel.NONE: No logs are printed.
EDebugLevel.INFO: Informational messages are printed.
EDebugLevel.VERBOSE: Detailed, verbose messages are printed.

type TOnException¶

A callback method that is triggered when a task execution throws an exception.

Parameters¶

TaskName: The ID of the task that failed.
Error: The exception message.

type TOnComplete¶

A callback method that is triggered when a task finishes execution.

Parameters¶

TaskName: The ID of the completed task.
Success: A boolean indicating if the task completed without errors.

type TThreadTask¶

Represents a single unit of work to be executed by a worker thread.

ID: A unique identifier for the task.
Method: The procedure to be executed.
Priority: The task’s priority; higher values are processed first.
Created: The timestamp when the task was created.
Next: A pointer to the next task in the queue.

type TThreadWorker¶

Represents a single worker thread within a thread pool.

ID: A unique integer identifier for the worker.
Name: The name of the worker thread.
Thread: The underlying TThread object.
Pool: A pointer to the parent thread pool.
Active: Indicates if the worker thread is running.
Busy: Indicates if the worker is currently processing a task.
Processed: The total number of tasks processed by this worker.
WaitTimeMS: The current sleep time when no tasks are available.
MaxWaitTimeMS: The maximum sleep time for the worker.
LastActive: The timestamp of the last processed task.

type TTaskQueue¶

A thread-safe, priority-based queue for managing tasks.

Head: A pointer to the first task in the queue (highest priority).
Tail: A pointer to the last task in the queue.
Count: The number of tasks currently in the queue.
Lock: A TLock for ensuring thread safety.

type TThreadPool¶

Manages a collection of worker threads to execute tasks concurrently.

Name: The name of the thread pool.
Workers: An array of TThreadWorker records.
Queue: The TTaskQueue holding tasks to be processed.
LogLock: A TLock for thread-safe logging.
Running, Terminating, ShuttingDown: State flags for the pool.
DebugLevel: The current logging verbosity.
TasksQueued, TasksProcessed, TasksFailed: Counters for statistics.
StartTime: The timestamp when the pool was started.
MinWorkerCount, MaxWorkerCount: The minimum and maximum number of allowed workers.
DefaultWorkerWaitMS, DefaultWorkerMaxWaitMS: Default timing properties for workers.
OnException, OnComplete: Event handlers for task exceptions and completions.

type TScheduledTask¶

Represents a task that is scheduled to run at regular intervals.

ID: A unique identifier for the scheduled task.
Method: The procedure to execute.
Interval: The time in milliseconds between executions.
LastRun: The timestamp of the last execution.
Active: A flag to pause or resume the task.

type TThreadScheduler¶

Manages and runs scheduled tasks using a dedicated thread pool.

Pool: The TThreadPool used to execute scheduled tasks.
Tasks: An array of TScheduledTask records.
Thread: The scheduler’s main management thread.
Running: A flag indicating if the scheduler loop is active.
SleepIntervalMS: The sleep interval for the scheduler’s check loop.

type TThreadManager¶

A high-level manager providing a simple interface to both a general-purpose thread pool and a task scheduler.

Pool: The primary thread pool for one-off tasks.
Scheduler: The task scheduler for recurring tasks.
IsSetup: A flag indicating if the manager has been initialized.
DebugLevel: The global debug level for all underlying components.
ThreadCount: The number of threads for the main pool.
ExceptionHandler, CompletionHandler: Global event handlers.

TTaskQueue.Init¶

procedure TTaskQueue.Init();

Initializes a new TTaskQueue, setting its head and tail to nil and creating its lock. This must be called before using any other queue operations.

TTaskQueue.Free¶

procedure TTaskQueue.Free();

Frees the resources used by the queue, including clearing all tasks and freeing the lock. Always call this when you’re done with a queue to prevent memory leaks.

TTaskQueue.Add¶

procedure TTaskQueue.Add(Task: PThreadTask);

Adds a TThreadTask to the queue, inserting it based on its Priority. Higher priority tasks are placed closer to the head of the queue. This operation is thread-safe.

Parameters¶

Task: Pointer to the task to add. Must not be nil.

TTaskQueue.Get¶

function TTaskQueue.Get(): PThreadTask;

Retrieves and removes the highest-priority task (the head) from the queue. Returns nil if the queue is empty. This operation is thread-safe.

Returns¶

PThreadTask: Pointer to the highest priority task, or nil if queue is empty.

TTaskQueue.IsEmpty¶

function TTaskQueue.IsEmpty(): Boolean;

Returns True if the queue contains no tasks, otherwise False. This operation is thread-safe.

Returns¶

Boolean: True if queue is empty, False otherwise.

TTaskQueue.Clear¶

procedure TTaskQueue.Clear();

Removes and disposes of all tasks currently in the queue, resetting it to an empty state. This operation is thread-safe.

TThreadWorker.Execute¶

procedure TThreadWorker.Execute();

The main execution loop for a worker thread. It continuously fetches tasks from the pool’s queue and processes them. If no tasks are available, it sleeps with an exponential backoff strategy to reduce CPU usage.

This method is automatically called when the worker thread starts and should not be called manually.

TThreadPool.Log¶

procedure TThreadPool.Log(Level: EDebugLevel; const Msg: String);

Logs a message to the console if the given Level is at or below the pool’s DebugLevel. This operation is thread-safe.

Parameters¶

Level: The debug level of this message.
Msg: The message to log.

TThreadPool.GetDefaultThreadCount¶

function TThreadPool.GetDefaultThreadCount(): Integer;

Determines the optimal number of threads for the pool based on the system’s CPU information, clamped between MinWorkerCount and MaxWorkerCount.

Returns¶

Integer: The recommended number of worker threads for this system.

TThreadPool.Init¶

procedure TThreadPool.Init(const PoolName: String; ThreadCount: Integer = 0; DebugLevel: EDebugLevel = EDebugLevel.NONE);

Initializes the thread pool, creating and starting the specified number of worker threads.

Parameters¶

PoolName: A name for the thread pool, used in logging.
ThreadCount: The number of worker threads to create. If 0, a default value is determined automatically.
DebugLevel: The verbosity level for logging.

Example:

var Pool: TThreadPool;
Pool.Init('MyPool', 4, EDebugLevel.INFO);

TThreadPool.Shutdown¶

procedure TThreadPool.Shutdown(TimeoutMS: Integer = 30000);

Gracefully shuts down the thread pool. It waits for busy workers to finish their current tasks up to a specified timeout before terminating all threads.

Parameters¶

TimeoutMS: Maximum time to wait for workers to finish, in milliseconds. Default is 30 seconds.

TThreadPool.Free¶

procedure TThreadPool.Free();

Frees all resources associated with the thread pool. It ensures a proper shutdown before deallocating memory. Always call this when you’re done with a thread pool to prevent memory leaks.

TThreadPool.ValidateTask¶

function TThreadPool.ValidateTask(const TaskID: String; Method: procedure() of object): String;

Checks if a task is valid for submission. Returns an empty string on success or an error message on failure.

Parameters¶

TaskID: The task identifier to validate.
Method: The method to validate.

Returns¶

String: Empty string if valid, or error message if invalid.

TThreadPool.HasPendingTask¶

function TThreadPool.HasPendingTask(const TaskID: String): Boolean;

Checks if a task with the given ID is already in the queue.

Parameters¶

TaskID: The task identifier to check for.

Returns¶

Boolean: True if a task with this ID exists in the queue, False otherwise.

TThreadPool.Submit¶

function TThreadPool.Submit(const TaskID: String; Method: procedure() of object; Priority: Integer = 0; AllowDuplicates: Boolean = False): Boolean;

Submits a task to the pool’s queue for execution. By default, prevents duplicate task IDs. Returns True on successful submission.

Parameters¶

TaskID: A unique identifier for the task.
Method: The procedure to be executed.
Priority: The task’s priority (higher values execute sooner). Default is 0.
AllowDuplicates: Whether to allow duplicate task IDs. Default is False.

Returns¶

Boolean: True if task was successfully submitted, False otherwise.

Example:

if Pool.Submit('MyTask', @MyProcedure, 5) then
  WriteLn('Task submitted successfully');

TThreadPool.GetTask¶

function TThreadPool.GetTask(): PThreadTask;

Internal function used by workers to retrieve the next task from the queue. This should not be called directly by user code.

Returns¶

PThreadTask: Pointer to the next task, or nil if queue is empty.

TThreadPool.ProcessTask¶

procedure TThreadPool.ProcessTask(Task: PThreadTask; WorkerID: Integer);

Internal function that executes a task’s method, handles exceptions, and triggers completion/exception callbacks. This should not be called directly by user code.

Parameters¶

Task: Pointer to the task to process.
WorkerID: ID of the worker executing this task.

TThreadPool.QueueSize¶

function TThreadPool.QueueSize(): Integer;

Returns the current number of tasks waiting in the queue.

Returns¶

Integer: Number of tasks currently in the queue.

TThreadPool.ActiveWorkers¶

function TThreadPool.ActiveWorkers(): Integer;

Returns the number of worker threads that are currently running.

Returns¶

Integer: Number of active worker threads.

TThreadPool.BusyWorkers¶

function TThreadPool.BusyWorkers(): Integer;

Returns the number of worker threads that are currently executing a task.

Returns¶

Integer: Number of busy worker threads.

TThreadPool.Await¶

procedure TThreadPool.Await(TimeoutMS: Integer = 30000);

Waits until the task queue is empty and all workers are idle, or until the timeout is reached.

Parameters¶

TimeoutMS: Maximum time to wait in milliseconds. Default is 30 seconds.

TThreadPool.GetStats¶

function TThreadPool.GetStats(): String;

Returns a formatted string containing performance statistics for the thread pool.

Returns¶

String: Detailed statistics including worker counts, task metrics, and runtime.

TThreadPool.ResetStats¶

procedure TThreadPool.ResetStats();

Resets the performance counters of the thread pool. This clears all task counts and resets the start time.

TThreadScheduler.Loop¶

procedure TThreadScheduler.Loop();

The main loop for the scheduler. It periodically checks all scheduled tasks and submits them to its thread pool for execution if their interval has elapsed. This method runs in a separate thread and should not be called manually.

TThreadScheduler.Init¶

procedure TThreadScheduler.Init(const Name: String; ThreadCount: Integer = 0; DebugLevel: EDebugLevel = EDebugLevel.NONE);

Initializes the scheduler, its internal thread pool, and starts the scheduling loop.

Parameters¶

Name: A name for the scheduler, used in logging and thread naming.
ThreadCount: Number of worker threads for the scheduler’s pool. If 0, uses default.
DebugLevel: The verbosity level for logging.

TThreadScheduler.Free¶

procedure TThreadScheduler.Free();

Frees all resources used by the scheduler, including its thread pool and management thread. Always call this when you’re done with a scheduler to prevent memory leaks.

TThreadScheduler.Schedule¶

function TThreadScheduler.Schedule(const TaskID: String; Method: procedure() of object; IntervalMS: Integer = 100): Boolean;

Schedules a new recurring task.

Parameters¶

TaskID: A unique identifier for the task.
Method: The procedure to execute.
IntervalMS: The interval in milliseconds at which to run the task. Default is 100ms.

Returns¶

Boolean: True if task was successfully scheduled, False otherwise.

TThreadScheduler.Pause¶

function TThreadScheduler.Pause(const TaskID: String): Boolean;

Pauses a recurring task, preventing it from being scheduled for execution. Returns True if the task was found and paused.

Parameters¶

TaskID: The ID of the task to pause.

Returns¶

Boolean: True if task was found and paused, False otherwise.

TThreadScheduler.PauseAll¶

procedure TThreadScheduler.PauseAll();

Pauses all currently active scheduled tasks.

TThreadScheduler.Unschedule¶

function TThreadScheduler.Unschedule(const TaskID: String): Boolean;

Permanently removes a recurring task from the scheduler. Returns True if the task was found and removed.

Parameters¶

TaskID: The ID of the task to remove.

Returns¶

Boolean: True if task was found and removed, False otherwise.

TThreadScheduler.Resume¶

function TThreadScheduler.Resume(const TaskID: String): Boolean;

Resumes a paused recurring task. Returns True if the task was found and resumed.

Parameters¶

TaskID: The ID of the task to resume.

Returns¶

Boolean: True if task was found and resumed, False otherwise.

TThreadScheduler.GetTasks¶

function TThreadScheduler.GetTasks(): TStringArray;

Returns a string array of the IDs of all currently active scheduled tasks.

Returns¶

TStringArray: Array containing the IDs of all active scheduled tasks.

TThreadManager.Init¶

procedure TThreadManager.Init(ThreadCount: Integer = 0; DebugLevel: EDebugLevel = EDebugLevel.NONE);

Initializes the thread manager, which in turn sets up the main thread pool and the scheduler. This is the main entry point for using the library.

Parameters¶

ThreadCount: Number of worker threads for the main pool. If 0, uses system default.
DebugLevel: The verbosity level for logging.

Example:

var Manager: TThreadManager;
Manager.Init(8, EDebugLevel.INFO);

TThreadManager.Free¶

procedure TThreadManager.Free();

Frees all resources used by the thread manager, including its thread pool and scheduler. Always call this when you’re done with the thread manager to prevent memory leaks.

TThreadManager.Submit¶

function TThreadManager.Submit(const TaskID: String; Method: procedure() of object; Priority: Integer = 0; AllowDuplicates: Boolean = False): Boolean;

Submits a one-off task for asynchronous execution. By default, prevents duplicate task IDs.

Parameters¶

TaskID: A unique identifier for the task.
Method: The procedure to execute.
Priority: Task priority (higher values execute sooner). Default is 0.
AllowDuplicates: Whether to allow duplicate task IDs. Default is False.

Returns¶

Boolean: True if task was successfully submitted, False otherwise.

TThreadManager.Schedule¶

function TThreadManager.Schedule(const TaskID: String; Method: procedure() of object; IntervalMS: Integer): Boolean;

Schedules a recurring task to be executed at a fixed interval.

Parameters¶

TaskID: A unique identifier for the task.
Method: The procedure to execute.
IntervalMS: The interval in milliseconds between executions.

Returns¶

Boolean: True if task was successfully scheduled, False otherwise.

TThreadManager.PauseTask¶

function TThreadManager.PauseTask(const TaskID: String): Boolean;

Pauses a scheduled task.

Parameters¶

TaskID: The ID of the task to pause.

Returns¶

Boolean: True if task was found and paused, False otherwise.

TThreadManager.ResumeTask¶

function TThreadManager.ResumeTask(const TaskID: String): Boolean;

Resumes a previously paused scheduled task.

Parameters¶

TaskID: The ID of the task to resume.

Returns¶

Boolean: True if task was found and resumed, False otherwise.

TThreadManager.CancelTask¶

function TThreadManager.CancelTask(const TaskID: String): Boolean;

Permanently removes a scheduled task.

Parameters¶

TaskID: The ID of the task to cancel.

Returns¶

Boolean: True if task was found and canceled, False otherwise.

TThreadManager.SubmitBatch¶

function TThreadManager.SubmitBatch(const TaskIDs: TStringArray; Methods: array of procedure() of object): Boolean;

Submits a batch of one-off tasks for execution.

Parameters¶

TaskIDs: Array of unique identifiers for the tasks.
Methods: Array of procedures to execute (must match TaskIDs length).

Returns¶

Boolean: True if all tasks were successfully submitted, False if any failed.

TThreadManager.Await¶

procedure TThreadManager.Await(TimeoutMS: Integer = 30000);

Waits for all submitted one-off tasks to complete.

Parameters¶

TimeoutMS: Maximum time to wait in milliseconds. Default is 30 seconds.

TThreadManager.Stats¶

function TThreadManager.Stats(): String;

Returns a string containing performance statistics for both the main pool and the scheduler.

Returns¶

String: Detailed statistics including pool metrics and scheduled task count.

TThreadManager.SetExceptionHandler¶

procedure TThreadManager.SetExceptionHandler(Handler: TOnException);

Sets a global callback to handle exceptions from any task in the manager.

Parameters¶

Handler: The exception handler callback procedure.

TThreadManager.SetCompletionHandler¶

procedure TThreadManager.SetCompletionHandler(Handler: TOnComplete);

Sets a global callback to handle the completion of any task in the manager.

Parameters¶

Handler: The completion handler callback procedure.

TThreadManager.SetDebugLevel¶

procedure TThreadManager.SetDebugLevel(Level: EDebugLevel);

Sets the logging verbosity level for the entire thread manager and its components.

Parameters¶

Level: The debug level to set (EDebugLevel.NONE, EDebugLevel.INFO, or EDebugLevel.VERBOSE).