Semaphore Examples

The following sections provides examples of typical semaphore use. For the full story on semaphores, see Semaphores.

Semaphore Example 1: Locking

The most typical use of a semaphore is to protect a chunk of code that can only be executed by one thread at a time. The semaphore acts as a lock; acquire_sem() locks the code, release_sem() releases it. Semaphores that are used as locks are (almost always) created with a thread count of 1.

As a simple example, let's say you keep track of a maximum value like this:

/* max_val is a global. */ uint32 max_val = 0; ... /* bump_max() resets the max value, if necessary. */ void bump_max(uint32 new_value) {    if (new_value > max_value)       max_value = new_value; }

bump_max() isn't thread safe; there's a race condition between the comparison and the assignment. So we protect it with a semaphore:

sem_id max_sem; uint32 max_val = 0; ... /* Initialize the semaphore during a setup routine. */ status_t init() {    if ((max_sem = create_sem(1, "max_sem")) < B_NO_ERROR)       return B_ERROR;    ... } void bump_max(uint32 new_value) {    if (acquire_sem(max_sem) != B_NO_ERROR)       return;    if (new_value > max_value)       max_value = new_value;    release_sem(); }

Semaphore Example 2: Benaphores

A "benaphore" is a combination of an atomic variable and a semaphore that can improve locking efficiency. If you're using a semaphore as shown in the previous example, you should consider using a benaphore instead (if you can).

Here's the example re-written to use a benaphore:

sem_id max_sem; uint32 max_val = 0; int32 ben_val = 0; status_t init() {    /* This time we initialized the semaphore to 0. */    if ((max_sem = create_sem(0, "max_sem")) < B_NO_ERROR)       return B_ERROR;    ... } void bump_max(uint32 new_value) {    int32 previous = atomic_add(&ben_val, 1);    if (previous >= 1)       if (acquire_sem(max_sem) != B_NO_ERROR)          goto get_out;    if (new_value > max_value)       max_value = new_value; get_out:    previous = atomic_add(&ben_val, -1);    if (previous > 1)       release_sem(max_sem); }

The point, here, is that acquire_sem() is called only if it's known (by checking the previous value of ben_val) that some other thread is in the middle of the critical section. On the releasing end, the release_sem() is called only if some other thread has since entered the function (and is now blocked in the acquire_sem() call). An important point, here, is that the semaphore is initialized to 0.

Semaphore Example 3: Imposing an Execution Order

Semaphores can also be used to coordinate threads that are performing separate operations, but that need to perform these operations in a particular order. In the following example, we have a global buffer that's accessed through separate reading and writing functions. Furthermore, we want writes and reads to alternate, with a write going first.

We can lock the entire buffer with a single semaphore, but to enforce alternation we need two semaphores:

sem_id write_sem, read_sem; char buffer[1024]; /* Initialize the semaphores */ status_t init() {    if ((write_sem = create_sem(1, "write")) < B_NO_ERROR) {       return;    if ((read_sem = create_sem(0, "read")) < B_NO_ERROR) {       delete_sem(write_sem);       return;    } } status_t write_buffer(const char *src) {    if (acquire_sem(write_sem) != B_NO_ERROR)       return B_ERROR;    strncpy(buffer, src, 1024);    release_sem(read_sem); } status_t read_buffer(char *dest, size_t len) {    if (acquire_sem(read_sem) != B_NO_ERROR)       return B_ERROR;    strncpy(dest, buffer, len);    release_sem(write_sem); }

The initial thread counts ensure that the buffer will be written to before it's read: If a reader arrives before a writer, the reader will block until the writer releases the read_sem semaphore.