[fnordlicht-mini] / firmware / common / pt / pt.h

/*
 * Copyright (c) 2004-2005, Swedish Institute of Computer Science.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of the Institute nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * This file is part of the Contiki operating system.
 *
 * Author: Adam Dunkels <adam@sics.se>
 *
 * $Id: pt.h,v 1.7 2006/10/02 07:52:56 adam Exp $
 */

/**
 * \addtogroup pt
 * @{
 */

/**
 * \file
 * Protothreads implementation.
 * \author
 * Adam Dunkels <adam@sics.se>
 *
 */

#ifndef __PT_H__
#define __PT_H__

#include "lc.h"

struct pt {
  lc_t lc;
};

#define PT_WAITING 0
#define PT_YIELDED 1
#define PT_EXITED  2
#define PT_ENDED   3

/**
 * \name Initialization
 * @{
 */

/**
 * Initialize a protothread.
 *
 * Initializes a protothread. Initialization must be done prior to
 * starting to execute the protothread.
 *
 * \param pt A pointer to the protothread control structure.
 *
 * \sa PT_SPAWN()
 *
 * \hideinitializer
 */
#define PT_INIT(pt)   LC_INIT((pt)->lc)

/** @} */

/**
 * \name Declaration and definition
 * @{
 */

/**
 * Declaration of a protothread.
 *
 * This macro is used to declare a protothread. All protothreads must
 * be declared with this macro.
 *
 * \param name_args The name and arguments of the C function
 * implementing the protothread.
 *
 * \hideinitializer
 */
#define PT_THREAD(name_args) char name_args

/**
 * Declare the start of a protothread inside the C function
 * implementing the protothread.
 *
 * This macro is used to declare the starting point of a
 * protothread. It should be placed at the start of the function in
 * which the protothread runs. All C statements above the PT_BEGIN()
 * invokation will be executed each time the protothread is scheduled.
 *
 * \param pt A pointer to the protothread control structure.
 *
 * \hideinitializer
 */
#define PT_BEGIN(pt) { char PT_YIELD_FLAG = 1; LC_RESUME((pt)->lc)

/**
 * Declare the end of a protothread.
 *
 * This macro is used for declaring that a protothread ends. It must
 * always be used together with a matching PT_BEGIN() macro.
 *
 * \param pt A pointer to the protothread control structure.
 *
 * \hideinitializer
 */
#define PT_END(pt) LC_END((pt)->lc); PT_YIELD_FLAG = 0; \
                   PT_INIT(pt); return PT_ENDED; }

/** @} */

/**
 * \name Blocked wait
 * @{
 */

/**
 * Block and wait until condition is true.
 *
 * This macro blocks the protothread until the specified condition is
 * true.
 *
 * \param pt A pointer to the protothread control structure.
 * \param condition The condition.
 *
 * \hideinitializer
 */
#define PT_WAIT_UNTIL(pt, condition)	        \
  do {						\
    LC_SET((pt)->lc);				\
    if(!(condition)) {				\
      return PT_WAITING;			\
    }						\
  } while(0)

/**
 * Block and wait while condition is true.
 *
 * This function blocks and waits while condition is true. See
 * PT_WAIT_UNTIL().
 *
 * \param pt A pointer to the protothread control structure.
 * \param cond The condition.
 *
 * \hideinitializer
 */
#define PT_WAIT_WHILE(pt, cond)  PT_WAIT_UNTIL((pt), !(cond))

/** @} */

/**
 * \name Hierarchical protothreads
 * @{
 */

/**
 * Block and wait until a child protothread completes.
 *
 * This macro schedules a child protothread. The current protothread
 * will block until the child protothread completes.
 *
 * \note The child protothread must be manually initialized with the
 * PT_INIT() function before this function is used.
 *
 * \param pt A pointer to the protothread control structure.
 * \param thread The child protothread with arguments
 *
 * \sa PT_SPAWN()
 *
 * \hideinitializer
 */
#define PT_WAIT_THREAD(pt, thread) PT_WAIT_WHILE((pt), PT_SCHEDULE(thread))

/**
 * Spawn a child protothread and wait until it exits.
 *
 * This macro spawns a child protothread and waits until it exits. The
 * macro can only be used within a protothread.
 *
 * \param pt A pointer to the protothread control structure.
 * \param child A pointer to the child protothread's control structure.
 * \param thread The child protothread with arguments
 *
 * \hideinitializer
 */
#define PT_SPAWN(pt, child, thread)		\
  do {						\
    PT_INIT((child));				\
    PT_WAIT_THREAD((pt), (thread));		\
  } while(0)

/** @} */

/**
 * \name Exiting and restarting
 * @{
 */

/**
 * Restart the protothread.
 *
 * This macro will block and cause the running protothread to restart
 * its execution at the place of the PT_BEGIN() call.
 *
 * \param pt A pointer to the protothread control structure.
 *
 * \hideinitializer
 */
#define PT_RESTART(pt)				\
  do {						\
    PT_INIT(pt);				\
    return PT_WAITING;			\
  } while(0)

/**
 * Exit the protothread.
 *
 * This macro causes the protothread to exit. If the protothread was
 * spawned by another protothread, the parent protothread will become
 * unblocked and can continue to run.
 *
 * \param pt A pointer to the protothread control structure.
 *
 * \hideinitializer
 */
#define PT_EXIT(pt)				\
  do {						\
    PT_INIT(pt);				\
    return PT_EXITED;			\
  } while(0)

/** @} */

/**
 * \name Calling a protothread
 * @{
 */

/**
 * Schedule a protothread.
 *
 * This function shedules a protothread. The return value of the
 * function is non-zero if the protothread is running or zero if the
 * protothread has exited.
 *
 * \param f The call to the C function implementing the protothread to
 * be scheduled
 *
 * \hideinitializer
 */
#define PT_SCHEDULE(f) ((f) < PT_EXITED)

/** @} */

/**
 * \name Yielding from a protothread
 * @{
 */

/**
 * Yield from the current protothread.
 *
 * This function will yield the protothread, thereby allowing other
 * processing to take place in the system.
 *
 * \param pt A pointer to the protothread control structure.
 *
 * \hideinitializer
 */
#define PT_YIELD(pt)				\
  do {						\
    PT_YIELD_FLAG = 0;				\
    LC_SET((pt)->lc);				\
    if(PT_YIELD_FLAG == 0) {			\
      return PT_YIELDED;			\
    }						\
  } while(0)

/**
 * \brief      Yield from the protothread until a condition occurs.
 * \param pt   A pointer to the protothread control structure.
 * \param cond The condition.
 *
 *             This function will yield the protothread, until the
 *             specified condition evaluates to true.
 *
 *
 * \hideinitializer
 */
#define PT_YIELD_UNTIL(pt, cond)		\
  do {						\
    PT_YIELD_FLAG = 0;				\
    LC_SET((pt)->lc);				\
    if((PT_YIELD_FLAG == 0) || !(cond)) {	\
      return PT_YIELDED;			\
    }						\
  } while(0)

/** @} */

#endif /* __PT_H__ */

/** @} */
Commit	Line	Data
ec1bef8e	1	/*
	2	* Copyright (c) 2004-2005, Swedish Institute of Computer Science.
	3	* All rights reserved.
	4	*
	5	* Redistribution and use in source and binary forms, with or without
	6	* modification, are permitted provided that the following conditions
	7	* are met:
	8	* 1. Redistributions of source code must retain the above copyright
	9	* notice, this list of conditions and the following disclaimer.
	10	* 2. Redistributions in binary form must reproduce the above copyright
	11	* notice, this list of conditions and the following disclaimer in the
	12	* documentation and/or other materials provided with the distribution.
	13	* 3. Neither the name of the Institute nor the names of its contributors
	14	* may be used to endorse or promote products derived from this software
	15	* without specific prior written permission.
	16	*
	17	* THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
	18	* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	19	* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	20	* ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
	21	* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	22	* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	23	* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	24	* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	25	* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	26	* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	27	* SUCH DAMAGE.
	28	*
	29	* This file is part of the Contiki operating system.
	30	*
	31	* Author: Adam Dunkels <adam@sics.se>
	32	*
	33	* $Id: pt.h,v 1.7 2006/10/02 07:52:56 adam Exp $
	34	*/
	35
	36	/**
	37	* \addtogroup pt
	38	* @{
	39	*/
	40
	41	/**
	42	* \file
	43	* Protothreads implementation.
	44	* \author
	45	* Adam Dunkels <adam@sics.se>
	46	*
	47	*/
	48
	49	#ifndef __PT_H__
	50	#define __PT_H__
	51
	52	#include "lc.h"
	53
	54	struct pt {
	55	lc_t lc;
	56	};
	57
	58	#define PT_WAITING 0
	59	#define PT_YIELDED 1
	60	#define PT_EXITED 2
	61	#define PT_ENDED 3
	62
	63	/**
	64	* \name Initialization
65	* @{
66	*/
67
68	/**
69	* Initialize a protothread.
70	*
71	* Initializes a protothread. Initialization must be done prior to
72	* starting to execute the protothread.
73	*
74	* \param pt A pointer to the protothread control structure.
75	*
76	* \sa PT_SPAWN()
77	*
78	* \hideinitializer
79	*/
80	#define PT_INIT(pt) LC_INIT((pt)->lc)
81
82	/** @} */
83
84	/**
85	* \name Declaration and definition
86	* @{
87	*/
88
89	/**
90	* Declaration of a protothread.
91	*
92	* This macro is used to declare a protothread. All protothreads must
93	* be declared with this macro.
94	*
95	* \param name_args The name and arguments of the C function
96	* implementing the protothread.
97	*
98	* \hideinitializer
99	*/
100	#define PT_THREAD(name_args) char name_args
101
102	/**
103	* Declare the start of a protothread inside the C function
104	* implementing the protothread.
105	*
106	* This macro is used to declare the starting point of a
107	* protothread. It should be placed at the start of the function in
108	* which the protothread runs. All C statements above the PT_BEGIN()
109	* invokation will be executed each time the protothread is scheduled.
110	*
111	* \param pt A pointer to the protothread control structure.
112	*
113	* \hideinitializer
114	*/
115	#define PT_BEGIN(pt) { char PT_YIELD_FLAG = 1; LC_RESUME((pt)->lc)
116
117	/**
118	* Declare the end of a protothread.
119	*
120	* This macro is used for declaring that a protothread ends. It must
121	* always be used together with a matching PT_BEGIN() macro.
122	*
123	* \param pt A pointer to the protothread control structure.
124	*
125	* \hideinitializer
126	*/
127	#define PT_END(pt) LC_END((pt)->lc); PT_YIELD_FLAG = 0; \
128	PT_INIT(pt); return PT_ENDED; }
129
130	/** @} */
131
132	/**
133	* \name Blocked wait
134	* @{
135	*/
136
137	/**
138	* Block and wait until condition is true.
139	*
140	* This macro blocks the protothread until the specified condition is
141	* true.
142	*
143	* \param pt A pointer to the protothread control structure.
144	* \param condition The condition.
145	*
146	* \hideinitializer
147	*/
148	#define PT_WAIT_UNTIL(pt, condition) \
149	do { \
150	LC_SET((pt)->lc); \
151	if(!(condition)) { \
152	return PT_WAITING; \
153	} \
154	} while(0)
155
156	/**
157	* Block and wait while condition is true.
158	*
159	* This function blocks and waits while condition is true. See
160	* PT_WAIT_UNTIL().
161	*
162	* \param pt A pointer to the protothread control structure.
163	* \param cond The condition.
164	*
165	* \hideinitializer
166	*/
167	#define PT_WAIT_WHILE(pt, cond) PT_WAIT_UNTIL((pt), !(cond))
168
169	/** @} */
170
171	/**
172	* \name Hierarchical protothreads
173	* @{
174	*/
175
176	/**
177	* Block and wait until a child protothread completes.
178	*
179	* This macro schedules a child protothread. The current protothread
180	* will block until the child protothread completes.
181	*
182	* \note The child protothread must be manually initialized with the
183	* PT_INIT() function before this function is used.
184	*
185	* \param pt A pointer to the protothread control structure.
186	* \param thread The child protothread with arguments
187	*
188	* \sa PT_SPAWN()
189	*
190	* \hideinitializer
191	*/
192	#define PT_WAIT_THREAD(pt, thread) PT_WAIT_WHILE((pt), PT_SCHEDULE(thread))
193
194	/**
195	* Spawn a child protothread and wait until it exits.
196	*
197	* This macro spawns a child protothread and waits until it exits. The
198	* macro can only be used within a protothread.
199	*
200	* \param pt A pointer to the protothread control structure.
201	* \param child A pointer to the child protothread's control structure.
202	* \param thread The child protothread with arguments
203	*
204	* \hideinitializer
205	*/
206	#define PT_SPAWN(pt, child, thread) \
207	do { \
208	PT_INIT((child)); \
209	PT_WAIT_THREAD((pt), (thread)); \
210	} while(0)
211
212	/** @} */
213
214	/**
215	* \name Exiting and restarting
216	* @{
217	*/
218
219	/**
220	* Restart the protothread.
221	*
222	* This macro will block and cause the running protothread to restart
223	* its execution at the place of the PT_BEGIN() call.
224	*
225	* \param pt A pointer to the protothread control structure.
226	*
227	* \hideinitializer
228	*/
229	#define PT_RESTART(pt) \
230	do { \
231	PT_INIT(pt); \
232	return PT_WAITING; \
233	} while(0)
234
235	/**
236	* Exit the protothread.
237	*
238	* This macro causes the protothread to exit. If the protothread was
239	* spawned by another protothread, the parent protothread will become
240	* unblocked and can continue to run.
241	*
242	* \param pt A pointer to the protothread control structure.
243	*
244	* \hideinitializer
245	*/
246	#define PT_EXIT(pt) \
247	do { \
248	PT_INIT(pt); \
249	return PT_EXITED; \
250	} while(0)
251
252	/** @} */
253
254	/**
255	* \name Calling a protothread
256	* @{
257	*/
258
259	/**
260	* Schedule a protothread.
261	*
262	* This function shedules a protothread. The return value of the
263	* function is non-zero if the protothread is running or zero if the
264	* protothread has exited.
265	*
266	* \param f The call to the C function implementing the protothread to
267	* be scheduled
268	*
269	* \hideinitializer
270	*/
271	#define PT_SCHEDULE(f) ((f) < PT_EXITED)
272
273	/** @} */
274
275	/**
276	* \name Yielding from a protothread
277	* @{
278	*/
279
280	/**
281	* Yield from the current protothread.
282	*
283	* This function will yield the protothread, thereby allowing other
284	* processing to take place in the system.
285	*
286	* \param pt A pointer to the protothread control structure.
287	*
288	* \hideinitializer
289	*/
290	#define PT_YIELD(pt) \
291	do { \
292	PT_YIELD_FLAG = 0; \
293	LC_SET((pt)->lc); \
294	if(PT_YIELD_FLAG == 0) { \
295	return PT_YIELDED; \
296	} \
297	} while(0)
298
299	/**
300	* \brief Yield from the protothread until a condition occurs.
301	* \param pt A pointer to the protothread control structure.
302	* \param cond The condition.
303	*
304	* This function will yield the protothread, until the
305	* specified condition evaluates to true.
306	*
307	*
308	* \hideinitializer
309	*/
310	#define PT_YIELD_UNTIL(pt, cond) \
311	do { \
312	PT_YIELD_FLAG = 0; \
313	LC_SET((pt)->lc); \
314	if((PT_YIELD_FLAG == 0) \|\| !(cond)) { \
315	return PT_YIELDED; \
316	} \
317	} while(0)
318
319	/** @} */
320
321	#endif /* __PT_H__ */
322
323	/** @} */