Click here for the API Reference documentation.

Creating a Semaphore
Using a Semaphore
Deleting a Semaphore
Diagnostics

This API provides standard semaphore functionality, but with added diagnostic capabilities. These semaphores can only be shared by threads within the same process.

Two kinds of semaphore are supported by Legato:

Normal
Traceable

Normal semaphores are faster than traceable semaphores and consume less memory, but still offer some diagnosic capabilities. Traceable semaphores generally behave the same as Normal sempahores, but can also log their activities.

All semaphores can wait (decrease value by one) and post (increase value by one). The same wait, post, and delete functions work for all the semaphores, regardless of what type they are. This means that a semaphore can be changed from Normal to Traceable or vice versa just by changing the function you use to create it. This helps when troubleshooting race conditions or deadlocks because it's easy to switch one semaphore or a select few semaphores to Traceable, without suffering the runtime cost of switching all semaphores to the slower Traceable semaphores.

Creating a Semaphore

In Legato, semaphores are dynamically allocated objects. Functions that create them return references to them (of type le_sem_Ref_t). The functions for creating semaphores are:

le_sem_Create() - creates a normal, semaphore.
le_sem_CreateTraceable() - creates a traceable, semaphore.

Note that all semaphores have names. This is required for diagnostic purposes. See Diagnostics below.

Using a Semaphore

Functions to increase and decrease semaphores are:

Function to get semaphores values is:

le_sem_GetValue()

It doesn't matter what type of semaphore you are using, you still use the same functions for increasing, decreasing, getting value your semaphore.

Deleting a Semaphore

When you are finished with a semaphore, you must delete it by calling le_sem_Delete().

There must not be anything using the semaphore when it is deleted (i.e., no one can be waiting on it).

Diagnostics

Both Normal and Traceable semaphores have some diagnostics capabilities.

The command-line diagnostic tool lssemaphore can be used to list the semaphores that currently exist inside a given process. The state of each semaphore can be seen, including a list of any threads that might be waiting for that semaphore.

The tool threadlook will show if a given thread is currently waiting for a semaphore, and will name that semaphore.

If there are Traceable semaphores in a process, then it will be possible to use the log tool to enable or disable tracing on that semaphore. The trace keyword name is the name of the process, the name of the component, and the name of the semaphore, separated by slashes (e.g., "process/component/semaphore").