Difference between revisions of "Unit Threads"

From Ultibo.org
Jump to: navigation, search
Line 23: Line 23:
 
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.
 
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:'''  
+
'''''Usage:'''''  
 
                
 
                
 
''Create/Destroy''
 
''Create/Destroy''

Revision as of 05:24, 30 November 2016

Return to Unit Reference


Description

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

Retrieved from "https://ultibo.org/mediawiki_ultibo_org/index.php?title=Unit_Threads&oldid=1828"