- Main Page
- Modules
- Data Structures
- Files

- File List
- Globals

# pt.h

Go to the documentation of this file.

    00001 /*
    00002  * Copyright (c) 2004-2005, Swedish Institute of Computer Science.
    00003  * All rights reserved.
    00004  *
    00005  * Redistribution and use in source and binary forms, with or without
    00006  * modification, are permitted provided that the following conditions
    00007  * are met:
    00008  * 1. Redistributions of source code must retain the above copyright
    00009  *    notice, this list of conditions and the following disclaimer.
    00010  * 2. Redistributions in binary form must reproduce the above copyright
    00011  *    notice, this list of conditions and the following disclaimer in the
    00012  *    documentation and/or other materials provided with the distribution.
    00013  * 3. Neither the name of the Institute nor the names of its contributors
    00014  *    may be used to endorse or promote products derived from this software
    00015  *    without specific prior written permission.
    00016  *
    00017  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
    00018  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    00019  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    00020  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
    00021  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    00022  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
    00023  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    00024  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    00025  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
    00026  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    00027  * SUCH DAMAGE.
    00028  *
    00029  * This file is part of the Contiki operating system.
    00030  *
    00031  * Author: Adam Dunkels <adam@sics.se>
    00032  *
    00033  * $Id: pt.h,v 1.7 2006/10/02 07:52:56 adam Exp $
    00034  */
    00035
    00036 /**
    00037  * \addtogroup pt
    00038  * @{
    00039  */
    00040
    00041 /**
    00042  * \file
    00043  * Protothreads implementation.
    00044  * \author
    00045  * Adam Dunkels <adam@sics.se>
    00046  *
    00047  */
    00048
    00049 #ifndef __PT_H__
    00050 #define __PT_H__
    00051
    00052 #include "lc.h"
    00053
    00054 struct pt {
    00055   lc_t lc;
    00056 };
    00057
    00058 #define PT_WAITING 0
    00059 #define PT_YIELDED 1
    00060 #define PT_EXITED  2
    00061 #define PT_ENDED   3
    00062
    00063 /**
    00064  * \name Initialization
    00065  * @{
    00066  */
    00067
    00068 /**
    00069  * Initialize a protothread.
    00070  *
    00071  * Initializes a protothread. Initialization must be done prior to
    00072  * starting to execute the protothread.
    00073  *
    00074  * \param pt A pointer to the protothread control structure.
    00075  *
    00076  * \sa PT_SPAWN()
    00077  *
    00078  * \hideinitializer
    00079  */
    00080 #define PT_INIT(pt)   LC_INIT((pt)->lc)
    00081
    00082 /** @} */
    00083
    00084 /**
    00085  * \name Declaration and definition
    00086  * @{
    00087  */
    00088
    00089 /**
    00090  * Declaration of a protothread.
    00091  *
    00092  * This macro is used to declare a protothread. All protothreads must
    00093  * be declared with this macro.
    00094  *
    00095  * \param name_args The name and arguments of the C function
    00096  * implementing the protothread.
    00097  *
    00098  * \hideinitializer
    00099  */
    00100 #define PT_THREAD(name_args) char name_args
    00101
    00102 /**
    00103  * Declare the start of a protothread inside the C function
    00104  * implementing the protothread.
    00105  *
    00106  * This macro is used to declare the starting point of a
    00107  * protothread. It should be placed at the start of the function in
    00108  * which the protothread runs. All C statements above the PT_BEGIN()
    00109  * invokation will be executed each time the protothread is scheduled.
    00110  *
    00111  * \param pt A pointer to the protothread control structure.
    00112  *
    00113  * \hideinitializer
    00114  */
    00115 #define PT_BEGIN(pt) { char PT_YIELD_FLAG = 1; LC_RESUME((pt)->lc)
    00116
    00117 /**
    00118  * Declare the end of a protothread.
    00119  *
    00120  * This macro is used for declaring that a protothread ends. It must
    00121  * always be used together with a matching PT_BEGIN() macro.
    00122  *
    00123  * \param pt A pointer to the protothread control structure.
    00124  *
    00125  * \hideinitializer
    00126  */
    00127 #define PT_END(pt) LC_END((pt)->lc); PT_YIELD_FLAG = 0; \
    00128                    PT_INIT(pt); return PT_ENDED; }
    00129
    00130 /** @} */
    00131
    00132 /**
    00133  * \name Blocked wait
    00134  * @{
    00135  */
    00136
    00137 /**
    00138  * Block and wait until condition is true.
    00139  *
    00140  * This macro blocks the protothread until the specified condition is
    00141  * true.
    00142  *
    00143  * \param pt A pointer to the protothread control structure.
    00144  * \param condition The condition.
    00145  *
    00146  * \hideinitializer
    00147  */
    00148 #define PT_WAIT_UNTIL(pt, condition)            \
    00149   do {                                          \
    00150     LC_SET((pt)->lc);                           \
    00151     if(!(condition)) {                          \
    00152       return PT_WAITING;                        \
    00153     }                                           \
    00154   } while(0)
    00155
    00156 /**
    00157  * Block and wait while condition is true.
    00158  *
    00159  * This function blocks and waits while condition is true. See
    00160  * PT_WAIT_UNTIL().
    00161  *
    00162  * \param pt A pointer to the protothread control structure.
    00163  * \param cond The condition.
    00164  *
    00165  * \hideinitializer
    00166  */
    00167 #define PT_WAIT_WHILE(pt, cond)  PT_WAIT_UNTIL((pt), !(cond))
    00168
    00169 /** @} */
    00170
    00171 /**
    00172  * \name Hierarchical protothreads
    00173  * @{
    00174  */
    00175
    00176 /**
    00177  * Block and wait until a child protothread completes.
    00178  *
    00179  * This macro schedules a child protothread. The current protothread
    00180  * will block until the child protothread completes.
    00181  *
    00182  * \note The child protothread must be manually initialized with the
    00183  * PT_INIT() function before this function is used.
    00184  *
    00185  * \param pt A pointer to the protothread control structure.
    00186  * \param thread The child protothread with arguments
    00187  *
    00188  * \sa PT_SPAWN()
    00189  *
    00190  * \hideinitializer
    00191  */
    00192 #define PT_WAIT_THREAD(pt, thread) PT_WAIT_WHILE((pt), PT_SCHEDULE(thread))
    00193
    00194 /**
    00195  * Spawn a child protothread and wait until it exits.
    00196  *
    00197  * This macro spawns a child protothread and waits until it exits. The
    00198  * macro can only be used within a protothread.
    00199  *
    00200  * \param pt A pointer to the protothread control structure.
    00201  * \param child A pointer to the child protothread's control structure.
    00202  * \param thread The child protothread with arguments
    00203  *
    00204  * \hideinitializer
    00205  */
    00206 #define PT_SPAWN(pt, child, thread)             \
    00207   do {                                          \
    00208     PT_INIT((child));                           \
    00209     PT_WAIT_THREAD((pt), (thread));             \
    00210   } while(0)
    00211
    00212 /** @} */
    00213
    00214 /**
    00215  * \name Exiting and restarting
    00216  * @{
    00217  */
    00218
    00219 /**
    00220  * Restart the protothread.
    00221  *
    00222  * This macro will block and cause the running protothread to restart
    00223  * its execution at the place of the PT_BEGIN() call.
    00224  *
    00225  * \param pt A pointer to the protothread control structure.
    00226  *
    00227  * \hideinitializer
    00228  */
    00229 #define PT_RESTART(pt)                          \
    00230   do {                                          \
    00231     PT_INIT(pt);                                \
    00232     return PT_WAITING;                  \
    00233   } while(0)
    00234
    00235 /**
    00236  * Exit the protothread.
    00237  *
    00238  * This macro causes the protothread to exit. If the protothread was
    00239  * spawned by another protothread, the parent protothread will become
    00240  * unblocked and can continue to run.
    00241  *
    00242  * \param pt A pointer to the protothread control structure.
    00243  *
    00244  * \hideinitializer
    00245  */
    00246 #define PT_EXIT(pt)                             \
    00247   do {                                          \
    00248     PT_INIT(pt);                                \
    00249     return PT_EXITED;                   \
    00250   } while(0)
    00251
    00252 /** @} */
    00253
    00254 /**
    00255  * \name Calling a protothread
    00256  * @{
    00257  */
    00258
    00259 /**
    00260  * Schedule a protothread.
    00261  *
    00262  * This function shedules a protothread. The return value of the
    00263  * function is non-zero if the protothread is running or zero if the
    00264  * protothread has exited.
    00265  *
    00266  * \param f The call to the C function implementing the protothread to
    00267  * be scheduled
    00268  *
    00269  * \hideinitializer
    00270  */
    00271 #define PT_SCHEDULE(f) ((f) < PT_EXITED)
    00272
    00273 /** @} */
    00274
    00275 /**
    00276  * \name Yielding from a protothread
    00277  * @{
    00278  */
    00279
    00280 /**
    00281  * Yield from the current protothread.
    00282  *
    00283  * This function will yield the protothread, thereby allowing other
    00284  * processing to take place in the system.
    00285  *
    00286  * \param pt A pointer to the protothread control structure.
    00287  *
    00288  * \hideinitializer
    00289  */
    00290 #define PT_YIELD(pt)                            \
    00291   do {                                          \
    00292     PT_YIELD_FLAG = 0;                          \
    00293     LC_SET((pt)->lc);                           \
    00294     if(PT_YIELD_FLAG == 0) {                    \
    00295       return PT_YIELDED;                        \
    00296     }                                           \
    00297   } while(0)
    00298
    00299 /**
    00300  * \brief      Yield from the protothread until a condition occurs.
    00301  * \param pt   A pointer to the protothread control structure.
    00302  * \param cond The condition.
    00303  *
    00304  *             This function will yield the protothread, until the
    00305  *             specified condition evaluates to true.
    00306  *
    00307  *
    00308  * \hideinitializer
    00309  */
    00310 #define PT_YIELD_UNTIL(pt, cond)                \
    00311   do {                                          \
    00312     PT_YIELD_FLAG = 0;                          \
    00313     LC_SET((pt)->lc);                           \
    00314     if((PT_YIELD_FLAG == 0) || !(cond)) {       \
    00315       return PT_YIELDED;                        \
    00316     }                                           \
    00317   } while(0)
    00318
    00319 /** @} */
    00320
    00321 #endif /* __PT_H__ */
    00322
    00323 /** @} */