Unit Threads
From Ultibo.org
Return to Unit Reference
Description
Ultibo Threads interface unit Locking Primitives
Spin -
A simple spin lock for fast mutually exclusive access to data. Threads "spin" while waiting to acquire the lock and do not yield the CPU unless pre-empted.
Non recursive (can only be acquired once by the same thread)
Includes IRQ/FIQ entry and exit routines to Save/Restore the IRQ/FIQ state.
Suitable for use by Interrupt handlers if non interrupt callers use the IRQ/FIQ entry and exit routines to Lock and Unlock.
Suitable for use on multiprocessor systems if the lock is allocated from shared memory (Determined during initialization).
Not recommended for long held operations or holding during I/O operations.
Access is not serialized, the next thread to try obtaining the lock when it is released will succeed even if that thread was not the first waiting.
Usage:
Create/Destroy
Spin locks are created using SpinCreate() and destroyed using SpinDestroy(), these functions should not be called from within an Interrupt handler. Lock/Unlock (Data accessed only by threads)
To synchronize data access between threads each thread should call SpinLock() before accessing the data and SpinUnlock() when finished accessing the data. These calls do not affect the state of IRQs or FIQs and therefore do not impact interrupt latency. Lock/Unlock (Data accessed by threads and interrupt handlers)
To use a Spin lock to synchronise data access between threads and an interrupt handler each thread should call SpinLockIRQ() or SpinLockFIQ(), depending on whether the interrupt handler is servicing IRQ or FIQ requests, before accessing the data and SpinUnlockIRQ() or SpinUnlockFIQ() when finished accessing the data. These calls disable interrupts before acquiring the lock (with deadlock protection) and restore interrupts after releaseing the lock and therefore should only be used to protect very short sections of code accessing shared data to minimize the impact on interrupt latency.
Interrupt handlers should call SpinLock() before accessing the data and SpinUnlock() when finished accessing the data. In a Uniprocessor system it is technically not necessary for interrupt handlers to call lock/unlock as the use of IRQ/FIQ disable/enable will prevent interrupt handlers from executing while a thread has the lock. On a Multiprocessor system however interrupt handlers can execute on one processor while a thread is executing on another (which will not deadlock), to correctly synchronize data access both threads and interrupt handlers should call the appropriate lock/unlock before and after access to the data.
Lock Hierachy
It is safe to acquire one lock using SpinLock() then another lock using SpinLock() and then release them in reverse order.
It is also safe to acquire one lock using SpinLock() then another lock using SpinLockIRQ(or FIQ)() and then release them in reverse order.
It is NOT safe to acquire one lock using SpinLockIRQ(or FIQ)() then another lock using SpinLock() and then release them in reverse order. This is because the first SpinLockIRQ(or FIQ)() can disable the scheduling and prevent thread preemption. If another thread is already holding the second lock then this sequence will deadlock (except on a multicore system where the other thread is running on a different CPU).
It is also safe to acquire one lock using SpinLockIRQ(or FIQ)() then another lock using SpinLockIRQ(or FIQ)() and then release them in reverse order. In this case you must ensure that any thread aquiring the second lock also calls SpinLockIRQ(or FIQ)() to thereby avoid the deadlock.
It is NOT safe to acquire one lock using SpinLockIRQ(or FIQ)() then another lock using SpinLockIRQ(or FIQ)() and then release them in the SAME order. If the situation absolutely requires this behavious then you must use SpinExchangeIRQ(or FIQ)() when holding both locks in order to reverse the order of the IRQ or FIQ renabling.
Mutex -
A mutually exlusive lock for controlling access to data. Threads yield while waiting to acquire the lock. Non recursive (can only be acquired once by the same thread)
Not suitable for use by Interrupt handlers.
Suitable for use on multiprocessor systems if the lock is allocated from shared memory (Determined during initialization).
Recommended for long held operations or holding during I/O operations.
Access is not serialized, the next thread to try obtaining the lock when it is released will succeed even if that thread was not the first waiting.
CriticalSection -
A mutually exlusive lock for serializing access to data. Threads are placed on a wait list while waiting to acquire the lock.
Recursive (can be acquired multiple times by the same thread)
Not suitable for use by Interrupt handlers.
Suitable for use on multiprocessor systems.
Recommended for long held operations or holding during I/O operations.
Access is serialized, the next thread to obtain the lock when it is released will be the thread that has been waiting longest.
Semaphore -
Suitable for use by Interrupt handlers for signaling only if created with SEMAPHORE_FLAG_IRQ or FIQ (Interrupt handlers must not call wait).
Suitable for use on multiprocessor systems.
Access is serialized, the next thread to acquire the semaphore when it is signaled will be the thread that has been waiting longest.
Synchronizer -
A reader/writer lock for serializing multiple concurrent reads and single writes to data. Threads are placed on a wait list while waiting to acquire the lock.
Recursive (reader lock can be acquired multiple times by the same thread or by other threads / writer lock can be acquired multiple times by the same thread) Not suitable for use by Interrupt handlers.
Suitable for use on multiprocessor systems.
Recommended for long held operations or holding during I/O operations.
Access is serialized, the next thread to obtain the lock when it is released will be the thread that has been waiting longest.
Constants
Lock constants
LOCK_FLAG_* LOCK_FLAG_NONE = $00000000;
|
|
LOCK_FLAG_IRQ = $00000001;
|
|
LOCK_FLAG_FIQ = $00000002;
|
|
LOCK_FLAG_IRQFIQ = $00000004;
|
Spin constants
SPIN_* SPIN_SIGNATURE = $0FEC3B82;
|
Spin state constants
SPIN_STATE_* SPIN_STATE_UNLOCKED = 0;
|
|
SPIN_STATE_LOCKED = 1;
|
Mutex constants
MUTEX_* MUTEX_SIGNATURE = $1C5D7FA4;
|
Mutex state constants
MUTEX_STATE_* MUTEX_STATE_UNLOCKED = 0;
|
|
MUTEX_STATE_LOCKED = 1;
|
Mutex flags constants
MUTEX_FLAG_* MUTEX_FLAG_NONE = $00000000;
|
|
MUTEX_FLAG_RECURSIVE = $00000001;
|
Critical section constants
CRITICAL_SECTION_* CRITICAL_SECTION_SIGNATURE = $25F3AE01;
|
Critical section state constants
CRITICAL_SECTION_STATE_* CRITICAL_SECTION_STATE_UNLOCKED = 0;
|
|
CRITICAL_SECTION_STATE_LOCKED = 1;
|
Semaphore constants
SEMAPHORE_* SEMAPHORE_SIGNATURE = $390A1EB4;
|
Semaphore flag constants
SEMAPHORE_FLAG_* SEMAPHORE_FLAG_NONE = LOCK_FLAG_NONE;
|
|
SEMAPHORE_FLAG_IRQ = LOCK_FLAG_IRQ;
|
|
SEMAPHORE_FLAG_FIQ = LOCK_FLAG_FIQ;
|
|
SEMAPHORE_FLAG_IRQFIQ = LOCK_FLAG_IRQFIQ;
|
Synchronizer constants
SYNCHRONIZER_* SYNCHRONIZER_SIGNATURE = $C5D081FB;
|
Synchronizer state constants
SYNCHRONIZER_STATE_* SYNCHRONIZER_STATE_UNLOCKED = 0;
|
|
SYNCHRONIZER_STATE_READER_LOCKED = 1;
|
|
SYNCHRONIZER_STATE_WRITER_LOCKED = 2;
|
Synchronizer flag constants
SYNCHRONIZER_FLAG_* SYNCHRONIZER_FLAG_NONE = $00000000;
|
|
SYNCHRONIZER_FLAG_READ_PRIORITY = $00000001;
|
Synchronizer prioritises readers over writers |
SYNCHRONIZER_FLAG_WRITE_PRIORITY = $00000002;
|
Synchronizer prioritises writers over readers |
List constants
LIST_* LIST_SIGNATURE = $4A98BE2A;
|
List type constants
LIST_TYPE_* LIST_TYPE_NOT_SPECIFIED = 0;
|
A generic thread list without a specific purpose |
LIST_TYPE_WAIT_SECTION = 1;
|
A Critical Section Wait List |
LIST_TYPE_WAIT_SEMAPHORE = 2;
|
A Semaphore Wait List |
LIST_TYPE_WAIT_SYNCHRONIZER = 3;
|
A Synchronizer Wait List |
LIST_TYPE_WAIT_EVENT = 4;
|
An Event Wait List |
LIST_TYPE_WAIT_THREAD = 5;
|
A Thread Wait List |
LIST_TYPE_WAIT_MESSAGESLOT = 6;
|
A Messageslot Wait List |
LIST_TYPE_WAIT_OTHER = 7;
|
Another type of Wait List (Suitable for passing to ThreadWait/ThreadWaitEx/ThreadWaitMultiple/ThreadRelease) |
List flag constants
LIST_FLAG_* LIST_FLAG_NONE = LOCK_FLAG_NONE;
|
|
LIST_FLAG_IRQ = LOCK_FLAG_IRQ;
|
|
LIST_FLAG_FIQ = LOCK_FLAG_FIQ;
|
|
LIST_FLAG_IRQFIQ = LOCK_FLAG_IRQFIQ;
|
Queue constants
QUEUE_* QUEUE_SIGNATURE = $57A3BF9E;
|
Queue type constants
QUEUE_TYPE_* QUEUE_TYPE_NOT_SPECIFIED = 0;
|
A generic thread queue without a specific purpose |
QUEUE_TYPE_SCHEDULE_SLEEP = 1;
|
A Scheduler Sleep Queue |
QUEUE_TYPE_SCHEDULE_TIMEOUT = 2;
|
A Scheduler Timeout Queue |
QUEUE_TYPE_SCHEDULE_TERMINATION = 3;
|
A Scheduler Termination Queue (Threads are placed on termination queue when they exit or are terminated) |
QUEUE_TYPE_SCHEDULE_NONE = 4;
|
A Scheduler No Priority Queue (Only used for IRQ/FIQ threads which are never selected for scheduling) |
QUEUE_TYPE_SCHEDULE_IDLE = 5;
|
A Scheduler Idle Priority Queue |
QUEUE_TYPE_SCHEDULE_LOWEST = 6;
|
A Scheduler Lowest Priority Queue |
QUEUE_TYPE_SCHEDULE_LOWER = 7;
|
A Scheduler Lower Priority Queue |
QUEUE_TYPE_SCHEDULE_NORMAL = 8;
|
A Scheduler Normal Priority Queue |
QUEUE_TYPE_SCHEDULE_HIGHER = 9;
|
A Scheduler Higher Priority Queue |
QUEUE_TYPE_SCHEDULE_HIGHEST = 10;
|
A Scheduler Highest Priority Queue |
QUEUE_TYPE_SCHEDULE_CRITICAL = 11;
|
A Scheduler Critical Priority Queue |
Queue flag constants
QUEUE_FLAG_* NONE = LOCK_FLAG_NONE;
|
|
QUEUE_FLAG_IRQ = LOCK_FLAG_IRQ;
|
|
QUEUE_FLAG_FIQ = LOCK_FLAG_FIQ;
|
|
QUEUE_FLAG_IRQFIQ = LOCK_FLAG_IRQFIQ;
|
|
QUEUE_FLAG_DESCENDING = $00000008;
|
|
QUEUE_FLAG_DELTA = $00000010;
|
Queue key constants
QUEUE_KEY_* QUEUE_KEY_NONE = Integer($7FFFFFFF);
|
Null key value returned from an empty Queue |
QUEUE_KEY_MAX = Integer($7FFFFFFE);
|
Max key that can be ordered in a Queue |
QUEUE_KEY_MIN = Integer($80000000);
|
Min key that can be ordered in a Queue |
Thread constants
THREAD_* THREAD_SIGNATURE = $6C2BA10F;
|
Thread type constants
THREAD_TYPE_* THREAD_TYPE_NORMAL = 0;
|
A Normal thread (No special case handling) |
THREAD_TYPE_IDLE = 1;
|
An Idle thread (Used to calculate ultilization and provide an always ready thread) |
THREAD_TYPE_IRQ = 2;
|
An IRQ thread (Used by the IRQ handler during interrupt time) |
THREAD_TYPE_FIQ = 3;
|
An FIQ thread (Used by the FIQ handler during interrupt time) |
THREAD_TYPE_SWI = 4;
|
A Software Interrupt (SWI) thread (Used by the SWI handler during a system call) |
Thread state constants
THREAD_STATE_* THREAD_STATE_RUNNING = 1;
|
Thread is currently running |
THREAD_STATE_READY = 2;
|
Thread is on ready queue |
THREAD_STATE_SLEEP = 3;
|
Thread is sleeping |
THREAD_STATE_SUSPENDED = 4;
|
Thread is suspended |
THREAD_STATE_WAIT = 5;
|
Thread is on a wait list |
THREAD_STATE_WAIT_TIMEOUT = 6;
|
Thread is on a wait list with timeout |
THREAD_STATE_RECEIVE = 7;
|
Thread is waiting to receive a message |
THREAD_STATE_RECEIVE_TIMEOUT = 8;
|
Thread is waiting to receive a message with timeout |
THREAD_STATE_HALTED = 9;
|
Thread has been halted (Due to an unhandled exception etc) |
THREAD_STATE_TERMINATED = 10;
|
Thread has been terminated |
Thread priority constants
THREAD_PRIORITY_* THREAD_PRIORITY_NONE = 0;
|
Only used for IRQ/FIQ threads which are never selected for scheduling |
THREAD_PRIORITY_IDLE = 1;
|
|
THREAD_PRIORITY_LOWEST = 2;
|
|
THREAD_PRIORITY_LOWER = 3;
|
|
THREAD_PRIORITY_NORMAL = 4;
|
|
THREAD_PRIORITY_HIGHER = 5;
|
|
THREAD_PRIORITY_HIGHEST = 6;
|
|
THREAD_PRIORITY_CRITICAL = 7;
|
|
THREAD_PRIORITY_DEFAULT = THREAD_PRIORITY_NORMAL;
|
Default thread priority |
THREAD_PRIORITY_MINIMUM = THREAD_PRIORITY_IDLE;
|
Minimum thread priority |
THREAD_PRIORITY_MAXIMUM = THREAD_PRIORITY_CRITICAL;
|
Maximum thread priority |
THREAD_PRIORITY_COUNT = THREAD_PRIORITY_MAXIMUM + 1;
|
Number of thread priority levels |
| Additional priority aliases for compatibility | |
THREAD_PRIORITY_BELOW_NORMAL = THREAD_PRIORITY_LOWER;
|
|
THREAD_PRIORITY_ABOVE_NORMAL = THREAD_PRIORITY_HIGHER;
|
|
THREAD_PRIORITY_TIME_CRITICAL = THREAD_PRIORITY_CRITICAL;
|
|
Thread name constants
THREAD_NAME_* THREAD_NAME_LENGTH = 256;
|
Length of thread name |
IRQ_THREAD_NAME = 'IRQ';
|
|
FIQ_THREAD_NAME = 'FIQ';
|
|
SWI_THREAD_NAME = 'SWI';
|
|
IDLE_THREAD_NAME = 'Idle';
|
|
MAIN_THREAD_NAME = 'Main';
|
|
TIMER_THREAD_NAME = 'Timer';
|
|
WORKER_THREAD_NAME = 'Worker';
|
|
RTL_THREAD_NAME = 'RTL Thread';
|
|
Thread priority constants
*_THREAD_PRIORITY TIMER_THREAD_PRIORITY = THREAD_PRIORITY_NORMAL;
|
|
WORKER_THREAD_PRIORITY = THREAD_PRIORITY_NORMAL;
|
Thread create constants
THREAD_CREATE_* THREAD_CREATE_NONE = $00000000;
|
|
THREAD_CREATE_SUSPENDED = $00000004;
|
Thread TLS constants
THREAD_TLS_* THREAD_TLS_FREE = $00000000;
|
|
THREAD_TLS_USED = $00000001;
|
|
THREAD_TLS_INVALID = $FFFFFFFF;
|
|
THREAD_TLS_MAXIMUM = SIZE_64;
|
The maximum number TLS index slots available |
Thread TLS flag constants
THREAD_TLS_FLAG_* THREAD_TLS_FLAG_NONE = $00000000;
|
|
THREAD_TLS_FLAG_FREE = $00000001;
|
If set then pointer in thread TLS index will be freed on ThreadReleaseTlsIndex or ThreadDestroy |
Thread wait constants
THREAD_LISTS_* THREAD_LISTS_MAXIMUM = SIZE_64;
|
Maximum number of lists a thread can wait on at the same time |
Messageslot constants
MESSAGESLOT_* MESSAGESLOT_SIGNATURE = $B631CE4B;
|
Messageslot flag constants
MESSAGESLOT_FLAG_* MESSAGESLOT_FLAG_NONE = LOCK_FLAG_NONE;
|
|
MESSAGESLOT_FLAG_IRQ = LOCK_FLAG_IRQ;
|
|
MESSAGESLOT_FLAG_FIQ = LOCK_FLAG_FIQ;
|
|
MESSAGESLOT_FLAG_IRQFIQ = LOCK_FLAG_IRQFIQ;
|
Mailslot constants
MAILSLOT_* MAILSLOT_SIGNATURE = $7A409BF3;
|
Buffer constants
BUFFER_* BUFFER_SIGNATURE = $830BEA71;
|
Buffer flag constants
BUFFER_FLAG_* BUFFER_FLAG_NONE = $00000000;
|
|
BUFFER_FLAG_SHARED = $00000001;
|
If set the buffer memory (Not the buffer entry itself) is allocated from shared memory |
Event constants
EVENT_* EVENT_SIGNATURE = $903BA69D;
|
Event state constants
EVENT_STATE_* EVENT_STATE_UNSIGNALED = 0;
|
|
EVENT_STATE_SIGNALED = 1;
|
Event flag constants
EVENT_FLAG_* EVENT_FLAG_NONE = $00000000;
|
|
EVENT_FLAG_INITIAL_STATE = $00000001;
|
|
EVENT_FLAG_MANUAL_RESET = $00000002;
|
Timer constants
TIMER_* TIMER_SIGNATURE = $AB7E07FB;
|
Timer state constants
TIMER_STATE_* TIMER_STATE_DISABLED = 0;
|
|
TIMER_STATE_ENABLED = 1;
|
Timer flag constants
TIMER_FLAG_* TIMER_FLAG_NONE = $00000000;
|
|
TIMER_FLAG_RESCHEDULE = $00000001;
|
Timer should be rescheduled each time the event completes |
TIMER_FLAG_IMMEDIATE = $00000002;
|
Timer event should be executed immediately and then each interval milliseconds |
TIMER_FLAG_WORKER = $00000004;
|
Timer event should be executed by a worker thread instead of a timer thread |
Timer key constants
TIMER_KEY_* TIMER_KEY_NONE = Integer($7FFFFFFF);
|
Null key value returned from an empty Timer list |
TIMER_KEY_MAX = Integer($7FFFFFFE);
|
Max key that can be ordered in a Timer list |
TIMER_KEY_MIN = Integer($80000000);
|
Min key that can be ordered in a Timer list |
Worker constants
WORKER_* WORKER_SIGNATURE = $EF6A901B;
|
Worker flag constants
WORKER_FLAG_* WORKER_FLAG_NONE = $00000000;
|
|
WORKER_FLAG_RESCHEDULE = $00000001;
|
Worker task should be rescheduled each time the task completes |
WORKER_FLAG_IMMEDIATE = $00000002;
|
Worker task should be executed immediately and then each interval milliseconds |
WORKER_FLAG_CANCEL = $00000004;
|
Internal flag to indicate the worker task should be cancelled next time the interval expires |
WORKER_FLAG_NOFREE = $00000008;
|
Internal flag to tell worker execute not to free the worker request when it is completed |
WORKER_FLAG_TERMINATE = $00000010;
|
Internal flag to tell worker execute to terminate the worker thread |
WORKER_FLAG_IRQ = $00000020;
|
Internal flag to tell worker execute to free IRQ memory when the request is completed |
WORKER_FLAG_FIQ = $00000040;
|
Internal flag to tell worker execute to free FIQ memory when the request is completed |
Tasker task constants
TASKER_TASK_* TASKER_TASK_THREADSENDMESSAGE = 1;
|
Perform a ThreadSendMessage() function using the tasker list |
TASKER_TASK_MESSAGESLOTSEND = 2;
|
Perform a MessageslotSend() function using the tasker list |
TASKER_TASK_SEMAPHORESIGNAL = 3;
|
Perform a SemaphoreSignal() function using the tasker list |
Scheduler migration constants
SCHEDULER_MIGRATION_* SCHEDULER_MIGRATION_DISABLED = 0;
|
|
SCHEDULER_MIGRATION_ENABLED = 1;
|
Scheduler preempt constants
SCHEDULER_PREEMPT_* SCHEDULER_PREEMPT_DISABLED = 0;
|
|
SCHEDULER_PREEMPT_ENABLED = 1;
|
Scheduler allocation constants
SCHEDULER_ALLOCATION_* SCHEDULER_ALLOCATION_DISABLED = 0;
|
|
SCHEDULER_ALLOCATION_ENABLED = 1;
|
Scheduler mask constants
SCHEDULER_MASK_* SCHEDULER_MASK_NONE = (1 shl THREAD_PRIORITY_NONE);
|
|
SCHEDULER_MASK_IDLE = (1 shl THREAD_PRIORITY_IDLE);
|
|
SCHEDULER_MASK_LOWEST = (1 shl THREAD_PRIORITY_LOWEST);
|
|
SCHEDULER_MASK_LOWER = (1 shl THREAD_PRIORITY_LOWER);
|
|
SCHEDULER_MASK_NORMAL = (1 shl THREAD_PRIORITY_NORMAL);
|
|
SCHEDULER_MASK_HIGHER = (1 shl THREAD_PRIORITY_HIGHER);
|
|
SCHEDULER_MASK_HIGHEST = (1 shl THREAD_PRIORITY_HIGHEST);
|
|
SCHEDULER_MASK_CRITICAL = (1 shl THREAD_PRIORITY_CRITICAL);
|
Scheduler quantum constants
SCHEDULER_QUANTUM_* SCHEDULER_QUANTUM_NONE = 0;
|
|
SCHEDULER_QUANTUM_IDLE = 0;
|
|
SCHEDULER_QUANTUM_LOWEST = 1;
|
|
SCHEDULER_QUANTUM_LOWER = 2;
|
|
SCHEDULER_QUANTUM_NORMAL = 4;
|
|
SCHEDULER_QUANTUM_HIGHER = 6;
|
|
SCHEDULER_QUANTUM_HIGHEST = 8;
|
|
SCHEDULER_QUANTUM_CRITICAL = 10;
|
Thread logging constants
THREAD_LOG_* THREAD_LOG_LEVEL_DEBUG = LOG_LEVEL_DEBUG;
|
Thread debugging messages |
THREAD_LOG_LEVEL_INFO = LOG_LEVEL_INFO;
|
Thread informational messages, such as a thread being created or destroyed |
THREAD_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;
|
Thread error messages |
THREAD_LOG_LEVEL_NONE = LOG_LEVEL_NONE;
|
No Thread messages |
Type definitions
To be documented
Public variables
To be documented
Function declarations
Initialization functions
procedure LocksInit;
Description: Initialize Locks
| Note | None documented |
|---|
procedure ThreadsInit;
Description: Initialize Threading
| Note | None documented |
|---|
procedure PrimaryInit;
Description: Initialize the primary CPU
| Note | None documented |
|---|
procedure SchedulerInit;
Description: Initialize the thread scheduler
| Note | None documented |
|---|
procedure SchedulerStart(CPUID:LongWord);
Description: Initialize the thread scheduler for secondary CPUs (Where Applicable)
| Note | None documented |
|---|
procedure SecondaryInit;
Description: Initialize the secondary CPUs (Where Applicable)
| Note | None documented |
|---|
procedure SecondaryBoot(CPUID:LongWord);
Description: Boot the specified secondary CPU (Where Applicable)
| Note | None documented |
|---|
procedure SecondaryStart(CPUID:LongWord);
Description: Startup procedure for secondary CPUs (Where Applicable)
| Note | The Secondary Boot procedure should have already cleared L1 cache, enabled FPU, MMU, Vectors and PageTables before calling this function. The thread id of the IRQ or FIQ should also have been loaded into the appropriate registers. |
|---|
function IRQExecute(Parameter:Pointer):PtrInt;
Description: To be documented
| Note | None documented |
|---|
function FIQExecute(Parameter:Pointer):PtrInt;
Description: To be documented
| Note | None documented |
|---|
function SWIExecute(Parameter:Pointer):PtrInt;
Description: To be documented
| Note | None documented |
|---|
function IdleExecute(Parameter:Pointer):PtrInt;
Description: To be documented
| Note | None documented |
|---|
function MainExecute(Parameter:Pointer):PtrInt;
Description: To be documented
| Note | None documented |
|---|
function TimerExecute(Parameter:Pointer):PtrInt;
Description: To be documented
| Note | None documented |
|---|
function WorkerExecute(Parameter:Pointer):PtrInt;
Description: To be documented
| Note | None documented |
|---|
function IdleCalibrate:LongWord;
Description: Calibrate the idle thread loop by counting the number of loops in 100ms
| Note | None documented |
|---|
Spin functions
function SpinCreate:TSpinHandle; {$IFDEF SPIN_INLINE}inline; {$ENDIF}
Description: Create and insert a new Spin entry
| Return | Handle of new Spin entry or INVALID_HANDLE_VALUE if entry could not be created |
|---|
function SpinCreateEx(InitialOwner:Boolean):TSpinHandle;
Description: Create and insert a new Spin entry
| InitialOwner | If true set the state of the spin to locked and the owner to the current thread |
|---|---|
| Return | Handle of new Spin entry or INVALID_HANDLE_VALUE if entry could not be created |
function SpinDestroy(Spin:TSpinHandle):LongWord;
Description: Destroy and remove an existing Spin entry
| Spin | Handle of Spin entry to destroy |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SpinOwner(Spin:TSpinHandle):TThreadHandle;
Description: Get the current owner of an existing Spin entry
| Spin | Handle of Spin entry to get owner for |
|---|---|
| Return | Handle of owning thread or INVALID_HANDLE_VALUE if not currently owned |
function SpinLock(Spin:TSpinHandle):LongWord; {$IFDEF SPIN_INLINE}inline; {$ENDIF}
Description: Lock an existing Spin entry
| Spin | Handle of Spin entry to lock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SpinUnlock(Spin:TSpinHandle):LongWord; {$IFDEF SPIN_INLINE}inline; {$ENDIF}
Description: Unlock an existing Spin entry
| Spin | Handle of Spin entry to unlock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SpinLockIRQ(Spin:TSpinHandle):LongWord; {$IFDEF SPIN_INLINE}inline; {$ENDIF}
Description: Lock an existing Spin entry, disable IRQ and save the previous IRQ state
| Spin | Handle of Spin entry to lock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SpinUnlockIRQ(Spin:TSpinHandle):LongWord; {$IFDEF SPIN_INLINE}inline; {$ENDIF}
Description: Unlock an existing Spin entry and restore the previous IRQ state
| Spin | Handle of Spin entry to unlock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SpinLockFIQ(Spin:TSpinHandle):LongWord; {$IFDEF SPIN_INLINE}inline; {$ENDIF}
Description: Lock an existing Spin entry, disable FIQ and save the previous FIQ state
| Spin | Handle of Spin entry to lock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SpinUnlockFIQ(Spin:TSpinHandle):LongWord; {$IFDEF SPIN_INLINE}inline; {$ENDIF}
Description: Unlock an existing Spin entry and restore the previous FIQ state
| Spin | Handle of Spin entry to unlock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SpinLockIRQFIQ(Spin:TSpinHandle):LongWord; {$IFDEF SPIN_INLINE}inline; {$ENDIF}
Description: Lock an existing Spin entry, disable IRQ and FIQ and save the previous IRQ and FIQ state
| Spin | Handle of Spin entry to lock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SpinUnlockIRQFIQ(Spin:TSpinHandle):LongWord; {$IFDEF SPIN_INLINE}inline; {$ENDIF}
Description: Unlock an existing Spin entry and restore the previous IRQ and FIQ state
| Spin | Handle of Spin entry to unlock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SpinCheckIRQ(Spin:TSpinHandle):Boolean;
Description: Check the mask that stores the previous IRQ state to determine if IRQ is enabled
| Spin | Handle of Spin entry to check |
|---|---|
| Return | True if the mask would enable IRQ on restore, False if it would not |
| Note | The Spin entry must be locked by the current thread |
function SpinCheckFIQ(Spin:TSpinHandle):Boolean;
Description: Check the mask that stores the previous FIQ state to determine if FIQ is enabled
| Spin | Handle of Spin entry to check |
|---|---|
| Return | True if the mask would enable FIQ on restore, False if it would not |
| Note | The Spin entry must be locked by the current thread |
function SpinExchangeIRQ(Spin1,Spin2:TSpinHandle):LongWord;
Description: Exchange the previous IRQ state between two Spin entries
| Spin1 | Handle of first Spin entry |
|---|---|
| Spin2 | Handle of second Spin entry |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Both Spin entries must be locked by the current thread |
function SpinExchangeFIQ(Spin1,Spin2:TSpinHandle):LongWord;
Description: Exchange the previous FIQ state between two Spin entries
| Spin1 | Handle of first Spin entry |
|---|---|
| Spin2 | Handle of second Spin entry |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Both Spin entries must be locked by the current thread |
function SpinLockDefault(SpinEntry:PSpinEntry):LongWord;
Description: Default version of SpinLock function used if no handler is registered
| Note | Not intended to be called directly by applications, use SpinLock instead |
|---|
function SpinUnlockDefault(SpinEntry:PSpinEntry):LongWord;
Description: Default version of SpinUnlock function used if no handler is registered
| Note | Not intended to be called directly by applications, use SpinUnlock instead |
|---|
function SpinLockIRQDefault(SpinEntry:PSpinEntry):LongWord;
Description: Default version of SpinLockIRQ function used if no handler is registered
| Note | Not intended to be called directly by applications, use SpinLockIRQ instead |
|---|
function SpinUnlockIRQDefault(SpinEntry:PSpinEntry):LongWord;
Description: Default version of SpinUnlockIRQ function used if no handler is registered
| Note | Not intended to be called directly by applications, use SpinUnlockIRQ instead |
|---|
function SpinLockFIQDefault(SpinEntry:PSpinEntry):LongWord;
Description: Default version of SpinLockFIQ function used if no handler is registered
| Note | Not intended to be called directly by applications, use SpinLockFIQ instead |
|---|
function SpinUnlockFIQDefault(SpinEntry:PSpinEntry):LongWord;
Description: Default version of SpinUnlockFIQ function used if no handler is registered
| Note | Not intended to be called directly by applications, use SpinUnlockFIQ instead |
|---|
function SpinLockIRQFIQDefault(SpinEntry:PSpinEntry):LongWord;
Description: Default version of SpinLockIRQFIQ function used if no handler is registered
| Note | Not intended to be called directly by applications, use SpinLockIRQFIQ instead |
|---|
Mutex functions
function MutexCreate:TMutexHandle; {$IFDEF MUTEX_INLINE}inline; {$ENDIF}
Description: Create and insert a new Mutex entry
| Return | Handle of new Mutex entry or INVALID_HANDLE_VALUE if entry could not be created |
|---|
function MutexCreateEx(InitialOwner:Boolean; SpinCount:LongWord; Flags:LongWord):TMutexHandle;
Description: Create and insert a new Mutex entry
| InitialOwner | If true set the state of the mutex to locked and the owner to the current thread |
|---|---|
| SpinCount | The number of times the mutex will spin before yielding (Always 0 if CPU count equals 1) |
| Flags | The flags for the Mutex entry (eg MUTEX_FLAG_RECURSIVE) |
| Return | Handle of new Mutex entry or INVALID_HANDLE_VALUE if entry could not be created |
function MutexDestroy(Mutex:TMutexHandle):LongWord;
Description: Destroy and remove an existing Mutex entry
| Mutex | Handle of Mutex entry to destroy |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MutexFlags(Mutex:TMutexHandle):LongWord;
Description: Get the current flags of an existing Mutex entry
| Mutex | Handle of Mutex entry to get flags for |
|---|---|
| Return | Current flags or INVALID_HANDLE_VALUE on error |
function MutexLock(Mutex:TMutexHandle):LongWord; {$IFDEF MUTEX_INLINE}inline; {$ENDIF}
Description: Lock an existing Mutex entry
| Mutex | Handle of Mutex entry to lock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MutexUnlock(Mutex:TMutexHandle):LongWord; {$IFDEF MUTEX_INLINE}inline; {$ENDIF}
Description: Unlock an existing Mutex entry
| Mutex | Handle of Mutex entry to unlock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MutexTryLock(Mutex:TMutexHandle):LongWord; {$IFDEF MUTEX_INLINE}inline; {$ENDIF}
Description: Try to lock an existing Mutex entry. If the Mutex is not locked then lock it and mark the owner as the current thread. If the Mutex is already locked then return immediately with an error and do not wait for it to be unlocked.
| Mutex | Mutex to try to lock |
|---|---|
| Return | ERROR_SUCCESS if completed, ERROR_LOCKED if already locked or another error code on failure |
function MutexCount(Mutex:TMutexHandle):LongWord;
Description: Get the current lock count of an existing Mutex entry
| Mutex | Mutex to get count for |
|---|---|
| Return | Current lock count or INVALID_HANDLE_VALUE on error |
| Note | Count is only valid if Flags includes MUTEX_FLAG_RECURSIVE |
function MutexOwner(Mutex:TMutexHandle):TThreadHandle;
Description: Get the current owner of an existing Mutex entry
| Mutex | Handle of Mutex entry to get owner for |
|---|---|
| Return | Handle of owning thread or INVALID_HANDLE_VALUE if not currently owned |
function MutexLockDefault(MutexEntry:PMutexEntry):LongWord;
Description: Default version of MutexLock function used if no handler is registered
| Note | Not intended to be called directly by applications, use MutexLock instead |
|---|
function MutexUnlockDefault(MutexEntry:PMutexEntry):LongWord;
Description: Default version of MutexUnlock function used if no handler is registered
| Note | Not intended to be called directly by applications, use MutexUnlock instead |
|---|
function MutexTryLockDefault(MutexEntry:PMutexEntry):LongWord;
Description: Default version of MutexTryLock function used if no handler is registered
| Note | Not intended to be called directly by applications, use MutexTryLock instead |
|---|
Critical section functions
function CriticalSectionCreate:TCriticalSectionHandle;
Description: Create and insert a new CriticalSection entry
| Return | Handle of new CriticalSection entry or INVALID_HANDLE_VALUE if entry could not be created |
|---|
function CriticalSectionCreateEx(InitialOwner:Boolean; SpinCount:LongWord):TCriticalSectionHandle;
Description: Create and insert a new CriticalSection entry
| CriticalSection | If true set the state of the criticalsection to locked and the owner to the current thread |
|---|---|
| SpinCount | The number of times the criticalsection will spin before waiting (Always 0 if CPU count equals 1) |
| Return | Handle of new CriticalSection entry or INVALID_HANDLE_VALUE if entry could not be created |
function CriticalSectionDestroy(CriticalSection:TCriticalSectionHandle):LongWord;
Description: Destroy and remove an existing CriticalSection entry
| CriticalSection | Handle of CriticalSection entry to destroy |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function CriticalSectionCount(CriticalSection:TCriticalSectionHandle):LongWord;
Description: Get the current lock count of an existing CriticalSection entry
| CriticalSection | CriticalSection to get count for |
|---|---|
| Return | Current lock count or INVALID_HANDLE_VALUE on error |
function CriticalSectionOwner(CriticalSection:TCriticalSectionHandle):TThreadHandle;
Description: Get the current owner of an existing CriticalSection entry
| CriticalSection | CriticalSection to get owner for |
|---|---|
| Return | Handle of owning thread or INVALID_HANDLE_VALUE if not currently owned |
function CriticalSectionSetSpinCount(CriticalSection:TCriticalSectionHandle; SpinCount:LongWord):LongWord;
Description: Set the spin count of an existing CriticalSection entry
| CriticalSection | CriticalSection to set spin count for |
|---|---|
| SpinCount | The spin count value to set |
| Return | Current spin count or INVALID_HANDLE_VALUE on error |
function CriticalSectionLock(CriticalSection:TCriticalSectionHandle):LongWord;
Description: Lock an existing CriticalSection entry
| CriticalSection | CriticalSection to lock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If the CriticalSection is not locked then lock it, set the count to one and mark the owner as the current thread. If the CriticalSection is already locked by the current thread then increment the count and return immediately. If the CriticalSection is already locked by another thread then wait until it is unlocked. |
function CriticalSectionLockEx(CriticalSection:TCriticalSectionHandle; Timeout:LongWord):LongWord;
Description: Lock an existing CriticalSection entry
| CriticalSection | CriticalSection to lock |
|---|---|
| Timeout | Milliseconds to wait before timeout (0 equals do not wait, INFINITE equals wait forever) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If the CriticalSection is not locked then lock it, set the count to one and mark the owner as the current thread. If the CriticalSection is already locked by the current thread then increment the count and return immediately. If the CriticalSection is already locked by another thread then wait until it is unlocked. |
function CriticalSectionUnlock(CriticalSection:TCriticalSectionHandle):LongWord;
Description: Unlock an existing CriticalSection entry
| CriticalSection | CriticalSection to unlock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If the CriticalSection is locked by the current thread then decrement the count. If the count is greater than zero then return immediately. If the count reaches zero then unlock the CriticalSection and release the first thread waiting for it to be unlocked. If the CriticalSection is locked by another thread then return an error. If the CriticalSection is not locked then return an error. |
function CriticalSectionTryLock(CriticalSection:TCriticalSectionHandle):LongWord;
Description: Try to lock an existing CriticalSection entry
| CriticalSection | CriticalSection to try to lock |
|---|---|
| Return | ERROR_SUCCESS if completed, ERROR_LOCKED if locked by another thread or another error code on failure |
| Note | If the CriticalSection is not locked then lock it, set the count to one and mark the owner as the current thread. If the CriticalSection is already locked by the current thread then increment the count and return immediately. If the CriticalSection is already locked by another thread then return immediately with an error and do not wait for it to be unlocked. |
Semaphore functions
function SemaphoreCreate(Count:LongWord):TSemaphoreHandle;
Description: Create and insert a new Semaphore entry
| Count | The initial count of the Semaphore (Must be greater than or equal to zero) |
|---|---|
| Return | Handle of new Semaphore entry or INVALID_HANDLE_VALUE if entry could not be created |
function SemaphoreCreateEx(Count,Maximum:LongWord; Flags:LongWord):TSemaphoreHandle;
Description: Create and insert a new Semaphore entry
| Count | The initial count of the Semaphore (Must be greater than or equal to zero) |
|---|---|
| Maximum | The maximum count of the Semaphore (Must be greater than one) |
| Flags | The flags for the Semaphore entry (eg SEMAPHORE_FLAG_IRQ) |
| Return | Handle of new Semaphore entry or INVALID_HANDLE_VALUE if entry could not be created |
function SemaphoreDestroy(Semaphore:TSemaphoreHandle):LongWord;
Description: Destroy and remove an existing Semaphore entry
| Semaphore | Handle of Semaphore entry to destroy |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SemaphoreCount(Semaphore:TSemaphoreHandle):LongWord;
Description: Get the current count of an existing Semaphore entry
| Semaphore | Semaphore to get count for |
|---|---|
| Return | Current count or INVALID_HANDLE_VALUE on error |
function SemaphoreWait(Semaphore:TSemaphoreHandle):LongWord;
Description: Wait on an existing Semaphore entry
| Semaphore | Semaphore to wait on |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If the Semaphore count is greater than zero it will be decremented and this function will return immediately. If the Semaphore count is zero the current thread will be put on a wait queue until the Semaphore is signalled by another thread calling SemaphoreSignal() or SemaphoreSignalEx(). |
function SemaphoreWaitEx(Semaphore:TSemaphoreHandle; Timeout:LongWord):LongWord;
Description: Wait on an existing Semaphore entry
| Semaphore | Semaphore to wait on |
|---|---|
| Timeout | Milliseconds to wait before timeout (0 equals do not wait, INFINITE equals wait forever) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If the Semaphore count is greater than zero it will be decremented and this function will return immediately. If the Semaphore count is zero the current thread will be put on a wait queue until the Semaphore is signalled by another thread calling SemaphoreSignal() or SemaphoreSignalEx(). |
function SemaphoreSignal(Semaphore:TSemaphoreHandle):LongWord;
Description: Signal an existing Semaphore entry
| Semaphore | Semaphore to signal |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If any threads are waiting on the Semaphore then one thread will be woken up and placed on the ready queue. If no threads are wait then the Semaphore count will be incremented. |
function SemaphoreSignalEx(Semaphore:TSemaphoreHandle; Count:LongWord; Previous:PLongWord):LongWord;
Description: Signal an existing Semaphore entry one or more times
| Semaphore | Semaphore to signal |
|---|---|
| Count | The number is times to signal the Semaphore, must be greater than zero |
| Previous | A pointer to a value that receives the previous count of the Semaphore. Can be nil if the previous count is not required |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If any threads are waiting on the Semaphore then one thread will be woken up and placed on the ready queue for each interation of the count passed. If no threads are wait then the Semaphore count will be incremented once for each interation of the count passed. |
Synchronizer functions
function SynchronizerCreate:TSynchronizerHandle;
Description: Create and insert a new Synchronizer entry
| Return | Handle of new Synchronizer entry or INVALID_HANDLE_VALUE if entry could not be created |
|---|
function SynchronizerCreateEx(InitialReader,InitialWriter:Boolean):TSynchronizerHandle;
Description: Create and insert a new Synchronizer entry
| InitialReader | If true set the state of the synchronizer to locked and the reader count to 1 |
|---|---|
| InitialWriter | If true set the state of the synchronizer to locked and the writer owner to the current thread |
| Return | Handle of new Synchronizer entry or INVALID_HANDLE_VALUE if entry could not be created |
function SynchronizerDestroy(Synchronizer:TSynchronizerHandle):LongWord;
Description: Destroy and remove an existing Synchronizer entry
| Synchronizer | Handle of Synchronizer entry to destroy |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SynchronizerReaderCount(Synchronizer:TSynchronizerHandle):LongWord;
Description: Get the current reader count of an existing Synchronizer entry
| Synchronizer | Synchronizer to get count for |
|---|---|
| Return | Current reader count or INVALID_HANDLE_VALUE on error |
function SynchronizerReaderLast(Synchronizer:TSynchronizerHandle):TThreadHandle;
Description: Get the last reader thread of an existing Synchronizer entry
| Synchronizer | Synchronizer to last reader for |
|---|---|
| Return | Last reader thread or INVALID_HANDLE_VALUE on error |
function SynchronizerReaderLock(Synchronizer:TSynchronizerHandle):LongWord;
Description: Lock an existing Synchronizer entry for reading
| Synchronizer | Synchronizer to lock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If the Synchronizer is not locked then lock it and set the reader count to one. If the Synchronizer is already locked for reading then increment the reader count and return immediately. If the Synchronizer is already locked for writing then wait until it is unlocked. |
function SynchronizerReaderLockEx(Synchronizer:TSynchronizerHandle; Timeout:LongWord):LongWord;
Description: Lock an existing Synchronizer entry for reading
| Synchronizer | Synchronizer to lock |
|---|---|
| Timeout | Milliseconds to wait before timeout (0 equals do not wait, INFINITE equals wait forever) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If the Synchronizer is not locked then lock it and set the reader count to one. If the Synchronizer is already locked for reading then increment the reader count and return immediately. If the Synchronizer is already locked for writing then wait until it is unlocked. |
function SynchronizerReaderUnlock(Synchronizer:TSynchronizerHandle):LongWord;
Description: Unlock an existing Synchronizer entry
| Synchronizer | Synchronizer to unlock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If the Synchronizer is locked for reading then decrement the count. If the count is greater than zero then return immediately. If the count reaches zero then unlock the Synchronizer and release the first writer thread waiting for it to be unlocked. If the Synchronizer is locked for writing then return an error. If the Synchronizer is not locked then return an error. |
function SynchronizerReaderConvert(Synchronizer:TSynchronizerHandle):LongWord;
Description: Convert a reader lock on an existing Synchronizer entry to a writer lock
| Synchronizer | Synchronizer to convert |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If the Synchronizer is locked for reading then decrement the count. If the count is greater than zero then wait to acquire the writer lock. If the count reaches zero then convert to writer lock with the current thread as the owner. If the Synchronizer is locked for writing then return an error. If the Synchronizer is not locked then return an error. Since reader locks are recursive but do not maintain reader thread ownership, caller must ensure that one and only one reader lock is held by the current thread. |
function SynchronizerReaderConvertEx(Synchronizer:TSynchronizerHandle; Timeout:LongWord):LongWord;
Description: Convert a reader lock on an existing Synchronizer entry to a writer lock
| Synchronizer | Synchronizer to convert |
|---|---|
| Timeout | Milliseconds to wait before timeout (0 equals do not wait, INFINITE equals wait forever) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If the Synchronizer is locked for reading then decrement the count. If the count is greater than zero then wait to acquire the writer lock. If the count reaches zero then convert to writer lock with the current thread as the owner. If the Synchronizer is locked for writing then return an error. If the Synchronizer is not locked then return an error. Since reader locks are recursive but do not maintain reader thread ownership, caller must ensure that one and only one reader lock is held by the current thread. |
function SynchronizerWriterCount(Synchronizer:TSynchronizerHandle):LongWord;
Description: Get the current writer count of an existing Synchronizer entry
| Synchronizer | Synchronizer to get count for |
|---|---|
| Return | Current writer count or INVALID_HANDLE_VALUE on error |
function SynchronizerWriterOwner(Synchronizer:TSynchronizerHandle):TThreadHandle;
Description: Get the current writer owner of an existing Synchronizer entry
| Synchronizer | Synchronizer to get owner for |
|---|---|
| Return | Handle of owning thread or INVALID_HANDLE_VALUE if not currently owned |
function SynchronizerWriterLock(Synchronizer:TSynchronizerHandle):LongWord;
Description: Lock an existing Synchronizer entry for writing
| Synchronizer | Synchronizer to lock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If the Synchronizer is not locked then lock it, set the writer count to one and mark the owner as the current thread. If the Synchronizer is already locked by the current thread then increment the writer count and return immediately. If the Synchronizer is already locked for reading then wait until it is unlocked. |
function SynchronizerWriterLockEx(Synchronizer:TSynchronizerHandle; Timeout:LongWord):LongWord;
Description: Lock an existing Synchronizer entry for writing
| Synchronizer | Synchronizer to lock |
|---|---|
| Timeout | Milliseconds to wait before timeout (0 equals do not wait, INFINITE equals wait forever) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If the Synchronizer is not locked then lock it, set the writer count to one and mark the owner as the current thread. If the Synchronizer is already locked by the current thread then increment the writer count and return immediately. If the Synchronizer is already locked for reading then wait until it is unlocked. |
function SynchronizerWriterUnlock(Synchronizer:TSynchronizerHandle):LongWord;
Description: Unlock an existing Synchronizer entry
| Synchronizer | Synchronizer to unlock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If the Synchronizer is locked for writing by the current thread then decrement the count. If the count is greater than zero then return immediately. If the count reaches zero then unlock the Synchronizer and release all reader threads waiting for it to be unlocked or the first writer thread waiting for it to be unlocked. If the Synchronizer is locked for reading then return an error. If the Synchronizer is locked for writing by another thread then return an error. If the Synchronizer is not locked then return an error. |
function SynchronizerWriterConvert(Synchronizer:TSynchronizerHandle):LongWord;
Description: Convert a writer lock on an existing Synchronizer entry to a reader lock
| Synchronizer | Synchronizer to convert |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If the Synchronizer is locked for writing by the current thread and the count is one then decrement the count. If the count is greater than one then return an error. If the count reaches zero then convert to reader lock and release all waiting reader threads. If the Synchronizer is locked for reading then return an error. If the Synchronizer is not locked then return an error. Since writer locks are recursive, caller must ensure that one and only one writer lock is held by the current thread. |
List functions
function ListCreate:TListHandle; {$IFDEF LIST_INLINE}inline; {$ENDIF}
Description: Create and insert a new List entry
| Return | Handle of new List entry or INVALID_HANDLE_VALUE if entry could not be created |
|---|
function ListCreateEx(ListType:LongWord; Flags:LongWord):TListHandle;
Description: Create and insert a new List entry
| ListType | Type of list to create (eg LIST_TYPE_WAIT_SEMAPHORE) |
|---|---|
| Flags | Flags for the new list (eg LIST_FLAG_IRQ) |
| Return | Handle of new List entry or INVALID_HANDLE_VALUE if entry could not be created |
function ListDestroy(List:TListHandle):LongWord;
Description: Destroy and remove an existing List entry
| List | Handle of List entry to destroy |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If list is part of a synchronisation object then caller must hold the lock on the object containing the list |
function ListCount(List:TListHandle):LongWord;
Description: Get the current count from the supplied list
| List | Handle of List entry to get from |
|---|---|
| Return | List count on success or INVALID_HANDLE_VALUE on failure |
function ListAddFirst(List:TListHandle; Element:PListElement):LongWord;
Description: Add the supplied element as the first item in the List
| List | Handle of List entry to add to |
|---|---|
| Element | The list element to be added |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If list is part of a synchronisation object then caller must hold the lock on the object containing the list |
function ListAddLast(List:TListHandle; Element:PListElement):LongWord;
Description: Add the supplied element as the last item in the List
| List | Handle of List entry to add to |
|---|---|
| Element | The list element to be added |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If list is part of a synchronisation object then caller must hold the lock on the object containing the list |
function ListGetThread(List:TListHandle; Thread:TThreadHandle):PListElement;
Description: Find the supplied thread in the List and return its element
| List | Handle of List entry to find from |
|---|---|
| Thread | The thread handle to be found |
| Return | List element on success, nil on failure or list empty |
| Note | If list is part of a synchronisation object then caller must hold the lock on the object containing the list |
function ListGetFirst(List:TListHandle):PListElement;
Description: Get the first element from the List
| List | Handle of List entry to get from |
|---|---|
| Return | List element on success, nil on failure or list empty |
| Note | If list is part of a synchronisation object then caller must hold the lock on the object containing the list |
function ListGetFirstEx(List:TListHandle; Remove:Boolean):PListElement;
Description: Get the first element from the List
| List | Handle of List entry to get from |
|---|---|
| Remove | If true then remove the element from the list |
| Return | List element on success, nil on failure or list empty |
| Note | If list is part of a synchronisation object then caller must hold the lock on the object containing the list |
function ListGetLast(List:TListHandle):PListElement;
Description: Get the last element from the List
| List | Handle of List entry to get from |
|---|---|
| Return | List element on success, nil on failure or list empty |
| Note | If list is part of a synchronisation object then caller must hold the lock on the object containing the list |
function ListGetLastEx(List:TListHandle; Remove:Boolean):PListElement;
Description: Get the last element from the List
| List | Handle of List entry to get from |
|---|---|
| Remove | If true then remove the element from the list |
| Return | List element on success, nil on failure or list empty |
| Note | If list is part of a synchronisation object then caller must hold the lock on the object containing the list |
function ListInsert(List:TListHandle; Previous,Element:PListElement):LongWord;
Description: Insert a new element in the List
| List | Handle of List entry to insert into |
|---|---|
| Previous | The element to insert the new element after |
| Element | The list element to be inserted |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If list is part of a synchronisation object then caller must hold the lock on the object containing the list |
function ListRemove(List:TListHandle; Element:PListElement):LongWord;
Description: Remove an element from the List
| List | Handle of List entry to remove from |
|---|---|
| Element | The list element to be removed |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If list is part of a synchronisation object then caller must hold the lock on the object containing the list |
function ListIsEmpty(List:TListHandle):Boolean;
Description: Check if the supplied List is empty
| List | Handle of List entry to check |
|---|---|
| Return | True if List is empty or does not exist, False if List is not empty |
| Note | If list is part of a synchronisation object then caller must hold the lock on the object containing the list |
function ListNotEmpty(List:TListHandle):Boolean;
Description: Check if the supplied List is empty
| List | Handle of List entry to check |
|---|---|
| Return | True if List is not empty, False if List is empty or does not exist |
| Note | If list is part of a synchronisation object then caller must hold the lock on the object containing the list |
function ListLock(List:TListHandle):LongWord;
Description: Lock the supplied List
| List | Handle of List entry to lock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function ListUnlock(List:TListHandle):LongWord;
Description: Unlock the supplied List
| List | Handle of List entry to unlock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function ListLock(List:TListHandle):LongWord; {$IFDEF LIST_INLINE}inline; {$ENDIF}
Description: Lock the supplied List
| List | Handle of List entry to lock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function ListUnlock(List:TListHandle):LongWord; {$IFDEF LIST_INLINE}inline; {$ENDIF}
Description: Unlock the supplied List
| List | Handle of List entry to unlock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
Queue functions
function QueueCreate:TQueueHandle; {$IFDEF QUEUE_INLINE}inline; {$ENDIF}
Description: Create and insert a new Queue entry
| Return | Handle of new Queue entry or INVALID_HANDLE_VALUE if entry could not be created |
|---|
function QueueCreateEx(QueueType:LongWord; Flags:LongWord):TQueueHandle;
Description: Create and insert a new Queue entry}
| 'Queue'Type | Type of queue to create (eg QUEUE_TYPE_SCHEDULE_SLEEP) |
|---|---|
| Flags | Flags for the new queue (eg QUEUE_FLAG_DESCENDING) |
| Return | Handle of new Queue entry or INVALID_HANDLE_VALUE if entry could not be created |
function QueueDestroy(Queue:TQueueHandle):LongWord;
Description: Destroy and remove an existing Queue entry
| Queue | Handle of Queue entry to destroy |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function QueueCount(Queue:TQueueHandle):LongWord;
Description: Get the current count from the supplied queue
| List | Handle of Queue entry to get from |
|---|---|
| Return | Queue count on success or INVALID_HANDLE_VALUE on failure |
function QueueEnqueue(Queue:TQueueHandle; Thread:TThreadHandle):LongWord;
Description: Add the supplied thread as the last item in the Queue
| Queue | Handle of Queue entry to add to |
|---|---|
| Thread | Handle of the Thread to enqueue |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If queue is a scheduler queue then caller must hold the lock on the thread |
function QueueDequeue(Queue:TQueueHandle):TThreadHandle;
Description: Get and remove the first thread from the Queue
| Queue | Handle of Queue entry to get from |
|---|---|
| Return | Handle of dequeued Thread or INVALID_HANDLE_VALUE on failure |
function QueueFirstKey(Queue:TQueueHandle):Integer;
Description: Get the first Key value from the Queue
| Queue | Handle of Queue entry to get from |
|---|---|
| Return | First Key value from queue or QUEUE_KEY_NONE on failure |
function QueueLastKey(Queue:TQueueHandle):Integer;
Description: Get the last Key value from the Queue
| Queue | Handle of Queue entry to get from |
|---|---|
| Return | Last Key value from queue or QUEUE_KEY_NONE on failure |
function QueueInsertKey(Queue:TQueueHandle; Thread:TThreadHandle; Key:Integer):LongWord;
Description: Insert the supplied thread in the Queue ordered based on Key and the flags of the Queue
| Queue | Handle of Queue entry to insert into |
|---|---|
| Thread | Handle of thread to be inserted |
| Key | The key to order the insertion on |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If queue is a scheduler queue then caller must hold the lock on the thread} |
function QueueDeleteKey(Queue:TQueueHandle; Thread:TThreadHandle):LongWord;
Description: Delete the supplied thread from the Queue based on the flags of the Queue
| Queue | Handle of Queue entry to delete from |
|---|---|
| Thread | Handle of thread to be deleted |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | If queue is a scheduler queue then caller must hold the lock on the thread |
function QueueIncrementKey(Queue:TQueueHandle):Integer;
Description: Increment the first Key value in the Queue
| Queue | Handle of Queue entry to increment in |
|---|---|
| Return | First Key value in queue after increment or QUEUE_KEY_NONE on failure |
function QueueDecrementKey(Queue:TQueueHandle):Integer;
Description: Decrement the first Key value in the Queue
| Queue | Handle of Queue entry to decrement in |
|---|---|
| Return | First Key value in queue after decrement or QUEUE_KEY_NONE on failure |
function QueueIsEmpty(Queue:TQueueHandle):Boolean;
Description: Check if the supplied Queue is empty
| Queue | Handle of Queue entry to check |
|---|---|
| Return | True if Queue is empty or does not exist, False if Queue is not empty |
function QueueNotEmpty(Queue:TQueueHandle):Boolean;
Description: Check if the supplied Queue is not empty
| Queue | Handle of Queue entry to check |
|---|---|
| Return | True if Queue is not empty, False if Queue is empty or does not exist |
function QueueLock(Queue:TQueueHandle):LongWord; {$IFDEF QUEUE_INLINE}inline; {$ENDIF}
Description: Lock the supplied Queue
| Queue | Handle of Queue entry to lock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function QueueUnlock(Queue:TQueueHandle):LongWord; {$IFDEF QUEUE_INLINE}inline; {$ENDIF}
Description: Unlock the supplied Queue
| Queue | Handle of Queue entry to unlock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
Thread functions
function ThreadCreate(StartProc:TThreadStart; StackSize,Priority:LongWord; Name:PChar; Parameter:Pointer):TThreadHandle;
Description: Create and insert a new Thread entry
| StartProc | Procedure address where the thread will start running |
|---|---|
| StackSize | Stack size in bytes |
| Priority | Thread priority (eg THREAD_PRIORITY_NORMAL) |
| Name | To be documented |
| Parameter | Parameter passed to StartProc of new thread |
| Return | Handle of new thread or INVALID_HANDLE_VALUE if a new thread could not be created |
| Note | The new thread will be created suspended so it will not start running until it is scheduled with either ThreadReady or ThreadResume. Calls ThreadCreateEx with: Affinity = SCHEDULER_CPU_MASK (Run on any available CPU) CPU = SchedulerThreadNext (Assign to next CPU in round robin). |
| Warning | ThreadCreate and ThreadCreateEx are only used internally by SysBeginThread and SysBeginThreadEx. These functions do not handle setting up certain RTL functionality such as thread variables, exceptions and standard input/output handles. If you need to create a standard thread use either BeginThread (or BeginThreadEx) or use the TThread class and its descendants. Only use ThreadCreate and ThreadCreateEx if you need to modify the thread creation behaviour and understand that you also need to handle the additional RTL setup. |
function ThreadCreateEx(StartProc:TThreadStart; StackSize,Priority,Affinity,CPU:LongWord; Name:PChar; Parameter:Pointer):TThreadHandle;
Description: Create and insert a new Thread entry
| StartProc | Procedure address where the thread will start running |
|---|---|
| StackSize | Stack size in bytes |
| Priority | Thread priority (eg THREAD_PRIORITY_NORMAL) |
| Affinity | Thread affinity (eg CPU_AFFINITY_ALL) |
| CPU | The CPU to assign new thread to (eg ) |
| Name | Name of the thread |
| Parameter | Parameter passed to StartProc of new thread |
| Return | Handle of new thread or INVALID_HANDLE_VALUE if a new thread could not be created |
| Note | The new thread will be created suspended so it will not start running until it is scheduled with either ThreadReady or ThreadResume. |
| Warning | ThreadCreate and ThreadCreateEx are only used internally by SysBeginThread and SysBeginThreadEx. These functions do not handle setting up certain RTL functionality such as thread variables, exceptions and standard input/output handles. If you need to create a standard thread use either BeginThread (or BeginThreadEx) or use the TThread class or its descendants. Only use ThreadCreate and ThreadCreateEx if you need to modify the thread creation behaviour and understand that you also need to handle the additional RTL setup |
function ThreadDestroy(Thread:TThreadHandle):LongWord;
Description: Destroy and remove an existing Thread entry
| Thread | Handle of thread to destroy |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function ThreadGetCurrent:TThreadHandle; inline;
Description: Get the Handle of currently executing thread
| Return | Thread handle of the currently running thread |
|---|
function ThreadSetCurrent(Thread:TThreadHandle):LongWord; inline;
Description: Set the Handle of currently executing thread
| Return | ERROR_SUCCESS if completed or another error code on failure |
|---|---|
| Note | Must not be called except during initialization |
function ThreadGetName(Thread:TThreadHandle):String;
Description: Get the name of a Thread}
| Thread | Handle of thread to get |
|---|---|
| Return | Name of thread or empty string on failure |
function ThreadSetName(Thread:TThreadHandle; const Name:String):LongWord;
Description: Set the name of a Thread
| Thread | Handle of thread to set |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function ThreadGetCPU(Thread:TThreadHandle):LongWord;
Description: Get the current CPU of a thread (eg CPU_ID_0)
| Thread | Handle of thread to get |
|---|---|
| Return | CPU of the thread or INVALID_HANDLE_VALUE on failure |
function ThreadSetCPU(Thread:TThreadHandle; CPU:LongWord):LongWord;
Description: Set the current CPU of a thread (eg CPU_ID_0)
| Thread | Handle of thread to set |
|---|---|
| CPU | New thread CPU (eg CPU_ID_0) |
| Return | Previous CPU of thread or INVALID_HANDLE_VALUE on failure |
| Note | The new CPU will not take affect until the thread is next rescheduled |
function ThreadGetState(Thread:TThreadHandle):LongWord;
Description: Get the current state of a thread (eg THREAD_STATE_SUSPENDED)
| Thread | Handle of thread to get |
|---|---|
| Return | State of the thread or INVALID_HANDLE_VALUE on failure |
function ThreadGetLocale(Thread:TThreadHandle):LCID;
Description: Get the current locale of a thread
| Thread | Handle of thread to get |
|---|---|
| Return | Locale of the thread or INVALID_HANDLE_VALUE on failure |
function ThreadSetLocale(Thread:TThreadHandle; Locale:LCID):LongWord;
Description: Set the locale of a thread
| Thread | Handle of thread to set |
|---|---|
| Locale | Locale id to set |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function ThreadGetTimes(Thread:TThreadHandle; var CreateTime,ExitTime,KernelTime:Int64):LongWord;
Description: Get the current times of a thread
| Thread | Handle of thread to get |
|---|---|
| CreateTime | Buffer to receive the CreateTime value |
| ExitTime | Buffer to receive the ExitTime value |
| KernelTime | Buffer to receive the KernelTime value |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function ThreadGetSwitchCount(Thread:TThreadHandle; var SwitchCount:Int64):LongWord;
Description: Get the current context switch count of a thread (How many times the thread has been scheduled)
| Thread | Handle of thread to get |
|---|---|
| SwitchCount | Buffer to receive the SwitchCount value |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function ThreadGetStackSize(Thread:TThreadHandle):LongWord;
Description: Get the current stack size of a thread
| Thread | Handle of thread to get |
|---|---|
| Return | Stack size of the thread or INVALID_HANDLE_VALUE on failure |
function ThreadGetStackBase(Thread:TThreadHandle):PtrUInt;
Description: Get the current stack base of a thread
| Thread | Handle of thread to get |
|---|---|
| Return | Stack base of the thread or INVALID_HANDLE_VALUE on failure |
function ThreadSetStackBase(Thread:TThreadHandle; StackBase:PtrUInt):LongWord;
Description: Set the current stack base of a thread
| Thread | Handle of thread to set |
|---|---|
| StackBase | Stack base to set |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Must not be called except during initialization |
function ThreadGetStackPointer(Thread:TThreadHandle):PtrUInt;
Description: Get the current stack pointer of a thread
| Thread | Handle of thread to get |
|---|---|
| Return | Stack pointer of the thread or INVALID_HANDLE_VALUE on failure |
function ThreadGetExitCode(Thread:TThreadHandle):LongWord;
Description: Get the exit code of a Thread
| Thread | Handle of thread to get |
|---|---|
| Return | Exit code of thread, STILL_ACTIVE if the thread has not terminated or INVALID_HANDLE_VALUE on failure |
function ThreadGetAffinity(Thread:TThreadHandle):LongWord;
Description: Get the scheduling affinity of a Thread
| Thread | Handle of thread to get |
|---|---|
| Return | Affinity of thread or INVALID_HANDLE_VALUE on failure |
function ThreadSetAffinity(Thread:TThreadHandle; Affinity:LongWord):LongWord;
Description: Set the scheduling affinity of a Thread
| Thread | Handle of thread to set |
|---|---|
| Affinity | New thread affinity (eg CPU_AFFINITY_0) |
| Return | Previous affinity of thread or INVALID_HANDLE_VALUE on failure |
| Note | The new affinity will not take affect until the thread is next rescheduled |
function ThreadGetPriority(Thread:TThreadHandle):LongWord;
Description: Get the scheduling priority of a Thread
| Thread | Handle of thread to get |
|---|---|
| Return | Priority of thread or INVALID_HANDLE_VALUE on failure |
function ThreadSetPriority(Thread:TThreadHandle; Priority:LongWord):LongWord;
Description: Set the scheduling priority of a Thread
| Thread | Handle of thread to set |
|---|---|
| Priority | New thread priority (eg THREAD_PRIORITY_NORMAL) |
| Return | Previous priority of thread or INVALID_HANDLE_VALUE on failure |
| Note | The new priority will not take affect until the thread is next rescheduled |
function ThreadGetLastError:LongWord;
Description: Get the last error value for the current Thread
| Return | Last Error of thread or ERROR_SUCCESS if no error |
|---|---|
| Note | No lock required as only ever called by the thread itself |
function ThreadSetLastError(LastError:LongWord):LongWord;
Description: Set the last error value for the current Thread
| Return | ERROR_SUCCESS if completed or another error code on failure |
|---|---|
| Note | No lock required as only ever called by the thread itself |
function ThreadGetWaitResult:LongWord;
Description: Get the result of the last wait timeout for the current Thread
| Return | Result of last wait timeout or ERROR_SUCCESS if no error |
|---|---|
| Note | No lock required as only ever called by the thread itself |
function ThreadGetReceiveResult:LongWord;
Description: Get the result of the last receive timeout for the current Thread
| Return | Result of last receive timeout or ERROR_SUCCESS if no error |
|---|---|
| Note | No lock required as only ever called by the thread itself |
function ThreadAllocTlsIndex:LongWord;
Description: Allocate a TLS index in the TLS index table
| Return | Allocated TLS index or TLS_OUT_OF_INDEXES on failure |
|---|
function ThreadAllocTlsIndexEx(Flags:LongWord):LongWord;
Description: Allocate a TLS index in the TLS index table
| Flags | The flags to apply to the TLS index entries (eg THREAD_TLS_FLAG_FREE) |
|---|---|
| Return | Allocated TLS index or TLS_OUT_OF_INDEXES on failure |
function ThreadReleaseTlsIndex(TlsIndex:LongWord):LongWord;
Description: Deallocate a TLS index from the TLS index table
| TlsIndex | The TLS index to deallocate |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function ThreadGetTlsValue(TlsIndex:LongWord):Pointer;
Description: Get the pointer associated with the TLS index for the current thread
| Return | Pointer for the specified TLS index or nil if not set or on error |
|---|---|
| Note | No lock required as only ever called by the thread itself |
function ThreadSetTlsValue(TlsIndex:LongWord; TlsValue:Pointer):LongWord;
Description: Set the pointer associated with the TLS index for the current thread
| TlsIndex | The TLS index to get the pointer for |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | No lock required as only ever called by the thread itself |
function ThreadGetTlsPointer(Thread:TThreadHandle):Pointer;
Description: Get the RTL TLS (Thread Local Storage) pointer of a Thread
| Thread | Handle of thread to get |
|---|---|
| Return | Pointer to the RTL TLS of thread or nil on failure |
function ThreadSetTlsPointer(Thread:TThreadHandle; TlsPointer:Pointer):LongWord;
Description: Set the RTL TLS (Thread Local Storage) pointer of a Thread
| Thread | Handle of thread to set |
|---|---|
| TlsPointer | Pointer value to set (Can be nil to clear the pointer) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function ThreadReady(Thread:TThreadHandle; Reschedule:Boolean):LongWord;
Description: Place the supplied Thread on the ready queue
| Thread | Handle of thread to make ready |
|---|---|
| Reschedule | If True then call SchedulerReschedule |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | When called by the scheduler, thread has already been removed from the sleep queue |
function ThreadTimeout(Thread:TThreadHandle):LongWord;
Description: Place the supplied Thread on the ready queue after a timeout waiting on a resource
| Thread | Handle of thread to make ready |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | When called by the scheduler, thread has already been removed from the timeout queue |
function ThreadWake(Thread:TThreadHandle):LongWord;
Description: Remove a thread prematurely from the sleep or timeout queues
| Thread | Handle of thread to remove |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | A thread that was sleeping will simply return early. A thread that was waiting or receiving with a timeout will return with the error WAIT_TIMEOUT. A thread that was waiting or receiving with INFINITE timeout will return with the error WAIT_ABANDONED. |
function ThreadMigrate(Thread:TThreadHandle; CPU:LongWord):LongWord;
Description: Migrate a thread to a new CPU
| Thread | Handle of thread to migrate |
|---|---|
| CPU | New CPU for the thread |
| Return | Previous CPU of thread or INVALID_HANDLE_VALUE on failure |
procedure ThreadEnd(ExitCode:LongWord);
Description: Terminate the current Thread
| ExitCode | The return code of the thread |
|---|
function ThreadHalt(ExitCode:LongWord):LongWord;
Description: Halt the current thread so it will never be rescheduled
| ExitCode | The return code of the thread |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Normally only called due to an unhandled exception etc so that the thread is put to sleep permanently without being terminated |
function ThreadTerminate(Thread:TThreadHandle; ExitCode:LongWord):LongWord;
Description: Terminate but do not destroy the supplied Thread
| Thread | Handle of thread to terminate |
|---|---|
| ExitCode | The return code of the thread |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | The terminated thread is placed on the termination queue until any threads waiting on it have been released |
function ThreadYield:LongWord;
Description: Make the current thread yield the processor (Same as ThreadSleep(0))
| Return | ERROR_SUCCESS if completed or another error code on failure |
|---|
function ThreadSleep(Milliseconds:LongWord):LongWord;
Description: Place the current thread on the sleep queue for a specified number of milliseconds
| Return | ERROR_SUCCESS if completed or another error code on failure |
|---|---|
| Note | Milliseconds: Number of milliseconds to sleep |
function ThreadWait(List:TListHandle; Lock:TSpinHandle; Flags:LongWord):LongWord;
Description: Put the current thread into a wait state on the supplied list
| List | Handle of List entry to put thread into |
|---|---|
| Lock | Handle of Lock to release before going into wait state |
| Flags | Flag to indicate which unlock method to use |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Caller must hold the lock on the synchronisation object containing the list |
function ThreadWaitEx(List:TListHandle; Lock:TSpinHandle; Flags,Timeout:LongWord):LongWord;
Description: Put the current thread into a wait state with timeout on the supplied list
| List | Handle of List entry to put thread into |
|---|---|
| Lock | Handle of Lock to release before going into wait state |
| Flags | Flag to indicate which unlock method to use |
| Timeout | Milliseconds to wait before timeout (INFINITE equals wait forever) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Caller must hold the lock on the synchronisation object containing the list |
function ThreadRelease(List:TListHandle):LongWord;
Description: Release the first thread waiting on the supplied list
| List | Handle of List entry to release thread from |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Caller must hold the lock on the synchronisation object containing the list |
function ThreadAbandon(List:TListHandle):LongWord;
Description: Release the first thread waiting on the supplied list and return with WAIT_ABANDONED
| List | Handle of List entry to release thread from |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Caller must hold the lock on the synchronisation object containing the list |
function ThreadWaitTerminate(Thread:TThreadHandle; Timeout:LongWord):LongWord;
Description: Make the current thread wait until the specified thread has terminated
| Thread | Handle of the thread to wait on |
|---|---|
| Timeout | Milliseconds to wait before timeout (0 equals do not wait, INFINITE equals wait forever) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | The wait can be abandoned by calling ThreadWake with the handle of the waiting thread |
function ThreadSuspend(Thread:TThreadHandle):LongWord;
Description: Suspend a thread, placing it in hibernation
| Thread | Handle of thread to suspend |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Suspending a thread from another thread is not safe unless specific precautions are taken to prevent deadlocks. It is normally safe for a thread to suspend itself as long as it releases any locks it is holding that may be required by other threads before suspending. |
function ThreadResume(Thread:TThreadHandle):LongWord;
Description: Resume a suspended thread, making it ready
| Thread | Handle of thread to resume |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function ThreadWaitMessage:LongWord;
Description: Make the current thread wait until a message is received (indefinately)
| Return | ERROR_SUCCESS if completed or another error code on failure |
|---|---|
| Note | The received message is not removed from the message list |
function ThreadSendMessage(Thread:TThreadHandle; const Message:TMessage):LongWord;
Description: Send a message to another thread
| Thread | Handle of thread to send to |
|---|---|
| Message | Contents of message to send |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function ThreadReceiveMessage(var Message:TMessage):LongWord;
Description: Make the current thread wait to receive a message (indefinately)
| Message | The received message if successful, undefined on error |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function ThreadReceiveMessageEx(var Message:TMessage; Timeout:LongWord; Remove:Boolean):LongWord;
Description: Make the current thread wait to receive a message
| Message | The received message if successful, undefined on error |
|---|---|
| Timeout | Milliseconds to wait before timeout (0 equals do not wait, INFINITE equals wait forever) |
| Remove | If true then remove the received message from the message list |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function ThreadAbandonMessage(Thread:TThreadHandle):LongWord;
Description: Tell another thread to abandon waiting for a message
| Thread | Handle of thread to abandon waiting |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | The waiting thread will return with ERROR_WAIT_ABANDONED or ERROR_WAIT_TIMEOUT |
function ThreadLock(Thread:TThreadHandle):LongWord;
Description: Lock a thread allowing access to internal structures such as the thread stack
| Thread | Handle of thread to lock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Locking a thread will also disable IRQ or FIQ depending on scheduler settings. The lock should only be held for the briefest time possible. |
function ThreadUnlock(Thread:TThreadHandle):LongWord;
Description: Unlock a thread that was locked by ThreadLock
| Thread | Handle of thread to unlock |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Locking a thread will also disable IRQ or FIQ depending on scheduler settings. The lock should only be held for the briefest time possible. |
Scheduler functions
function SchedulerCheck(CPUID:LongWord):LongWord;
Description: Check if the sleep queue is empty, if not then decrement the first key. Note: Then check if the timeout queue is empty, if not then decrement the first key. If either key reaches zero, return success to indicate there are threads to be woken or threads whose timeout has expired. Finally check if the termination queue is empty, if not then decrement the first key. Items will be removed from the termination queue by SchedulerReschedule.
| CPUID | The ID of the current CPU |
|---|---|
| Return | ERROR_SUCCESS if either first key is zero, ERROR_NO_MORE_ITEMS if both queues are empty or another error code on failure |
| Note | Called by scheduler interrupt with IRQ or FIQ disabled and running on the IRQ or FIQ thread |
function SchedulerWakeup(CPUID:LongWord):LongWord;
Description: Remove all threads from the sleep queue that have no more time to sleep. Note: Threads will be placed back on the ready queue for rescheduling.
| CPUID | The ID of the current CPU |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Called by scheduler interrupt with IRQ or FIQ disabled and running on the IRQ or FIQ thread |
function SchedulerExpire(CPUID:LongWord):LongWord;
Description: Remove all threads from the timeout queue that have no more time to wait. Note: Threads will be placed back on the ready queue for rescheduling but will return with an error indicating the timeout expired.
| CPUID | The ID of the current CPU |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Called by scheduler interrupt with IRQ or FIQ disabled and running on the IRQ or FIQ thread |
function SchedulerSwitch(CPUID:LongWord; Thread:TThreadHandle):TThreadHandle;
Description: Perform a preemptive thread switch operation under an interrupt handler. Note: The next thread to run will be selected based on remaining quantum of the current thread, ready threads at higher priority levels and scheduler priority quantum for fair scheduling of lower priority threads.
| CPUID | The ID of the current CPU |
|---|---|
| Thread | The handle of the currently running thread (Before IRQ or FIQ occurred) |
| Return | The handle of the current thread which may be the old thread or a new thread |
| Note | Called by scheduler interrupt with IRQ or FIQ disabled and running on the IRQ or FIQ thread |
function SchedulerSelect(CPUID:LongWord; Thread:TThreadHandle; Yield:Boolean):TThreadHandle;
Description: Select the next thread to be run based on state, yield, quantum and priority
| CPUID | The ID of the current CPU |
|---|---|
| Thread | The handle of the currently running thread (Before IRQ or FIQ occurred or when Reschedule was called) |
| Yield | True if the current thread is giving up its remaining time slice |
| Return | The handle of the next thread to run or INVALID_HANDLE_VALUE on no selection or error |
| Note | Called either by scheduler interrupt with IRQ or FIQ disabled and running on the IRQ or FIQ thread. Or by scheduler reschedule with IRQ or FIQ disabled and running on the current thread. Caller must either hold a lock on the current thread or have disabled IRQ or FIQ. |
function SchedulerReschedule(Yield:Boolean):LongWord;
Description: Perform a thread switch operation when a thread yields, sleeps or waits. Note: The next thread to run will be selected based on whether the current thread is yielding or no longer ready, remaining quantum of the current thread, ready threads at higher priority levels and scheduler priority quantum for fair scheduling of lower priority threads.
| Yield | True if the current thread is giving up its remaining time slice |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
| Note | Called by the currently running thread to force a reschedule before sleeping, waiting etc |
function SchedulerMigrationEnable:LongWord;
Description: Enable scheduler thread migration
| Return | ERROR_SUCCESS if completed or another error code on failure |
|---|
function SchedulerMigrationDisable:LongWord;
Description: Disable scheduler thread migration
| Return | ERROR_SUCCESS if completed or another error code on failure |
|---|
function SchedulerPreemptEnable(CPUID:LongWord):LongWord;
Description: Enable thread preemption for the specified CPU
| CPUID | The ID of the CPU to enable for |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SchedulerPreemptDisable(CPUID:LongWord):LongWord;
Description: Disable thread preemption for the specified CPU
| CPUID | The ID of the CPU to disable for |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SchedulerAllocationEnable(CPUID:LongWord):LongWord;
Description: Enable thread allocation for the specified CPU
| CPUID | The ID of the CPU to enable for |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function SchedulerAllocationDisable(CPUID:LongWord):LongWord;
Description: Disable thread allocation for the specified CPU
| CPUID | The ID of the CPU to disable for |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
Messageslot functions
function MessageslotCreate:TMessageslotHandle;
Description: Create and insert a new Messageslot entry
| Return | Handle of new Messageslot entry or INVALID_HANDLE_VALUE if entry could not be created |
|---|
function MessageslotCreateEx(Maximum:LongWord; Flags:LongWord):TMessageslotHandle;
Description: Create and insert a new Messageslot entry
| Maximum | Maximum number of messages allowed for the Messageslot (Must be greater than zero) |
|---|---|
| Flags | The flags for the Messageslot entry (eg MESSAGESLOT_FLAG_IRQ) |
| Return | Handle of new Messageslot entry or INVALID_HANDLE_VALUE if entry could not be created |
function MessageslotDestroy(Messageslot:TMessageslotHandle):LongWord;
Description: Destroy and remove an existing Messageslot entry
| Messageslot | Handle of Messageslot entry to destroy |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MessageslotCount(Messageslot:TMessageslotHandle):LongWord;
Description: Get the number of available messages in a Messageslot entry
| Messageslot | Messageslot to get from |
|---|---|
| Return | Number of messages or INVALID_HANDLE_VALUE on error |
function MessageslotSend(Messageslot:TMessageslotHandle; const Message:TMessage):LongWord;
Description: Send a message to a Messageslot
| Messageslot | Messageslot to send to |
|---|---|
| Message | Contents of message to send |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MessageslotReceive(Messageslot:TMessageslotHandle; var Message:TMessage):LongWord;
Description: Receive a message from a Messageslot
| Messageslot | Messageslot to receive from |
|---|---|
| Message | The received message if successful, undefined on error |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MessageslotReceiveEx(Messageslot:TMessageslotHandle; var Message:TMessage; Timeout:LongWord):LongWord;
Description: Receive a message from a Messageslot
| Messageslot | Messageslot to receive from |
|---|---|
| Message | The received message if successful, undefined on error |
| Timeout | Milliseconds to wait before timeout (0 equals do not wait, INFINITE equals wait forever) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
Mailslot functions
function MailslotCreate(Maximum:LongWord):TMailslotHandle;
Description: Create and insert a new Mailslot entry
| Maximum | Maximum number of messages allowed for the Mailslot (Must be greater than zero) |
|---|---|
| Return | Handle of new Mailslot entry or INVALID_HANDLE_VALUE if entry could not be created |
function MailslotDestroy(Mailslot:TMailslotHandle):LongWord;
Description: Destroy and remove an existing Mailslot entry
| Mailslot | Handle of Mailslot entry to destroy |
|---|---|
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MailslotCount(Mailslot:TMailslotHandle):LongWord;
Description: Get the number of available messages in a Mailslot entry
| Mailslot | Mailslot to get from |
|---|---|
| Return | Number of messages or INVALID_HANDLE_VALUE on error |
function MailslotSend(Mailslot:TMailslotHandle; Data:Integer):LongWord;
Description: Send a message to a Mailslot
| Mailslot | Mailslot to send to |
|---|---|
| Data | Message to send to mailslot |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MailslotSendEx(Mailslot:TMailslotHandle; Data:Integer; Timeout:LongWord):LongWord;
Description: Send a message to a Mailslot
| Mailslot | Mailslot to send to |
|---|---|
| Data | Message to send to mailslot |
| Timeout | Milliseconds to wait before timeout (0 equals do not wait, INFINITE equals wait forever) |
| Return | ERROR_SUCCESS if completed or another error code on failure |
function MailslotReceive(Mailslot:TMailslotHandle):Integer;
Description: Receive a message from a Mailslot
| Mailslot | Mailslot to receive from |
|---|---|
| Return | Received message or INVALID_HANDLE_VALUE on error |
Tasker functions
function TaskerThreadSendMessage(Thread:TThreadHandle; const Message:TMessage):LongWord;
Description: Perform a ThreadSendMessage() function call using the tasker list
| Note | None documented |
|---|
function TaskerMessageslotSend(Messageslot:TMessageslotHandle; const Message:TMessage):LongWord;
Description: Perform a MessageslotSend() function call using the tasker list
| Note | None documented |
|---|
function TaskerSemaphoreSignal(Semaphore:TSemaphoreHandle; Count:LongWord):LongWord;
Description: Perform a SemaphoreSignal() function call using the tasker list
| Note | None documented |
|---|
function TaskerEnqueue(Task:PTaskerTask):LongWord;
Description: Add the supplied task to the end of the Tasker list
| Return | ERROR_SUCCESS if completed or another error code on failure |
|---|
function TaskerDequeue:PTaskerTask;
Description: Get and remove the first task from the Tasker list
| Return | Dequeued Task or nil on failure (or list empty) |
|---|
function TaskerCheck:LongWord;
Description: Check if the tasker list is empty or contains tasks
| Return | ERROR_SUCCESS if the list contains tasks, ERROR_NO_MORE_ITEMS if list is empty or another error code on failure |
|---|---|
| Note | Called by clock interrupt with IRQ or FIQ disabled and running on the IRQ or FIQ thread |
function TaskerTrigger:LongWord;
Description: Dequeue all tasks in the tasker list and perform the requested task for each
| Return | ERROR_SUCCESS if completed or another error code on failure |
|---|---|
| Note | Called by clock interrupt with IRQ or FIQ disabled and running on the IRQ or FIQ thread |
function TaskerGetCount:LongWord; inline;
Description: Get the current tasker count
| Note | None documented |
|---|
Return to Unit Reference
