process.h

Go to the documentation of this file.

/*
 * Copyright (c) 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.
 *
 * @(#)$Id: process.h,v 1.8 2005/07/04 14:57:05 adam Exp $
 */
/**
 * \defgroup process Contiki processes
 *
 * A process in Contiki consists of a single \ref pt protothread.
 *
 * @{
 */

/**
 * \file
 * Header file for the Contiki process interface.
 * \author
 * Adam Dunkels <adam@sics.se>
 *
 */
#ifndef __PROCESS_H__
#define __PROCESS_H__

#include "pt.h"
#include "cc.h"

typedef unsigned char process_event_t;
typedef void *        process_data_t;
typedef unsigned char process_num_events_t;

#define PROCESS_ERR_OK        0
#define PROCESS_ERR_FULL      1
#define PROCESS_ERR_NOTUNIQUE 2
#define PROCESS_ERR_NOTFOUND  3

#define PROCESS_NONE          NULL

#define PROCESS_CONF_NUMEVENTS 32

#define PROCESS_EVENT_NONE            0x80
#define PROCESS_EVENT_INIT            0x81
#define PROCESS_EVENT_POLL            0x82
#define PROCESS_EVENT_EXIT            0x83
#define PROCESS_EVENT_SERVICE_REMOVED 0x84
#define PROCESS_EVENT_CONTINUE        0x85
#define PROCESS_EVENT_MSG             0x86
#define PROCESS_EVENT_EXITED          0x87
#define PROCESS_EVENT_TIMER           0x88
#define PROCESS_EVENT_MAX             0x89

#define PROCESS_BROADCAST NULL

/**
 * Define the beginning of a process.
 *
 * This macro defines the beginning of a process, and must always
 * appear in a PROCESS_THREAD() definition. The PROCESS_END() macro
 * must come at the end of the process.
 *
 * \hideinitializer
 */
#define PROCESS_BEGIN()             PT_BEGIN(process_pt)

/**
 * Define the end of a process.
 *
 * This macro defines the end of a process. It must appear in a
 * PROCESS_THREAD() definition and must always be included. The
 * process exits when the PROCESS_END() macro is reached.
 *
 * \hideinitializer
 */
#define PROCESS_END()               PT_END(process_pt)

/**
 * Wait for an event to be posted to the process.
 *
 * This macro blocks the currently running process until the process
 * receives an event.
 *
 * \hideinitializer
 */
#define PROCESS_WAIT_EVENT()        PROCESS_YIELD()

/**
 * Wait for an event to be posted to the process, with an extra
 * condition.
 *
 * This macro is similar to PROCESS_WAIT_EVENT() in that it blocks the
 * currently running process until the process receives an event. But
 * PROCESS_WAIT_EVENT_UNTIL() takes an extra condition which must be
 * true for the process to continue.
 *
 * \param c The condition that must be true for the process to continue.
 * \sa PT_WAIT_UNTIL()
 *
 * \hideinitializer
 */
#define PROCESS_WAIT_EVENT_UNTIL(c) PROCESS_YIELD_UNTIL(c)

/**
 * Yield the currently running process.
 *
 * \hideinitializer
 */
#define PROCESS_YIELD()             PT_YIELD(process_pt)

/**
 * Yield the currently running process until a condition occurs.
 *
 * This macro is different from PROCESS_WAIT_UNTIL() in that
 * PROCESS_YIELD_UNTIL() is guaranteed to always yield at least
 * once. This ensures that the process does not end up in an infinite
 * loop and monopolizing the CPU.
 *
 * \param c The condition to wait for.
 *
 * \hideinitializer
 */
#define PROCESS_YIELD_UNTIL(c)      PT_YIELD_UNTIL(process_pt, c)

/**
 * Wait for a condition to occur.
 *
 * This macro does not guarantee that the process yields, and should
 * therefore be used with care. In most cases, PROCESS_WAIT_EVENT(),
 * PROCESS_WAIT_EVENT_UNTIL(), PROCESS_YIELD() or
 * PROCESS_YIELD_UNTIL() should be used instead.
 *
 * \param c The condition to wait for.
 *
 * \hideinitializer
 */
#define PROCESS_WAIT_UNTIL(c)       PT_WAIT_UNTIL(process_pt, c)

/**
 * Exit the currently running process.
 *
 * \hideinitializer
 */
#define PROCESS_EXIT()              PT_EXIT(process_pt)

/**
 * Spawn a protothread from the process.
 *
 * \param pt The protothread state (struct pt) for the new protothread
 * \param thread The call to the protothread function.
 * \sa PT_SPAWN()
 * 
 * \hideinitializer
 */
#define PROCESS_SPAWN(pt, thread)   PT_SPAWN(process_pt, pt, thread)

/**
 * Yield the process for a short while.
 *
 * This macro yields the currently running process for a short while,
 * thus letting other processes run before the process continues.
 *
 * \hideinitializer
 */
#define PROCESS_PAUSE()             do {                                \
  process_post(PROCESS_CURRENT(), PROCESS_EVENT_CONTINUE, NULL);        \
  PROCESS_WAIT_EVENT();                                                 \
} while(0)


/**
 * Define the body of a process.
 *
 * This macro is used to define the body (protothread) of a
 * process. The process is called whenever an event occurs in the
 * system, A process always start with the PROCESS_BEGIN() macro and
 * end with the PROCESS_END() macro.
 */
#define PROCESS_THREAD(name, ev, data)                          \
static PT_THREAD(process_thread_##name(struct pt *process_pt,   \
                                       process_event_t ev,      \
                                       process_data_t data))

#if PROCESS_LOADABLE
#define PROCESS_LOAD(name) const struct process *process_load = &name;
#else  /* PROCESS_LOADABLE */
#define PROCESS_LOAD(name)
#endif /* PROCESS_LOADABLE */

/**
 * Declare the name of a process.
 *
 * This macro is typically used in header files to declare the name of
 * a process that is implemented in the C file.
 *
 * \hideinitializer
 */
#define PROCESS_NAME(name) extern struct process name

/**
 * Declare a process.
 *
 * This macro declares a process with the variable name of the
 * process, and a textual repressentation of the process (used mainly
 * for debugging).
 *
 * \hideinitializer
 */
#if PROCESS_LOADABLE
#define PROCESS(name, strname)                          \
  PROCESS_THREAD(name, ev, data);                       \
  static struct process name = { NULL, strname,         \
                          process_thread_##name };      \
  PROCESS_LOAD(name)
#else
#define PROCESS(name, strname)                          \
  PROCESS_THREAD(name, ev, data);                       \
  struct process name = { NULL, strname,                \
                          process_thread_##name };      \
  PROCESS_LOAD(name)
#endif

struct process {
  struct process *next;
  const char *name;
  PT_THREAD((* thread)(struct pt *, process_event_t, process_data_t));
  struct pt pt;
  unsigned char state;
};


void process_start(struct process *p, char *arg);
int  process_post(struct process *p, process_event_t ev, process_data_t data);
void process_post_synch(struct process *p,
                        process_event_t ev, process_data_t data);

void process_poll(struct process *p);

void process_exit(struct process *p);


/**
 * Get a pointer to the currently running process.
 *
 * This macro get a pointer to the currently running
 * process. Typically, this macro is used to post an event to the
 * current process with process_post().
 *
 * \hideinitializer
 */
#define PROCESS_CURRENT() process_current
extern struct process *process_current;

#define PROCESS_SET_FLAGS(flags)
#define PROCESS_NO_BROADCAST

process_event_t process_alloc_event(void);

void process_init(void);

/**
 * Process one event from the event queue.
 *
 * This function is called from the system initialization code (the
 * main() function) and should never be called from user programs. The
 * function processes one event from the kernel's internal event
 * queue. The function returns the number of events that are left to
 * be processed.
 *
 * If no events are left to be processed, the CPU can be put into a
 * sleep mode.
 *
 */
int process_run(void);

extern struct process *process_list;

#define PROCESS_LIST() process_list

#endif /* __PROCESS_H__ */

/** @} */

---