Difference between revisions of "Unit Threads"

Revision as of 02:23, 9 September 2016

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

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 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 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 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 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 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 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

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

Return to Unit Reference

@@ Line 2,670: / Line 2,670: @@
 ! '''Return'''
 | Handle of new Mailslot entry or INVALID_HANDLE_VALUE if entry could not be created
+|-
+|}
+</div></div>
+<br />
+<div class="toccolours mw-collapsible mw-collapsed" style="border: 1; font-family: arial; padding-top: 0px; padding-bottom: 15px;">
+<pre style="border: 0; padding-bottom:0px;">function MailslotDestroy(Mailslot:TMailslotHandle):LongWord;</pre>
+<div style="font-size: 14px; padding-left: 12px;">'''Description:''' Destroy and remove an existing Mailslot entry</div>
+<div class="mw-collapsible-content" style="text-align: left; padding-left: 5px;">
+{| class="wikitable" style="font-size: 14px; background: white;"
+|-
+! '''Mailslot'''
+| Handle of Mailslot entry to destroy
+|-
+! '''Return'''
+| ERROR_SUCCESS if completed or another error code on failure
 |-
 |}

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

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

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

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

Difference between revisions of "Unit Threads"

Revision as of 02:23, 9 September 2016

Contents

Description

Constants

Type definitions

Public variables

Function declarations

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools

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

Spin	Handle of Spin entry to destroy
Return	ERROR_SUCCESS if completed or another error code on failure

Spin	Handle of Spin entry to get owner for
Return	Handle of owning thread or INVALID_HANDLE_VALUE if not currently owned

Spin	Handle of Spin entry to lock
Return	ERROR_SUCCESS if completed or another error code on failure

Spin	Handle of Spin entry to unlock
Return	ERROR_SUCCESS if completed or another error code on failure