IoTivity-Lite
Protothread semaphores

This module implements counting semaphores on top of protothreads. More...

Files

file  pt-sem.h
 Counting semaphores implemented on protothreads.
 

Macros

#define PT_SEM_COUNT(s)   ((s)->head - (s)->tail)
 
#define PT_SEM_INIT(s, c)
 Initialize a semaphore. More...
 
#define PT_SEM_SIGNAL(pt, s)
 Signal a semaphore. More...
 
#define PT_SEM_WAIT(pt, s)
 Wait for a semaphore. More...
 

Detailed Description

This module implements counting semaphores on top of protothreads.

Semaphores are a synchronization primitive that provide two operations: "wait" and "signal". The "wait" operation checks the semaphore counter and blocks the thread if the counter is zero. The "signal" operation increases the semaphore counter but does not block. If another thread has blocked waiting for the semaphore that is signaled, the blocked thread will become runnable again.

Semaphores can be used to implement other, more structured, synchronization primitives such as monitors and message queues/bounded buffers (see below).

The following example shows how the producer-consumer problem, also known as the bounded buffer problem, can be solved using protothreads and semaphores. Notes on the program follow after the example.

#include "pt-sem.h"
#define NUM_ITEMS 32
#define BUFSIZE 8
static struct pt_sem mutex, full, empty;
PT_THREAD(producer(struct pt *pt))
{
static int produced;
PT_BEGIN(pt);
for(produced = 0; produced < NUM_ITEMS; ++produced) {
PT_SEM_WAIT(pt, &full);
PT_SEM_WAIT(pt, &mutex);
add_to_buffer(produce_item());
PT_SEM_SIGNAL(pt, &mutex);
PT_SEM_SIGNAL(pt, &empty);
}
PT_END(pt);
}
PT_THREAD(consumer(struct pt *pt))
{
static int consumed;
PT_BEGIN(pt);
for(consumed = 0; consumed < NUM_ITEMS; ++consumed) {
PT_SEM_WAIT(pt, &empty);
PT_SEM_WAIT(pt, &mutex);
consume_item(get_from_buffer());
PT_SEM_SIGNAL(pt, &mutex);
PT_SEM_SIGNAL(pt, &full);
}
PT_END(pt);
}
PT_THREAD(driver_thread(struct pt *pt))
{
static struct pt pt_producer, pt_consumer;
PT_BEGIN(pt);
PT_SEM_INIT(&empty, 0);
PT_SEM_INIT(&full, BUFSIZE);
PT_SEM_INIT(&mutex, 1);
PT_INIT(&pt_producer);
PT_INIT(&pt_consumer);
PT_WAIT_THREAD(pt, producer(&pt_producer) &
consumer(&pt_consumer));
PT_END(pt);
}
#define PT_WAIT_THREAD(pt, thread)
Block and wait until a child protothread completes.
Definition: pt.h:206
#define PT_BEGIN(pt)
Declare the start of a protothread inside the C function implementing the protothread.
Definition: pt.h:119
#define PT_THREAD(name_args)
Declaration of a protothread.
Definition: pt.h:104
#define PT_END(pt)
Declare the end of a protothread.
Definition: pt.h:137
#define PT_INIT(pt)
Initialize a protothread.
Definition: pt.h:84
#define PT_SEM_SIGNAL(pt, s)
Signal a semaphore.
Definition: pt-sem.h:232
#define PT_SEM_WAIT(pt, s)
Wait for a semaphore.
Definition: pt-sem.h:211
#define PT_SEM_INIT(s, c)
Initialize a semaphore.
Definition: pt-sem.h:189
Counting semaphores implemented on protothreads.

The program uses three protothreads: one protothread that implements the consumer, one thread that implements the producer, and one protothread that drives the two other protothreads. The program uses three semaphores: "full", "empty" and "mutex". The "mutex" semaphore is used to provide mutual exclusion for the buffer, the "empty" semaphore is used to block the consumer is the buffer is empty, and the "full" semaphore is used to block the producer is the buffer is full.

The "driver_thread" holds two protothread state variables, "pt_producer" and "pt_consumer". It is important to note that both these variables are declared as static. If the static keyword is not used, both variables are stored on the stack. Since protothreads do not store the stack, these variables may be overwritten during a protothread wait operation. Similarly, both the "consumer" and "producer" protothreads declare their local variables as static, to avoid them being stored on the stack.

Macro Definition Documentation

◆ PT_SEM_INIT

#define PT_SEM_INIT (   s,
 
)

Initialize a semaphore.

This macro initializes a semaphore with a value for the counter. Internally, the semaphores use an "unsigned int" to represent the counter, and therefore the "count" argument should be within range of an unsigned int.

Parameters
s(struct pt_sem *) A pointer to the pt_sem struct representing the semaphore
c(unsigned int) The initial count of the semaphore.

◆ PT_SEM_SIGNAL

#define PT_SEM_SIGNAL (   pt,
 
)

Signal a semaphore.

This macro carries out the "signal" operation on the semaphore. The signal operation increments the counter inside the semaphore, which eventually will cause waiting protothreads to continue executing.

Parameters
pt(struct pt *) A pointer to the protothread (struct pt) in which the operation is executed.
s(struct pt_sem *) A pointer to the pt_sem struct representing the semaphore

◆ PT_SEM_WAIT

#define PT_SEM_WAIT (   pt,
 
)

Wait for a semaphore.

This macro carries out the "wait" operation on the semaphore. The wait operation causes the protothread to block while the counter is zero. When the counter reaches a value larger than zero, the protothread will continue.

Parameters
pt(struct pt *) A pointer to the protothread (struct pt) in which the operation is executed.
s(struct pt_sem *) A pointer to the pt_sem struct representing the semaphore