VxWorks Reference Manual : Libraries
semCLib - counting semaphore library
semCCreate( ) - create and initialize a counting semaphore
This library provides the interface to VxWorks counting semaphores. Counting semaphores are useful for guarding multiple instances of a resource.
A counting semaphore may be viewed as a cell in memory whose contents keep track of a count. When a task takes a counting semaphore, using semTake( ), subsequent action depends on the state of the count:
- (1)
- If the count is non-zero, it is decremented and the calling task continues executing.
- (2)
- If the count is zero, the task will be blocked, pending the availability of the semaphore. If a timeout is specified and the timeout expires, the pended task will be removed from the queue of pended tasks and enter the ready state with an ERROR status. A pended task is ineligible for CPU allocation. Any number of tasks may be pended simultaneously on the same counting semaphore.
When a task gives a semaphore, using semGive( ), the next available task in the pend queue is unblocked. If no task is pending on this semaphore, the semaphore count is incremented. Note that if a semaphore is given, and a task is unblocked that is of higher priority than the task that called semGive( ), the unblocked task will preempt the calling task.
A semFlush( ) on a counting semaphore will atomically unblock all pended tasks in the semaphore queue. So all tasks will be made ready before any task actually executes. The count of the semaphore will remain unchanged.
Counting semaphores may be given but not taken from interrupt level.
There is no mechanism to give back or reclaim semaphores automatically when tasks are suspended or deleted. Such a mechanism, though desirable, is not currently feasible. Without explicit knowledge of the state of the guarded resource or region, reckless automatic reclamation of a semaphore could leave the resource in a partial state. Thus, if a task ceases execution unexpectedly, as with a bus error, currently owned semaphores will not be given back, effectively leaving a resource permanently unavailable. The mutual-exclusion semaphores provided by semMLib offer protection from unexpected task deletion.
semLib.h
semCLib, semLib, semBLib, semMLib, VxWorks Programmer's Guide: Basic OS
semCCreate( ) - create and initialize a counting semaphore
SEM_ID semCCreate ( int options, /* semaphore option modes */ int initialCount /* initial count */ )
This routine allocates and initializes a counting semaphore. The semaphore is initialized to the specified initial count.
The options parameter specifies the queuing style for blocked tasks. Tasks may be queued on a priority basis or a first-in-first-out basis. These options are SEM_Q_PRIORITY (0x1) and SEM_Q_FIFO (0x0), respectively.
The semaphore ID, or NULL if memory cannot be allocated.