Semaphores

A semaphore is a synchronization object that limits the number of threads that can concurrently access a resource.

Anytime that a thread successfully acquires the semaphore using SEMAPHORE_Acquire(), its count is decremented by one. If the semaphore's count is zero when a thread attempts to acquire the semaphore, the calling thread will be blocked until the semaphore's count is incremented using SEMAPHORE_Release().

Unlike the mutex, a semaphore does not have the notion of an owner thread. Without an owner, any thread can release a semaphore, even if it is different than the thread that originally acquired the semaphore.

Basic Usage

The code snippet below demonstrates how to allocate and create a counting semaphore.

#include "Kernel/kernel_semaphore.h"
#include <assert.h>

static SEMAPHORE sem1;                      /* Allocate a semaphore */

void APP_Example(void)
{
    STATUS status;


    status = SEMAPHORE_Create(&sem1,        /* A pointer to the allocated semaphore to be created */
                              "Semaphore1", /* A name for the semaphore (debugging purposes) */
                              0,            /* The initial count for the semaphore */
                              10);          /* The maximum allowable count for the semaphore */

    assert(status == SUCCESS);
}

One of the typical uses of a counting semaphore is to use the semaphore to signal a thread each time an event has occurred. The semaphore can keep a count of events that are pending to be processed by the thread. The thread can then be notified of each event to be processed.

The code snippet below has an event handler that releases the semaphore each time that the event occurred which releases the thread that is blocked upon the semaphore. For each time the semaphore is released, the thread will successfully acquire the semaphore and the event can be processed (and counted). Note the semaphore was created with a maximum count of '10', which for this example means that only up to '10' events can be pending to be processed before the events will be dropped and not processed by the thread.

#include "Kernel/kernel_semaphore.h"
#include <assert.h>

void EventHandler(void)
{
    STATUS status;


    status = SEMAPHORE_Release(&sem1, 1);   /* Release the semaphore once per event */
    assert(status == SUCCESS);
}

void ExampleThread(void* arg)
{
    UINT32 count = 0;
    STATUS status;


    for(;;) {

        status = SEMAPHORE_Acquire(&sem1, INFINITE);    /* Wait until event handler releases semaphore */
        if (status == SUCCESS) {                        /* Was the semaphore successfully acquired? */
			
            ProcessEvent();                             /* Process the event */
            count++;                                    /* Keep count of events that have been processed */
        }
    }
}