Unit Threads
From Ultibo.org
Return to Unit Reference
Description
To be documented
Constants
To be documented
Type definitions
To be documented
Public variables
To be documented
Function declarations
Initialization functions
procedure LocksInit;
Description: Initialize Locks
| Note | To be documented |
|---|
procedure ThreadsInit;
Description: Initialize Threading
| Note | To be documented |
|---|
procedure PrimaryInit;
Description: Initialize the primary CPU
| Note | To be documented |
|---|
procedure SchedulerInit;
Description: Initialize the thread scheduler
| Note | To be documented |
|---|
procedure SchedulerStart(CPUID:LongWord);
Description: Initialize the thread scheduler for secondary CPUs (Where Applicable)
| Note | To be documented |
|---|
procedure SecondaryInit;
Description: Initialize the secondary CPUs (Where Applicable)
| Note | To be documented |
|---|
procedure SecondaryBoot(CPUID:LongWord);
Description: Boot the specified secondary CPU (Where Applicable)
| Note | To be 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 | To be documented |
|---|
function FIQExecute(Parameter:Pointer):PtrInt;
Description: To be documented
| Note | To be documented |
|---|
function SWIExecute(Parameter:Pointer):PtrInt;
Description: To be documented
| Note | To be documented |
|---|
function IdleExecute(Parameter:Pointer):PtrInt;
Description: To be documented
| Note | To be documented |
|---|
function MainExecute(Parameter:Pointer):PtrInt;
Description: To be documented
| Note | To be documented |
|---|
function TimerExecute(Parameter:Pointer):PtrInt;
Description: To be documented
| Note | To be documented |
|---|
function WorkerExecute(Parameter:Pointer):PtrInt;
Description: To be documented
| Note | To be documented |
|---|
function IdleCalibrate:LongWord;
Description: Calibrate the idle thread loop by counting the number of loops in 100ms
| Note | To be documented |
|---|
Spin functions
function SpinCreate:TSpinHandle;
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;
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;
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;
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;
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;
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;
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;
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;
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 |
Mutex functions
function MutexCreate:TMutexHandle;
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 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 MutexLock(Mutex:TMutexHandle):LongWord;
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;
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;
Description: Try to lock an existing Mutex entry
| Mutex | Mutex to try to lock |
|---|---|
| Return | ERROR_SUCCESS if completed, ERROR_LOCKED if already locked or another error code on failure |
| Note | 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. |
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;
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 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 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 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 |
Queue functions
function QueueCreate:TQueueHandle;
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 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 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 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;
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;
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 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 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 |
Return to Unit Reference
