From 3061ecca3d0fdfb87dabbf5f63c9e06c2a30f53a Mon Sep 17 00:00:00 2001 From: Trygve Laugstøl Date: Thu, 23 Aug 2018 17:08:59 +0200 Subject: o Initial import. --- .../protothreads/pt-1.4/doc/html/a00016.html | 246 +++++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 thirdparty/nRF5_SDK_15.0.0_a53641a/external/protothreads/pt-1.4/doc/html/a00016.html (limited to 'thirdparty/nRF5_SDK_15.0.0_a53641a/external/protothreads/pt-1.4/doc/html/a00016.html') diff --git a/thirdparty/nRF5_SDK_15.0.0_a53641a/external/protothreads/pt-1.4/doc/html/a00016.html b/thirdparty/nRF5_SDK_15.0.0_a53641a/external/protothreads/pt-1.4/doc/html/a00016.html new file mode 100644 index 0000000..743f2bd --- /dev/null +++ b/thirdparty/nRF5_SDK_15.0.0_a53641a/external/protothreads/pt-1.4/doc/html/a00016.html @@ -0,0 +1,246 @@ + + +The Protothreads Library 1.4: Protothread semaphores + + + + +
+
+

Protothread semaphores
+ +[Protothreads] +

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 signalled, 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);
+}
+

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

+ + + + + + + +

+

+ + + + + + + + + + + + +

Files

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

Data Structures

struct  pt_sem

Defines

#define PT_SEM_INIT(s, c)
 Initialize a semaphore.
#define PT_SEM_WAIT(pt, s)
 Wait for a semaphore.
#define PT_SEM_SIGNAL(pt, s)
 Signal a semaphore.
+

Define Documentation

+

+ + + + +
+ + + + + + + + + + + + +
#define PT_SEM_INIT ( s,
c   ) 
+
+ + + + + +
+   + + +

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

+Definition at line 183 of file pt-sem.h.

+

+ + + + +
+ + + + + + + + + + + + +
#define PT_SEM_SIGNAL ( pt,
s   ) 
+
+ + + + + +
+   + + +

+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
+
+ +

+Definition at line 222 of file pt-sem.h.

+

+ + + + +
+ + + + + + + + + + + + +
#define PT_SEM_WAIT ( pt,
s   ) 
+
+ + + + + +
+   + + +

+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
+
+ +

+Definition at line 201 of file pt-sem.h.

+

Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + -- cgit v1.2.3