TSCreateSemaphore()
Syntax
TSCreateSemaphore(type, maximum_count, initial_count)
Description
This command creates a semaphore object for inter-thread synchronisation and communication. A semaphore is a very basic object, but gives you very useful abilities when trying to control your threads. The simplest way to think about a semaphore is to imagine a flag. The flag can either be raised (available) or lowered (unavailable). If you want access to the semaphore you have to ask for it. If the semaphore is available then you will get it and the semaphore becomes unavailable. If the semaphore is unavailable your thread will be suspended and only woken up when the semaphore is available. It is also possible that one semaphore object is available more than once (think of lots of flags on the same flagpole :).
In this library, a simple semaphore (sometimes called a counting semaphore) is one which is available once or more (at the same time). Every time a thread gets the semaphore, the availability is decreased by one. When the availability is zero, threads that ask for the semaphore are suspended until it becomes available. When the semaphore is put back the availability is increased by one, up to the maximum availability. The operation of this type of semaphore is implemented completely by the OS.
A complex semaphore type was specifically created for this library. Its purpose is to be a multiple-read, exclusive-write semaphore. Many threads can share read access to it (up to the maximum availability), but only one can have exclusive access to it (and not at the same time as any shared accesses). It is effectively like two semaphores, one for the shared access and one for the exclusive access. The exclusive access semaphore always has an availability of one. Both semaphores behave like the simple semaphore described above. The operation of this type of semaphore is built on top of the functions provided by the OS.
Paramaters:
type.l - The type of semaphore you want to create. This library offers you two types of semaphores, simple (specified using #TST_SIMPLE_SEMAPHORE) and complex (specified using #TST_COMPLEX_SEMAPHORE).
maximum_count.l - This parameter is the number of times you want the semaphore to be available at the same time (the number of flags on the flagpole if you like). This value must be more than 0.
initial_count.l - Set this value to the number of times you want the semaphore to be available when it is created. This value must be more than or equal to zero and less than or equal to maximum_count.
Return value:
The value returned by this command is a handle to the semaphore object which was created, or zero if it was failed to be created. You should use this handle when you use the other commands for dealing with this semaphore.
Advanced users only:
The value returned by this command is a pointer to the structure used to internally manage the semaphore objects in this library, or zero if it was failed to be created. The structure of this piece of memory is either a TSSemaphore or TSComplexSemaphore, depending on what type of semaphore was created. Both are defined in the ThreadSync resident, but are here for explanation:
Example:
See also: TSGetSemaphore() , TSGetExclusiveSemaphore() , TSDestroySemaphore()
Supported OS
Windows