VxWorks Reference Manual : Libraries
semLib - general semaphore library
semGive( ) - give a semaphore
semTake( ) - take a semaphore
semFlush( ) - unblock every task pended on a semaphore
semDelete( ) - delete a semaphore
Semaphores are the basis for synchronization and mutual exclusion in VxWorks. They are powerful in their simplicity and form the foundation for numerous VxWorks facilities.
Different semaphore types serve different needs, and while the behavior of the types differs, their basic interface is the same. This library provides semaphore routines common to all VxWorks semaphore types. For all types, the two basic operations are semTake( ) and semGive( ), the acquisition or relinquishing of a semaphore.
Semaphore creation and initialization is handled by other libraries, depending on the type of semaphore used. These libraries contain full functional descriptions of the semaphore types:
semBLib - binary semaphores
semCLib - counting semaphores
semMLib - mutual exclusion semaphores
semSmLib - shared memory semaphoresBinary semaphores offer the greatest speed and the broadest applicability.
The semLib library provides all other semaphore operations, including routines for semaphore control, deletion, and information. Semaphores must be validated before any semaphore operation can be undertaken. An invalid semaphore ID results in ERROR, and an appropriate errno is set.
The semTake( ) call acquires a specified semaphore, blocking the calling task or making the semaphore unavailable. All semaphore types support a timeout on the semTake( ) operation. The timeout is specified as the number of ticks to remain blocked on the semaphore. Timeouts of WAIT_FOREVER and NO_WAIT codify common timeouts. If a semTake( ) times out, it returns ERROR. Refer to the library of the specific semaphore type for the exact behavior of this operation.
The semGive( ) call relinquishes a specified semaphore, unblocking a pended task or making the semaphore available. Refer to the library of the specific semaphore type for the exact behavior of this operation.
The semFlush( ) call may be used to atomically unblock all tasks pended on a semaphore queue, i.e., all tasks will be unblocked before any are allowed to run. It may be thought of as a broadcast operation in synchronization applications. The state of the semaphore is unchanged by the use of semFlush( ); it is not analogous to semGive( ).
The semDelete( ) call terminates a semaphore and deallocates any associated memory. The deletion of a semaphore unblocks tasks pended on that semaphore; the routines which were pended return ERROR. Take care when deleting semaphores, particularly those used for mutual exclusion, to avoid deleting a semaphore out from under a task that already has taken (owns) that semaphore. Applications should adopt the protocol of only deleting semaphores that the deleting task has successfully taken.
The semInfo( ) call is a useful debugging aid, reporting all tasks blocked on a specified semaphore. It provides a snapshot of the queue at the time of the call, but because semaphores are dynamic, the information may be out of date by the time it is available. As with the current state of the semaphore, use of the queue of pended tasks should be restricted to debugging uses only.
semLib.h
semLib, taskLib, semBLib, semCLib, semMLib, semSmLib, VxWorks Programmer's Guide: Basic OS
semGive( ) - give a semaphore
STATUS semGive ( SEM_ID semId /* semaphore ID to give */ )
This routine performs the give operation on a specified semaphore. Depending on the type of semaphore, the state of the semaphore and of the pending tasks may be affected. The behavior of semGive( ) is discussed fully in the library description of the specific semaphore type being used.
OK, or ERROR if the semaphore ID is invalid.
S_intLib_NOT_ISR_CALLABLE, S_objLib_OBJ_ID_ERROR,
S_semLib_INVALID_OPERATION
semLib, semBLib, semCLib, semMLib, semSmLib
semTake( ) - take a semaphore
STATUS semTake ( SEM_ID semId, /* semaphore ID to take */ int timeout /* timeout in ticks */ )
This routine performs the take operation on a specified semaphore. Depending on the type of semaphore, the state of the semaphore and the calling task may be affected. The behavior of semTake( ) is discussed fully in the library description of the specific semaphore type being used.
A timeout in ticks may be specified. If a task times out, semTake( ) will return ERROR. Timeouts of WAIT_FOREVER (-1) and NO_WAIT (0) indicate to wait indefinitely or not to wait at all.
When semTake( ) returns due to timeout, it sets the errno to S_objLib_OBJ_TIMEOUT (defined in objLib.h).
The semTake( ) routine is not callable from interrupt service routines.
OK, or ERROR if the semaphore ID is invalid or the task timed out.
S_intLib_NOT_ISR_CALLABLE, S_objLib_OBJ_ID_ERROR,
S_objLib_OBJ_UNAVAILABLE
semLib, semBLib, semCLib, semMLib, semSmLib
semFlush( ) - unblock every task pended on a semaphore
STATUS semFlush ( SEM_ID semId /* semaphore ID to unblock everyone for */ )
This routine atomically unblocks all tasks pended on a specified semaphore, i.e., all tasks will be unblocked before any is allowed to run. The state of the underlying semaphore is unchanged. All pended tasks will enter the ready queue before having a chance to execute.
The flush operation is useful as a means of broadcast in synchronization applications. Its use is illegal for mutual-exclusion semaphores created with semMCreate( ).
OK, or ERROR if the semaphore ID is invalid or the operation is not supported.
S_objLib_OBJ_ID_ERROR
semLib, semBLib, semCLib, semMLib, semSmLib
semDelete( ) - delete a semaphore
STATUS semDelete ( SEM_ID semId /* semaphore ID to delete */ )
This routine terminates and deallocates any memory associated with a specified semaphore. Any pended tasks will unblock and return ERROR.
Take care when deleting semaphores, particularly those used for mutual exclusion, to avoid deleting a semaphore out from under a task that already has taken (owns) that semaphore. Applications should adopt the protocol of only deleting semaphores that the deleting task has successfully taken.
OK, or ERROR if the semaphore ID is invalid.
S_intLib_NOT_ISR_CALLABLE, S_objLib_OBJ_ID_ERROR,
S_smObjLib_NO_OBJECT_DESTROY