manu jose / Mbed 2 deprecated proto_thread

4. An implementation of the system as thread(s) written in protothread style, plus additional code that monitors the serial port and touch sensors, and dispatches them to the threads.

Dependencies:   mbed

pt-sem.h@0:3667ad9a98cc, 2010-11-30 (annotated)

Committer:
manujose
Date:
Tue Nov 30 22:02:03 2010 +0000
Revision:
0:3667ad9a98cc
protothreads

Who changed what in which revision?

UserRevisionLine numberNew contents of line
manujose 0:3667ad9a98cc 1 /*
manujose 0:3667ad9a98cc 2 * Copyright (c) 2004, Swedish Institute of Computer Science.
manujose 0:3667ad9a98cc 3 * All rights reserved.
manujose 0:3667ad9a98cc 4 *
manujose 0:3667ad9a98cc 5 * Redistribution and use in source and binary forms, with or without
manujose 0:3667ad9a98cc 6 * modification, are permitted provided that the following conditions
manujose 0:3667ad9a98cc 7 * are met:
manujose 0:3667ad9a98cc 8 * 1. Redistributions of source code must retain the above copyright
manujose 0:3667ad9a98cc 9 * notice, this list of conditions and the following disclaimer.
manujose 0:3667ad9a98cc 10 * 2. Redistributions in binary form must reproduce the above copyright
manujose 0:3667ad9a98cc 11 * notice, this list of conditions and the following disclaimer in the
manujose 0:3667ad9a98cc 12 * documentation and/or other materials provided with the distribution.
manujose 0:3667ad9a98cc 13 * 3. Neither the name of the Institute nor the names of its contributors
manujose 0:3667ad9a98cc 14 * may be used to endorse or promote products derived from this software
manujose 0:3667ad9a98cc 15 * without specific prior written permission.
manujose 0:3667ad9a98cc 16 *
manujose 0:3667ad9a98cc 17 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
manujose 0:3667ad9a98cc 18 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
manujose 0:3667ad9a98cc 19 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
manujose 0:3667ad9a98cc 20 * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
manujose 0:3667ad9a98cc 21 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
manujose 0:3667ad9a98cc 22 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
manujose 0:3667ad9a98cc 23 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
manujose 0:3667ad9a98cc 24 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
manujose 0:3667ad9a98cc 25 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
manujose 0:3667ad9a98cc 26 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
manujose 0:3667ad9a98cc 27 * SUCH DAMAGE.
manujose 0:3667ad9a98cc 28 *
manujose 0:3667ad9a98cc 29 * This file is part of the protothreads library.
manujose 0:3667ad9a98cc 30 *
manujose 0:3667ad9a98cc 31 * Author: Adam Dunkels <adam@sics.se>
manujose 0:3667ad9a98cc 32 *
manujose 0:3667ad9a98cc 33 * $Id: pt-sem.h,v 1.2 2005/02/24 10:36:59 adam Exp $
manujose 0:3667ad9a98cc 34 */
manujose 0:3667ad9a98cc 35
manujose 0:3667ad9a98cc 36 /**
manujose 0:3667ad9a98cc 37 * \addtogroup pt
manujose 0:3667ad9a98cc 38 * @{
manujose 0:3667ad9a98cc 39 */
manujose 0:3667ad9a98cc 40
manujose 0:3667ad9a98cc 41 /**
manujose 0:3667ad9a98cc 42 * \defgroup ptsem Protothread semaphores
manujose 0:3667ad9a98cc 43 * @{
manujose 0:3667ad9a98cc 44 *
manujose 0:3667ad9a98cc 45 * This module implements counting semaphores on top of
manujose 0:3667ad9a98cc 46 * protothreads. Semaphores are a synchronization primitive that
manujose 0:3667ad9a98cc 47 * provide two operations: "wait" and "signal". The "wait" operation
manujose 0:3667ad9a98cc 48 * checks the semaphore counter and blocks the thread if the counter
manujose 0:3667ad9a98cc 49 * is zero. The "signal" operation increases the semaphore counter but
manujose 0:3667ad9a98cc 50 * does not block. If another thread has blocked waiting for the
manujose 0:3667ad9a98cc 51 * semaphore that is signalled, the blocked thread will become
manujose 0:3667ad9a98cc 52 * runnable again.
manujose 0:3667ad9a98cc 53 *
manujose 0:3667ad9a98cc 54 * Semaphores can be used to implement other, more structured,
manujose 0:3667ad9a98cc 55 * synchronization primitives such as monitors and message
manujose 0:3667ad9a98cc 56 * queues/bounded buffers (see below).
manujose 0:3667ad9a98cc 57 *
manujose 0:3667ad9a98cc 58 * The following example shows how the producer-consumer problem, also
manujose 0:3667ad9a98cc 59 * known as the bounded buffer problem, can be solved using
manujose 0:3667ad9a98cc 60 * protothreads and semaphores. Notes on the program follow after the
manujose 0:3667ad9a98cc 61 * example.
manujose 0:3667ad9a98cc 62 *
manujose 0:3667ad9a98cc 63 \code
manujose 0:3667ad9a98cc 64 #include "pt-sem.h"
manujose 0:3667ad9a98cc 65
manujose 0:3667ad9a98cc 66 #define NUM_ITEMS 32
manujose 0:3667ad9a98cc 67 #define BUFSIZE 8
manujose 0:3667ad9a98cc 68
manujose 0:3667ad9a98cc 69 static struct pt_sem mutex, full, empty;
manujose 0:3667ad9a98cc 70
manujose 0:3667ad9a98cc 71 PT_THREAD(producer(struct pt *pt))
manujose 0:3667ad9a98cc 72 {
manujose 0:3667ad9a98cc 73 static int produced;
manujose 0:3667ad9a98cc 74
manujose 0:3667ad9a98cc 75 PT_BEGIN(pt);
manujose 0:3667ad9a98cc 76
manujose 0:3667ad9a98cc 77 for(produced = 0; produced < NUM_ITEMS; ++produced) {
manujose 0:3667ad9a98cc 78
manujose 0:3667ad9a98cc 79 PT_SEM_WAIT(pt, &full);
manujose 0:3667ad9a98cc 80
manujose 0:3667ad9a98cc 81 PT_SEM_WAIT(pt, &mutex);
manujose 0:3667ad9a98cc 82 add_to_buffer(produce_item());
manujose 0:3667ad9a98cc 83 PT_SEM_SIGNAL(pt, &mutex);
manujose 0:3667ad9a98cc 84
manujose 0:3667ad9a98cc 85 PT_SEM_SIGNAL(pt, &empty);
manujose 0:3667ad9a98cc 86 }
manujose 0:3667ad9a98cc 87
manujose 0:3667ad9a98cc 88 PT_END(pt);
manujose 0:3667ad9a98cc 89 }
manujose 0:3667ad9a98cc 90
manujose 0:3667ad9a98cc 91 PT_THREAD(consumer(struct pt *pt))
manujose 0:3667ad9a98cc 92 {
manujose 0:3667ad9a98cc 93 static int consumed;
manujose 0:3667ad9a98cc 94
manujose 0:3667ad9a98cc 95 PT_BEGIN(pt);
manujose 0:3667ad9a98cc 96
manujose 0:3667ad9a98cc 97 for(consumed = 0; consumed < NUM_ITEMS; ++consumed) {
manujose 0:3667ad9a98cc 98
manujose 0:3667ad9a98cc 99 PT_SEM_WAIT(pt, &empty);
manujose 0:3667ad9a98cc 100
manujose 0:3667ad9a98cc 101 PT_SEM_WAIT(pt, &mutex);
manujose 0:3667ad9a98cc 102 consume_item(get_from_buffer());
manujose 0:3667ad9a98cc 103 PT_SEM_SIGNAL(pt, &mutex);
manujose 0:3667ad9a98cc 104
manujose 0:3667ad9a98cc 105 PT_SEM_SIGNAL(pt, &full);
manujose 0:3667ad9a98cc 106 }
manujose 0:3667ad9a98cc 107
manujose 0:3667ad9a98cc 108 PT_END(pt);
manujose 0:3667ad9a98cc 109 }
manujose 0:3667ad9a98cc 110
manujose 0:3667ad9a98cc 111 PT_THREAD(driver_thread(struct pt *pt))
manujose 0:3667ad9a98cc 112 {
manujose 0:3667ad9a98cc 113 static struct pt pt_producer, pt_consumer;
manujose 0:3667ad9a98cc 114
manujose 0:3667ad9a98cc 115 PT_BEGIN(pt);
manujose 0:3667ad9a98cc 116
manujose 0:3667ad9a98cc 117 PT_SEM_INIT(&empty, 0);
manujose 0:3667ad9a98cc 118 PT_SEM_INIT(&full, BUFSIZE);
manujose 0:3667ad9a98cc 119 PT_SEM_INIT(&mutex, 1);
manujose 0:3667ad9a98cc 120
manujose 0:3667ad9a98cc 121 PT_INIT(&pt_producer);
manujose 0:3667ad9a98cc 122 PT_INIT(&pt_consumer);
manujose 0:3667ad9a98cc 123
manujose 0:3667ad9a98cc 124 PT_WAIT_THREAD(pt, producer(&pt_producer) &
manujose 0:3667ad9a98cc 125 consumer(&pt_consumer));
manujose 0:3667ad9a98cc 126
manujose 0:3667ad9a98cc 127 PT_END(pt);
manujose 0:3667ad9a98cc 128 }
manujose 0:3667ad9a98cc 129 \endcode
manujose 0:3667ad9a98cc 130 *
manujose 0:3667ad9a98cc 131 * The program uses three protothreads: one protothread that
manujose 0:3667ad9a98cc 132 * implements the consumer, one thread that implements the producer,
manujose 0:3667ad9a98cc 133 * and one protothread that drives the two other protothreads. The
manujose 0:3667ad9a98cc 134 * program uses three semaphores: "full", "empty" and "mutex". The
manujose 0:3667ad9a98cc 135 * "mutex" semaphore is used to provide mutual exclusion for the
manujose 0:3667ad9a98cc 136 * buffer, the "empty" semaphore is used to block the consumer is the
manujose 0:3667ad9a98cc 137 * buffer is empty, and the "full" semaphore is used to block the
manujose 0:3667ad9a98cc 138 * producer is the buffer is full.
manujose 0:3667ad9a98cc 139 *
manujose 0:3667ad9a98cc 140 * The "driver_thread" holds two protothread state variables,
manujose 0:3667ad9a98cc 141 * "pt_producer" and "pt_consumer". It is important to note that both
manujose 0:3667ad9a98cc 142 * these variables are declared as <i>static</i>. If the static
manujose 0:3667ad9a98cc 143 * keyword is not used, both variables are stored on the stack. Since
manujose 0:3667ad9a98cc 144 * protothreads do not store the stack, these variables may be
manujose 0:3667ad9a98cc 145 * overwritten during a protothread wait operation. Similarly, both
manujose 0:3667ad9a98cc 146 * the "consumer" and "producer" protothreads declare their local
manujose 0:3667ad9a98cc 147 * variables as static, to avoid them being stored on the stack.
manujose 0:3667ad9a98cc 148 *
manujose 0:3667ad9a98cc 149 *
manujose 0:3667ad9a98cc 150 */
manujose 0:3667ad9a98cc 151
manujose 0:3667ad9a98cc 152 /**
manujose 0:3667ad9a98cc 153 * \file
manujose 0:3667ad9a98cc 154 * Couting semaphores implemented on protothreads
manujose 0:3667ad9a98cc 155 * \author
manujose 0:3667ad9a98cc 156 * Adam Dunkels <adam@sics.se>
manujose 0:3667ad9a98cc 157 *
manujose 0:3667ad9a98cc 158 */
manujose 0:3667ad9a98cc 159
manujose 0:3667ad9a98cc 160 #ifndef __PT_SEM_H__
manujose 0:3667ad9a98cc 161 #define __PT_SEM_H__
manujose 0:3667ad9a98cc 162
manujose 0:3667ad9a98cc 163 #include "pt.h"
manujose 0:3667ad9a98cc 164
manujose 0:3667ad9a98cc 165 struct pt_sem {
manujose 0:3667ad9a98cc 166 unsigned int count;
manujose 0:3667ad9a98cc 167 };
manujose 0:3667ad9a98cc 168
manujose 0:3667ad9a98cc 169 /**
manujose 0:3667ad9a98cc 170 * Initialize a semaphore
manujose 0:3667ad9a98cc 171 *
manujose 0:3667ad9a98cc 172 * This macro initializes a semaphore with a value for the
manujose 0:3667ad9a98cc 173 * counter. Internally, the semaphores use an "unsigned int" to
manujose 0:3667ad9a98cc 174 * represent the counter, and therefore the "count" argument should be
manujose 0:3667ad9a98cc 175 * within range of an unsigned int.
manujose 0:3667ad9a98cc 176 *
manujose 0:3667ad9a98cc 177 * \param s (struct pt_sem *) A pointer to the pt_sem struct
manujose 0:3667ad9a98cc 178 * representing the semaphore
manujose 0:3667ad9a98cc 179 *
manujose 0:3667ad9a98cc 180 * \param c (unsigned int) The initial count of the semaphore.
manujose 0:3667ad9a98cc 181 * \hideinitializer
manujose 0:3667ad9a98cc 182 */
manujose 0:3667ad9a98cc 183 #define PT_SEM_INIT(s, c) (s)->count = c
manujose 0:3667ad9a98cc 184
manujose 0:3667ad9a98cc 185 /**
manujose 0:3667ad9a98cc 186 * Wait for a semaphore
manujose 0:3667ad9a98cc 187 *
manujose 0:3667ad9a98cc 188 * This macro carries out the "wait" operation on the semaphore. The
manujose 0:3667ad9a98cc 189 * wait operation causes the protothread to block while the counter is
manujose 0:3667ad9a98cc 190 * zero. When the counter reaches a value larger than zero, the
manujose 0:3667ad9a98cc 191 * protothread will continue.
manujose 0:3667ad9a98cc 192 *
manujose 0:3667ad9a98cc 193 * \param pt (struct pt *) A pointer to the protothread (struct pt) in
manujose 0:3667ad9a98cc 194 * which the operation is executed.
manujose 0:3667ad9a98cc 195 *
manujose 0:3667ad9a98cc 196 * \param s (struct pt_sem *) A pointer to the pt_sem struct
manujose 0:3667ad9a98cc 197 * representing the semaphore
manujose 0:3667ad9a98cc 198 *
manujose 0:3667ad9a98cc 199 * \hideinitializer
manujose 0:3667ad9a98cc 200 */
manujose 0:3667ad9a98cc 201 #define PT_SEM_WAIT(pt, s) \
manujose 0:3667ad9a98cc 202 do { \
manujose 0:3667ad9a98cc 203 PT_WAIT_UNTIL(pt, (s)->count > 0); \
manujose 0:3667ad9a98cc 204 --(s)->count; \
manujose 0:3667ad9a98cc 205 } while(0)
manujose 0:3667ad9a98cc 206
manujose 0:3667ad9a98cc 207 /**
manujose 0:3667ad9a98cc 208 * Signal a semaphore
manujose 0:3667ad9a98cc 209 *
manujose 0:3667ad9a98cc 210 * This macro carries out the "signal" operation on the semaphore. The
manujose 0:3667ad9a98cc 211 * signal operation increments the counter inside the semaphore, which
manujose 0:3667ad9a98cc 212 * eventually will cause waiting protothreads to continue executing.
manujose 0:3667ad9a98cc 213 *
manujose 0:3667ad9a98cc 214 * \param pt (struct pt *) A pointer to the protothread (struct pt) in
manujose 0:3667ad9a98cc 215 * which the operation is executed.
manujose 0:3667ad9a98cc 216 *
manujose 0:3667ad9a98cc 217 * \param s (struct pt_sem *) A pointer to the pt_sem struct
manujose 0:3667ad9a98cc 218 * representing the semaphore
manujose 0:3667ad9a98cc 219 *
manujose 0:3667ad9a98cc 220 * \hideinitializer
manujose 0:3667ad9a98cc 221 */
manujose 0:3667ad9a98cc 222 #define PT_SEM_SIGNAL(pt, s) ++(s)->count
manujose 0:3667ad9a98cc 223
manujose 0:3667ad9a98cc 224 #endif /* __PT_SEM_H__ */
manujose 0:3667ad9a98cc 225
manujose 0:3667ad9a98cc 226 /** @} */
manujose 0:3667ad9a98cc 227 /** @} */
manujose 0:3667ad9a98cc 228