VxWorks API Reference : OS Libraries

semLib

NAME

semLib - general semaphore library

ROUTINES

semGive( ) - give a semaphore
semTake( ) - take a semaphore
semFlush( ) - unblock every task pended on a semaphore
semDelete( ) - delete a semaphore

DESCRIPTION

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 semaphores

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

SEMAPHORE CONTROL

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( ).

SEMAPHORE DELETION

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.

SEMAPHORE INFORMATION

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.

VXWORKS EVENTS

If a task has registered for receiving events with a semaphore, events will be sent when that semaphore becomes available. By becoming available, it is implied that there is a change of state. For a binary semaphore, there is only a change of state when a semGive( ) is done on a semaphore that was taken. For a counting semaphore, there is always a change of state when the semaphore is available, since the count is incremented each time. For a mutex, a semGive( ) can only be performed if the current task is the owner, implying that the semaphore has been taken; thus, there is always a change of state.

INCLUDE FILES

semLib.h

SEE ALSO

taskLib, semBLib, semCLib, semMLib, semSmLib, semEvLib, eventLib, VxWorks Programmer's Guide: Basic OS


OS Libraries : Routines

semGive( )

NAME

semGive( ) - give a semaphore

SYNOPSIS

STATUS semGive
    (
    SEM_ID semId              /* semaphore ID to give */
    )

DESCRIPTION

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. If no tasks are pending on the sempahore and a task has previously registered to receive events from the semaphore, these events are sent in the context of this call. This may result in the unpending of the task waiting for the events. If the semaphore fails to send events and if it was created using the SEM_EVENTSEND_ERR_NOTIFY option, ERROR is returned even though the give operation was successful. The behavior of semGive( ) is discussed fully in the library description of the specific semaphore type being used.

RETURNS

OK on success or ERROR otherwise

ERRNO

S_intLib_NOT_ISR_CALLABLE
Routine was called from an ISR for a mutex semaphore.
S_objLib_OBJ_ID_ERROR
Semaphore ID is invalid.
S_semLib_INVALID_OPERATION
Current task not owner of mutex semaphore.
S_eventLib_EVENTSEND_FAILED
Semaphore failed to send events to the registered task. This errno value can only exist if the semaphore was created with the SEM_EVENTSEND_ERR_NOTIFY option.

SEE ALSO

semLib, semBLib, semCLib, semMLib, semSmLib, semEvStart


OS Libraries : Routines

semTake( )

NAME

semTake( ) - take a semaphore

SYNOPSIS

STATUS semTake
    (
    SEM_ID semId,             /* semaphore ID to take */
    int    timeout            /* timeout in ticks */
    )

DESCRIPTION

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.

RETURNS

OK, or ERROR if the semaphore ID is invalid or the task timed out.

ERRNO

S_intLib_NOT_ISR_CALLABLE, S_objLib_OBJ_ID_ERROR,
       S_objLib_OBJ_UNAVAILABLE

SEE ALSO

semLib, semBLib, semCLib, semMLib, semSmLib


OS Libraries : Routines

semFlush( )

NAME

semFlush( ) - unblock every task pended on a semaphore

SYNOPSIS

STATUS semFlush
    (
    SEM_ID semId              /* semaphore ID to unblock everyone for */
    )

DESCRIPTION

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( ).

RETURNS

OK, or ERROR if the semaphore ID is invalid or the operation is not supported.

ERRNO

S_objLib_OBJ_ID_ERROR

SEE ALSO

semLib, semBLib, semCLib, semMLib, semSmLib


OS Libraries : Routines

semDelete( )

NAME

semDelete( ) - delete a semaphore

SYNOPSIS

STATUS semDelete
    (
    SEM_ID semId              /* semaphore ID to delete */
    )

DESCRIPTION

This routine terminates and deallocates any memory associated with a specified semaphore. All tasks pending on the semaphore or pending for the reception of events meant to be sent from the semaphore will unblock and return ERROR.

WARNING

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.

RETURNS

OK, or ERROR if the semaphore ID is invalid.

ERRNO

S_intLib_NOT_ISR_CALLABLE
Routine cannot be called from ISR.
S_objLib_OBJ_ID_ERROR
Semaphore ID is invalid.
S_smObjLib_NO_OBJECT_DESTROY
Deleting a shared semaphore is not permitted

SEE ALSO

semLib, semBLib, semCLib, semMLib, semSmLib