commit 341c06b33955120c40bc7dc8afabe4d3a019f571 Author: 陈逸凡 <1343619937@qq.com> Date: Tue Nov 22 09:59:34 2022 +0800 1 diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..ff573ef --- /dev/null +++ b/Makefile @@ -0,0 +1,9 @@ +CFLAGS=-O -Wuninitialized -Werror + +all: example-codelock example-buffer example-small + +example-codelock: example-codelock.c pt.h lc.h + +example-buffer: example-buffer.c pt.h lc.h + +example-small: example-small.c pt.h lc.h diff --git a/README-VISUAL-C++.txt b/README-VISUAL-C++.txt new file mode 100644 index 0000000..3b09a69 --- /dev/null +++ b/README-VISUAL-C++.txt @@ -0,0 +1,5 @@ +Protothreads can in some cases fail to compile under Visual C++ +version 6.0 due to a bug in the compiler. See the following page for a +solution to the problem: + +http://support.microsoft.com/default.aspx?scid=kb;en-us;199057 diff --git a/README.md b/README.md new file mode 100644 index 0000000..eeace5d --- /dev/null +++ b/README.md @@ -0,0 +1,51 @@ +Protothreads are extremely lightweight stackless threads designed for +severely memory constrained systems such as small embedded systems or +sensor network nodes. Protothreads can be used with or without an +underlying operating system. + +Protothreads provides a blocking context on top of an event-driven +system, without the overhead of per-thread stacks. The purpose of +protothreads is to implement sequential flow of control without +complex state machines or full multi-threading. + +Main features: + + * No machine specific code - the protothreads library is pure C + * Does not use error-prone functions such as longjmp() + * Very small RAM overhead - only two bytes per protothread + * Can be used with or without an OS + * Provides blocking wait without full multi-threading or + stack-switching + * Freely available under a BSD-like open source license + +Example applications: + + * Memory constrained systems + * Event-driven protocol stacks + * Small embedded systems + * Sensor network nodes + +The protothreads library is released under an open source BSD-style +license that allows for both non-commercial and commercial usage. The +only requirement is that credit is given. + +The protothreads library was written by Adam Dunkels +with support from Oliver Schmidt . + +More information and new versions can be found at the protothreads +homepage: + http://www.sics.se/~adam/pt/ + +Documentation can be found in the doc/ subdirectory. + +Two example programs illustrating the use of protothreads can be found +in this directory: + + example-small.c A small example showing how to use protothreads + example-buffer.c The bounded buffer problem with protothreads + example-codelock.c A code lock with simulated key input + +To compile the examples, simply run "make". + + +Adam Dunkels, 3 June 2006 diff --git a/doc/Doxyfile b/doc/Doxyfile new file mode 100644 index 0000000..cecf583 --- /dev/null +++ b/doc/Doxyfile @@ -0,0 +1,229 @@ +# Doxyfile 1.4.6 + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +PROJECT_NAME = "The Protothreads Library 1.4" +PROJECT_NUMBER = +OUTPUT_DIRECTORY = . +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +USE_WINDOWS_ENCODING = NO +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = ../ +STRIP_FROM_INC_PATH = +SHORT_NAMES = YES +JAVADOC_AUTOBRIEF = YES +MULTILINE_CPP_IS_BRIEF = NO +DETAILS_AT_TOP = YES +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 8 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_JAVA = NO +BUILTIN_STL_SUPPORT = NO +DISTRIBUTE_GROUP_DOC = NO +SUBGROUPING = YES +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = NO +EXTRACT_LOCAL_METHODS = NO +HIDE_UNDOC_MEMBERS = YES +HIDE_UNDOC_CLASSES = YES +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +SHOW_INCLUDE_FILES = YES +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_BY_SCOPE_NAME = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = NO +GENERATE_DEPRECATEDLIST= NO +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = NO +SHOW_DIRECTORIES = NO +FILE_VERSION_FILTER = +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = pt-mainpage.txt \ + pt-doc.txt \ + ../pt.h \ + ../pt-sem.h \ + ../lc.h \ + ../lc-switch.h \ + ../lc-addrlabels.h +FILE_PATTERNS = +RECURSIVE = NO +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXAMPLE_PATH = .. +EXAMPLE_PATTERNS = +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = YES +INLINE_SOURCES = YES +STRIP_CODE_COMMENTS = NO +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = NO +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_ALIGN_MEMBERS = YES +GENERATE_HTMLHELP = YES +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +BINARY_TOC = NO +TOC_EXPAND = NO +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = YES +TREEVIEW_WIDTH = 250 +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = YES +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = YES +PAPER_TYPE = a4 +EXTRA_PACKAGES = +LATEX_HEADER = header.tex +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = NO +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +XML_PROGRAMLISTING = YES +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = DOXYGEN +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +PERL_PATH = /usr/bin/perl +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = NO +HIDE_UNDOC_RELATIONS = NO +HAVE_DOT = NO +CLASS_GRAPH = NO +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = NO +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = YES +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +DOT_PATH = +DOTFILE_DIRS = +MAX_DOT_GRAPH_WIDTH = 1024 +MAX_DOT_GRAPH_HEIGHT = 1024 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_TRANSPARENT = NO +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = NO diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..fd0c7d1 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,7 @@ +dox: + doxygen Doxyfile + + +pdf: dox + (cd latex; $(MAKE) refman.pdf) + mv latex/refman.pdf pt-refman.pdf \ No newline at end of file diff --git a/doc/header.tex b/doc/header.tex new file mode 100644 index 0000000..5899653 --- /dev/null +++ b/doc/header.tex @@ -0,0 +1,52 @@ +\documentclass[a4paper]{article} +\usepackage{a4wide} +\usepackage{makeidx} +\usepackage{fancyhdr} +\usepackage{graphicx} +\usepackage{multicol} +\usepackage{float} +\usepackage{textcomp} +\usepackage{alltt} +\usepackage{times} +\usepackage{epsfig} +\ifx\pdfoutput\undefined +\usepackage[ps2pdf, + pagebackref=true, + colorlinks=true, + linkcolor=blue + ]{hyperref} +\usepackage{pspicture} +\else +\usepackage[pdftex, + pagebackref=true, + colorlinks=true, + linkcolor=blue + ]{hyperref} +\fi +\usepackage{doxygen} +\makeindex +\setcounter{tocdepth}{1} +\renewcommand{\footrulewidth}{0.4pt} +\begin{document} +\begin{titlepage} +\vspace*{5cm} +\begin{center} +{\Huge Protothreads}\\ +\vspace*{1cm} +{\LARGE The Protothreads Library 1.3 Reference Manual}\\ +\vspace*{3cm} +{\Large June 2006}\\ +\vspace*{2cm} +\includegraphics[width=6cm]{../sicslogo.pdf}\\ +\vspace*{1cm} +{\Large Adam Dunkels}\\ +{\Large \texttt{adam@sics.se}}\\ +\vspace*{1cm} +{\LARGE Swedish Institute of Computer Science}\\ +\vspace*{0.5cm} + +\end{center} +\end{titlepage} +\pagenumbering{roman} +\tableofcontents +\pagenumbering{arabic} diff --git a/doc/html/a00005.html b/doc/html/a00005.html new file mode 100644 index 0000000..4f2e17d --- /dev/null +++ b/doc/html/a00005.html @@ -0,0 +1,40 @@ + + +The Protothreads Library 1.4: pt Struct Reference + + + + +
+
+
+
+

pt Struct Reference
+ +[Protothreads] +

Detailed Description

+ +

+ +

+Definition at line 54 of file pt.h. + + + + +

Data Fields

+lc_t lc
+

Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/a00006.html b/doc/html/a00006.html new file mode 100644 index 0000000..2ea0775 --- /dev/null +++ b/doc/html/a00006.html @@ -0,0 +1,40 @@ + + +The Protothreads Library 1.4: pt_sem Struct Reference + + + + +
+
+
+
+

pt_sem Struct Reference
+ +[Protothread semaphores] +

Detailed Description

+ +

+ +

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

Data Fields

+unsigned int count
+

Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/a00009.html b/doc/html/a00009.html new file mode 100644 index 0000000..b15ca22 --- /dev/null +++ b/doc/html/a00009.html @@ -0,0 +1,61 @@ + + +The Protothreads Library 1.4: lc-addrlabels.h File Reference + + + + +
+
+
+
+

lc-addrlabels.h File Reference

Detailed Description

+Implementation of local continuations based on the "Labels as values" feature of gcc. +

+

Author:
Adam Dunkels <adam@sics.se>
+This implementation of local continuations is based on a special feature of the GCC C compiler called "labels as values". This feature allows assigning pointers with the address of the code corresponding to a particular C label.

+For more information, see the GCC documentation: http://gcc.gnu.org/onlinedocs/gcc/Labels-as-Values.html +

+Definition in file lc-addrlabels.h. +

+ +

+Go to the source code of this file. + + + + + + + + + + + + + + + + + +

Defines

+#define LC_INIT(s)   s = NULL
+#define LC_RESUME(s)
+#define LC_CONCAT2(s1, s2)   s1##s2
+#define LC_CONCAT(s1, s2)   LC_CONCAT2(s1, s2)
+#define LC_SET(s)
+#define LC_END(s)

Typedefs

+typedef void * lc_t
+

Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/a00010.html b/doc/html/a00010.html new file mode 100644 index 0000000..4ba31de --- /dev/null +++ b/doc/html/a00010.html @@ -0,0 +1,56 @@ + + +The Protothreads Library 1.4: lc-switch.h File Reference + + + + +
+
+
+
+

lc-switch.h File Reference

Detailed Description

+Implementation of local continuations based on switch() statment. +

+

Author:
Adam Dunkels <adam@sics.se>
+This implementation of local continuations uses the C switch() statement to resume execution of a function somewhere inside the function's body. The implementation is based on the fact that switch() statements are able to jump directly into the bodies of control structures such as if() or while() statmenets.

+This implementation borrows heavily from Simon Tatham's coroutines implementation in C: http://www.chiark.greenend.org.uk/~sgtatham/coroutines.html +

+Definition in file lc-switch.h. +

+ +

+Go to the source code of this file. + + + + + + + + + + + + + + +

Defines

+#define LC_INIT(s)   s = 0;
+#define LC_RESUME(s)   switch(s) { case 0:
+#define LC_SET(s)   s = __LINE__; case __LINE__:
+#define LC_END(s)   }

Typedefs

+typedef unsigned short lc_t
 The local continuation type.
+

Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/a00011.html b/doc/html/a00011.html new file mode 100644 index 0000000..b9bf8ac --- /dev/null +++ b/doc/html/a00011.html @@ -0,0 +1,51 @@ + + +The Protothreads Library 1.4: lc.h File Reference + + + + +
+
+
+
+

lc.h File Reference

Detailed Description

+Local continuations. +

+

Author:
Adam Dunkels <adam@sics.se>
+ +

+Definition in file lc.h. +

+#include "lc-switch.h"
+ +

+Go to the source code of this file. + + + + + + + + + + + + + + +

Defines

#define LC_INIT(lc)
 Initialize a local continuation.
#define LC_SET(lc)
 Set a local continuation.
#define LC_RESUME(lc)
 Resume a local continuation.
#define LC_END(lc)
 Mark the end of local continuation usage.
+

Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/a00012.html b/doc/html/a00012.html new file mode 100644 index 0000000..25054d5 --- /dev/null +++ b/doc/html/a00012.html @@ -0,0 +1,51 @@ + + +The Protothreads Library 1.4: pt-sem.h File Reference + + + + +
+
+
+
+

pt-sem.h File Reference

Detailed Description

+Couting semaphores implemented on protothreads. +

+

Author:
Adam Dunkels <adam@sics.se>
+ +

+Definition in file pt-sem.h. +

+#include "pt.h"
+ +

+Go to the source code of this file. + + + + + + + + + + + + + + +

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

Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/a00013.html b/doc/html/a00013.html new file mode 100644 index 0000000..76430ea --- /dev/null +++ b/doc/html/a00013.html @@ -0,0 +1,100 @@ + + +The Protothreads Library 1.4: pt.h File Reference + + + + +
+
+
+
+

pt.h File Reference

Detailed Description

+Protothreads implementation. +

+

Author:
Adam Dunkels <adam@sics.se>
+ +

+Definition in file pt.h. +

+#include "lc.h"
+ +

+Go to the source code of this file. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Data Structures

struct  pt

Initialization

#define PT_INIT(pt)
 Initialize a protothread.

Declaration and definition

#define PT_THREAD(name_args)
 Declaration of a protothread.
#define PT_BEGIN(pt)
 Declare the start of a protothread inside the C function implementing the protothread.
#define PT_END(pt)
 Declare the end of a protothread.

Blocked wait

#define PT_WAIT_UNTIL(pt, condition)
 Block and wait until condition is true.
#define PT_WAIT_WHILE(pt, cond)
 Block and wait while condition is true.

Hierarchical protothreads

#define PT_WAIT_THREAD(pt, thread)
 Block and wait until a child protothread completes.
#define PT_SPAWN(pt, child, thread)
 Spawn a child protothread and wait until it exits.

Exiting and restarting

#define PT_RESTART(pt)
 Restart the protothread.
#define PT_EXIT(pt)
 Exit the protothread.

Calling a protothread

#define PT_SCHEDULE(f)
 Schedule a protothread.

Yielding from a protothread

#define PT_YIELD(pt)
 Yield from the current protothread.
#define PT_YIELD_UNTIL(pt, cond)
 Yield from the protothread until a condition occurs.

Defines

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

Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/a00014.html b/doc/html/a00014.html new file mode 100644 index 0000000..424adc4 --- /dev/null +++ b/doc/html/a00014.html @@ -0,0 +1,627 @@ + + +The Protothreads Library 1.4: Protothreads + + + + +
+
+

Protothreads

Detailed Description

+Protothreads are implemented in a single header file, pt.h, which includes the local continuations header file, lc.h. +

+This file in turn includes the actual implementation of local continuations, which typically also is contained in a single header file. +

+ + + + + + + +

+

+ + + + +

+

+ + + +

+

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

Files

file  pt.h
 Protothreads implementation.

Modules

 Protothread semaphores
 This module implements counting semaphores on top of protothreads.
 Local continuations
 Local continuations form the basis for implementing protothreads.

Data Structures

struct  pt

Initialization

#define PT_INIT(pt)
 Initialize a protothread.

Declaration and definition

#define PT_THREAD(name_args)
 Declaration of a protothread.
#define PT_BEGIN(pt)
 Declare the start of a protothread inside the C function implementing the protothread.
#define PT_END(pt)
 Declare the end of a protothread.

Blocked wait

#define PT_WAIT_UNTIL(pt, condition)
 Block and wait until condition is true.
#define PT_WAIT_WHILE(pt, cond)
 Block and wait while condition is true.

Hierarchical protothreads

#define PT_WAIT_THREAD(pt, thread)
 Block and wait until a child protothread completes.
#define PT_SPAWN(pt, child, thread)
 Spawn a child protothread and wait until it exits.

Exiting and restarting

#define PT_RESTART(pt)
 Restart the protothread.
#define PT_EXIT(pt)
 Exit the protothread.

Calling a protothread

#define PT_SCHEDULE(f)
 Schedule a protothread.

Yielding from a protothread

#define PT_YIELD(pt)
 Yield from the current protothread.
#define PT_YIELD_UNTIL(pt, cond)
 Yield from the protothread until a condition occurs.

Defines

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

Define Documentation

+

+ + + + +
+ + + + + + + + + +
#define PT_BEGIN ( pt   ) 
+
+ + + + + +
+   + + +

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

+

Parameters:
+ + +
pt A pointer to the protothread control structure.
+
+ +

+Definition at line 115 of file pt.h.

+

+ + + + +
+ + + + + + + + + +
#define PT_END ( pt   ) 
+
+ + + + + +
+   + + +

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

+

Parameters:
+ + +
pt A pointer to the protothread control structure.
+
+ +

+Definition at line 127 of file pt.h.

+

+ + + + +
+ + + + + + + + + +
#define PT_EXIT ( pt   ) 
+
+ + + + + +
+   + + +

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

+

Parameters:
+ + +
pt A pointer to the protothread control structure.
+
+ +

+Definition at line 246 of file pt.h.

+

+ + + + +
+ + + + + + + + + +
#define PT_INIT ( pt   ) 
+
+ + + + + +
+   + + +

+Initialize a protothread. +

+Initializes a protothread. Initialization must be done prior to starting to execute the protothread.

+

Parameters:
+ + +
pt A pointer to the protothread control structure.
+
+
See also:
PT_SPAWN()
+ +

+Definition at line 80 of file pt.h.

+

+ + + + +
+ + + + + + + + + +
#define PT_RESTART ( pt   ) 
+
+ + + + + +
+   + + +

+Restart the protothread. +

+This macro will block and cause the running protothread to restart its execution at the place of the PT_BEGIN() call.

+

Parameters:
+ + +
pt A pointer to the protothread control structure.
+
+ +

+Definition at line 229 of file pt.h.

+

+ + + + +
+ + + + + + + + + +
#define PT_SCHEDULE ( f   ) 
+
+ + + + + +
+   + + +

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

+

Parameters:
+ + +
f The call to the C function implementing the protothread to be scheduled
+
+ +

+Definition at line 271 of file pt.h.

+

+ + + + +
+ + + + + + + + + + + + + + + +
#define PT_SPAWN ( pt,
child,
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.

+

Parameters:
+ + + + +
pt A pointer to the protothread control structure.
child A pointer to the child protothread's control structure.
thread The child protothread with arguments
+
+ +

+Definition at line 206 of file pt.h.

+

+ + + + +
+ + + + + + + + + +
#define PT_THREAD ( name_args   ) 
+
+ + + + + +
+   + + +

+Declaration of a protothread. +

+This macro is used to declare a protothread. All protothreads must be declared with this macro.

+

Parameters:
+ + +
name_args The name and arguments of the C function implementing the protothread.
+
+ +

+Definition at line 100 of file pt.h.

+

+ + + + +
+ + + + + + + + + + + + +
#define PT_WAIT_THREAD ( pt,
thread   ) 
+
+ + + + + +
+   + + +

+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.
+
Parameters:
+ + + +
pt A pointer to the protothread control structure.
thread The child protothread with arguments
+
+
See also:
PT_SPAWN()
+ +

+Definition at line 192 of file pt.h.

+

+ + + + +
+ + + + + + + + + + + + +
#define PT_WAIT_UNTIL ( pt,
condition   ) 
+
+ + + + + +
+   + + +

+Block and wait until condition is true. +

+This macro blocks the protothread until the specified condition is true.

+

Parameters:
+ + + +
pt A pointer to the protothread control structure.
condition The condition.
+
+ +

+Definition at line 148 of file pt.h.

+

+ + + + +
+ + + + + + + + + + + + +
#define PT_WAIT_WHILE ( pt,
cond   ) 
+
+ + + + + +
+   + + +

+Block and wait while condition is true. +

+This function blocks and waits while condition is true. See PT_WAIT_UNTIL().

+

Parameters:
+ + + +
pt A pointer to the protothread control structure.
cond The condition.
+
+ +

+Definition at line 167 of file pt.h.

+

+ + + + +
+ + + + + + + + + +
#define PT_YIELD ( pt   ) 
+
+ + + + + +
+   + + +

+Yield from the current protothread. +

+This function will yield the protothread, thereby allowing other processing to take place in the system.

+

Parameters:
+ + +
pt A pointer to the protothread control structure.
+
+ +

+Definition at line 290 of file pt.h.

+

+ + + + +
+ + + + + + + + + + + + +
#define PT_YIELD_UNTIL ( pt,
cond   ) 
+
+ + + + + +
+   + + +

+Yield from the protothread until a condition occurs. +

+

Parameters:
+ + + +
pt A pointer to the protothread control structure.
cond The condition.
+
+This function will yield the protothread, until the specified condition evaluates to true. +

+Definition at line 310 of file pt.h.

+

Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/a00015.html b/doc/html/a00015.html new file mode 100644 index 0000000..1a0d69a --- /dev/null +++ b/doc/html/a00015.html @@ -0,0 +1,711 @@ + + +The Protothreads Library 1.4: Examples + + + + +
+
+

Examples

+A small example

+This first example shows a very simple program: two protothreads waiting for each other to toggle two flags. The code illustrates how to write protothreads code, how to initialize protothreads, and how to schedule them.

+

/**
+ * This is a very small example that shows how to use
+ * protothreads. The program consists of two protothreads that wait
+ * for each other to toggle a variable.
+ */
+
+/* We must always include pt.h in our protothreads code. */
+#include "pt.h"
+
+#include <stdio.h> /* For printf(). */
+
+/* Two flags that the two protothread functions use. */
+static int protothread1_flag, protothread2_flag;
+
+/**
+ * The first protothread function. A protothread function must always
+ * return an integer, but must never explicitly return - returning is
+ * performed inside the protothread statements.
+ *
+ * The protothread function is driven by the main loop further down in
+ * the code.
+ */
+static int
+protothread1(struct pt *pt)
+{
+  /* A protothread function must begin with PT_BEGIN() which takes a
+     pointer to a struct pt. */
+  PT_BEGIN(pt);
+
+  /* We loop forever here. */
+  while(1) {
+    /* Wait until the other protothread has set its flag. */
+    PT_WAIT_UNTIL(pt, protothread2_flag != 0);
+    printf("Protothread 1 running\n");
+
+    /* We then reset the other protothread's flag, and set our own
+       flag so that the other protothread can run. */
+    protothread2_flag = 0;
+    protothread1_flag = 1;
+
+    /* And we loop. */
+  }
+
+  /* All protothread functions must end with PT_END() which takes a
+     pointer to a struct pt. */
+  PT_END(pt);
+}
+
+/**
+ * The second protothread function. This is almost the same as the
+ * first one.
+ */
+static int
+protothread2(struct pt *pt)
+{
+  PT_BEGIN(pt);
+
+  while(1) {
+    /* Let the other protothread run. */
+    protothread2_flag = 1;
+
+    /* Wait until the other protothread has set its flag. */
+    PT_WAIT_UNTIL(pt, protothread1_flag != 0);
+    printf("Protothread 2 running\n");
+    
+    /* We then reset the other protothread's flag. */
+    protothread1_flag = 0;
+
+    /* And we loop. */
+  }
+  PT_END(pt);
+}
+
+/**
+ * Finally, we have the main loop. Here is where the protothreads are
+ * initialized and scheduled. First, however, we define the
+ * protothread state variables pt1 and pt2, which hold the state of
+ * the two protothreads.
+ */
+static struct pt pt1, pt2;
+int
+main(void)
+{
+  /* Initialize the protothread state variables with PT_INIT(). */
+  PT_INIT(&pt1);
+  PT_INIT(&pt2);
+  
+  /*
+   * Then we schedule the two protothreads by repeatedly calling their
+   * protothread functions and passing a pointer to the protothread
+   * state variables as arguments.
+   */
+  while(1) {
+    protothread1(&pt1);
+    protothread2(&pt2);
+  }
+}
+

+A code-lock

+This example shows how to implement a simple code lock - the kind of device that is placed next to doors and that you have to push a four digit number into in order to unlock the door.

+The code lock waits for key presses from a numeric keyboard and if the correct code is entered, the lock is unlocked. There is a maximum time of one second between each key press, and after the correct code has been entered, no more keys must be pressed for 0.5 seconds before the lock is opened.

+

/*
+ * 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 protothreads library.
+ *
+ * Author: Adam Dunkels <adam@sics.se>
+ *
+ * $Id: example-codelock.c,v 1.5 2005/10/06 07:57:08 adam Exp $
+ */
+
+/*
+ *
+ * This example shows how to implement a simple code lock. The code
+ * lock waits for key presses from a numeric keyboard and if the
+ * correct code is entered, the lock is unlocked. There is a maximum
+ * time of one second between each key press, and after the correct
+ * code has been entered, no more keys must be pressed for 0.5 seconds
+ * before the lock is opened.
+ *
+ * This is an example that shows two things:
+ * - how to implement a code lock key input mechanism, and
+ * - how to implement a sequential timed routine.
+ *
+ * The program consists of two protothreads, one that implements the
+ * code lock reader and one that implements simulated keyboard input.
+ *
+ *
+ */
+
+#ifdef _WIN32
+#include <windows.h>
+#else
+#include <unistd.h>
+#include <sys/time.h>
+#endif
+#include <stdio.h>
+
+#include "pt.h"
+
+/*---------------------------------------------------------------------------*/
+/*
+ * The following definitions are just for the simple timer library
+ * used in this example. The actual implementation of the functions
+ * can be found at the end of this file.
+ */
+struct timer { int start, interval; };
+static int  timer_expired(struct timer *t);
+static void timer_set(struct timer *t, int usecs);
+/*---------------------------------------------------------------------------*/
+/*
+ * This example uses two timers: one for the code lock protothread and
+ * one for the simulated key input protothread.
+ */
+static struct timer codelock_timer, input_timer;
+/*---------------------------------------------------------------------------*/
+/*
+ * This is the code that has to be entered.
+ */
+static const char code[4] = {'1', '4', '2', '3'};
+/*---------------------------------------------------------------------------*/
+/*
+ * This example has two protothread and therefor has two protothread
+ * control structures of type struct pt. These are initialized with
+ * PT_INIT() in the main() function below.
+ */
+static struct pt codelock_pt, input_pt;
+/*---------------------------------------------------------------------------*/
+/*
+ * The following code implements a simple key input. Input is made
+ * with the press_key() function, and the function key_pressed()
+ * checks if a key has been pressed. The variable "key" holds the
+ * latest key that was pressed. The variable "key_pressed_flag" is set
+ * when a key is pressed and cleared when a key press is checked.
+ */
+static char key, key_pressed_flag;
+
+static void
+press_key(char k)
+{
+  printf("--- Key '%c' pressed\n", k);
+  key = k;
+  key_pressed_flag = 1;
+}
+
+static int
+key_pressed(void)
+{
+  if(key_pressed_flag != 0) {
+    key_pressed_flag = 0;
+    return 1;
+  }
+  return 0;
+}
+/*---------------------------------------------------------------------------*/
+/*
+ * Declaration of the protothread function implementing the code lock
+ * logic. The protothread function is declared using the PT_THREAD()
+ * macro. The function is declared with the "static" keyword since it
+ * is local to this file. The name of the function is codelock_thread
+ * and it takes one argument, pt, of the type struct pt.
+ *
+ */
+static
+PT_THREAD(codelock_thread(struct pt *pt))
+{
+  /* This is a local variable that holds the number of keys that have
+   * been pressed. Note that it is declared with the "static" keyword
+   * to make sure that the variable is *not* allocated on the stack.
+   */
+  static int keys;
+
+  /*
+   * Declare the beginning of the protothread.
+   */
+  PT_BEGIN(pt);
+
+  /*
+   * We'll let the protothread loop until the protothread is
+   * expliticly exited with PT_EXIT().
+   */
+  while(1) {
+
+    /*
+     * We'll be reading key presses until we get the right amount of
+     * correct keys.
+     */ 
+    for(keys = 0; keys < sizeof(code); ++keys) {
+
+      /*
+       * If we haven't gotten any keypresses, we'll simply wait for one.
+       */
+      if(keys == 0) {
+
+        /*
+         * The PT_WAIT_UNTIL() function will block until the condition
+         * key_pressed() is true.
+         */
+        PT_WAIT_UNTIL(pt, key_pressed());
+      } else {
+        
+        /*
+         * If the "key" variable was larger than zero, we have already
+         * gotten at least one correct key press. If so, we'll not
+         * only wait for the next key, but we'll also set a timer that
+         * expires in one second. This gives the person pressing the
+         * keys one second to press the next key in the code.
+         */
+        timer_set(&codelock_timer, 1000);
+
+        /*
+         * The following statement shows how complex blocking
+         * conditions can be easily expressed with protothreads and
+         * the PT_WAIT_UNTIL() function.
+         */
+        PT_WAIT_UNTIL(pt, key_pressed() || timer_expired(&codelock_timer));
+
+        /*
+         * If the timer expired, we should break out of the for() loop
+         * and start reading keys from the beginning of the while(1)
+         * loop instead.
+         */
+        if(timer_expired(&codelock_timer)) {
+          printf("Code lock timer expired.\n");
+          
+          /*
+           * Break out from the for() loop and start from the
+           * beginning of the while(1) loop.
+           */
+          break;
+        }
+      }
+
+      /*
+       * Check if the pressed key was correct.
+       */
+      if(key != code[keys]) {
+        printf("Incorrect key '%c' found\n", key);
+        /*
+         * Break out of the for() loop since the key was incorrect.
+         */
+        break;
+      } else {
+        printf("Correct key '%c' found\n", key);
+      }
+    }
+
+    /*
+     * Check if we have gotten all keys.
+     */
+    if(keys == sizeof(code)) {
+      printf("Correct code entered, waiting for 500 ms before unlocking.\n");
+
+      /*
+       * Ok, we got the correct code. But to make sure that the code
+       * was not just a fluke of luck by an intruder, but the correct
+       * code entered by a person that knows the correct code, we'll
+       * wait for half a second before opening the lock. If another
+       * key is pressed during this time, we'll assume that it was a
+       * fluke of luck that the correct code was entered the first
+       * time.
+       */
+      timer_set(&codelock_timer, 500);      
+      PT_WAIT_UNTIL(pt, key_pressed() || timer_expired(&codelock_timer));
+
+      /*
+       * If we continued from the PT_WAIT_UNTIL() statement without
+       * the timer expired, we don't open the lock.
+       */
+      if(!timer_expired(&codelock_timer)) {
+        printf("Key pressed during final wait, code lock locked again.\n");
+      } else {
+
+        /*
+         * If the timer expired, we'll open the lock and exit from the
+         * protothread.
+         */
+        printf("Code lock unlocked.\n");
+        PT_EXIT(pt);
+      }
+    }
+  }
+
+  /*
+   * Finally, we'll mark the end of the protothread.
+   */
+  PT_END(pt);
+}
+/*---------------------------------------------------------------------------*/
+/*
+ * This is the second protothread in this example. It implements a
+ * simulated user pressing the keys. This illustrates how a linear
+ * sequence of timed instructions can be implemented with
+ * protothreads.
+ */
+static
+PT_THREAD(input_thread(struct pt *pt))
+{
+  PT_BEGIN(pt);
+
+  printf("Waiting 1 second before entering first key.\n");
+  
+  timer_set(&input_timer, 1000);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+
+  press_key('1');
+  
+  timer_set(&input_timer, 100);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  press_key('2');
+
+  timer_set(&input_timer, 100);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  press_key('3');
+
+  timer_set(&input_timer, 2000);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  press_key('1');
+
+  timer_set(&input_timer, 200);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  press_key('4');
+
+  timer_set(&input_timer, 200);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  press_key('2');
+  
+  timer_set(&input_timer, 2000);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  press_key('3');
+
+  timer_set(&input_timer, 200);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  press_key('1');
+
+  timer_set(&input_timer, 200);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  press_key('4');
+
+  timer_set(&input_timer, 200);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  press_key('2');
+  
+  timer_set(&input_timer, 100);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  press_key('3');
+
+  timer_set(&input_timer, 100);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  press_key('4');
+
+  timer_set(&input_timer, 1500);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  press_key('1');
+
+  timer_set(&input_timer, 300);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  press_key('4');
+
+  timer_set(&input_timer, 400);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  press_key('2');
+
+  timer_set(&input_timer, 500);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  press_key('3');
+
+  timer_set(&input_timer, 2000);
+  PT_WAIT_UNTIL(pt, timer_expired(&input_timer));
+  
+  PT_END(pt);
+}
+/*---------------------------------------------------------------------------*/
+/*
+ * This is the main function. It initializes the two protothread
+ * control structures and schedules the two protothreads. The main
+ * function returns when the protothread the runs the code lock exits.
+ */
+int
+main(void)
+{
+  /*
+   * Initialize the two protothread control structures.
+   */
+  PT_INIT(&input_pt);
+  PT_INIT(&codelock_pt);
+
+  /*
+   * Schedule the two protothreads until the codelock_thread() exits.
+   */
+  while(PT_SCHEDULE(codelock_thread(&codelock_pt))) {
+    PT_SCHEDULE(input_thread(&input_pt));
+    
+    /*
+     * When running this example on a multitasking system, we must
+     * give other processes a chance to run too and therefore we call
+     * usleep() resp. Sleep() here. On a dedicated embedded system,
+     * we usually do not need to do this.
+     */
+#ifdef _WIN32
+    Sleep(0);
+#else
+    usleep(10);
+#endif
+  }
+
+  return 0;
+}
+/*---------------------------------------------------------------------------*/
+/*
+ * Finally, the implementation of the simple timer library follows.
+ */
+#ifdef _WIN32
+
+static int clock_time(void)
+{ return (int)GetTickCount(); }
+
+#else /* _WIN32 */
+
+static int clock_time(void)
+{
+  struct timeval tv;
+  struct timezone tz;   
+  gettimeofday(&tv, &tz); 
+  return tv.tv_sec * 1000 + tv.tv_usec / 1000;
+}
+
+#endif /* _WIN32 */
+
+static int timer_expired(struct timer *t)
+{ return (int)(clock_time() - t->start) >= (int)t->interval; }
+
+static void timer_set(struct timer *t, int interval)
+{ t->interval = interval; t->start = clock_time(); }
+/*---------------------------------------------------------------------------*/
+

+The bounded buffer with protothread semaphores

+The following example shows how to implement the bounded buffer problem using the protothreads semaphore library. The example uses three protothreads: one producer() protothread that produces items, one consumer() protothread that consumes items, and one driver_thread() that schedules the producer and consumer protothreads.

+Note that there is no need for a mutex to guard the add_to_buffer() and get_from_buffer() functions because of the implicit locking semantics of protothreads - a protothread will never be preempted and will never block except in an explicit PT_WAIT statement.

+

/*
+ * 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 protothreads library.
+ *
+ * Author: Adam Dunkels <adam@sics.se>
+ *
+ * $Id: example-buffer.c,v 1.5 2005/10/07 05:21:33 adam Exp $
+ */
+
+#ifdef _WIN32
+#include <windows.h>
+#else
+#include <unistd.h>
+#endif
+#include <stdio.h>
+
+#include "pt-sem.h"
+ 
+#define NUM_ITEMS 32
+#define BUFSIZE 8
+
+static int buffer[BUFSIZE];
+static int bufptr;
+
+static void
+add_to_buffer(int item)
+{
+  printf("Item %d added to buffer at place %d\n", item, bufptr);  
+  buffer[bufptr] = item;
+  bufptr = (bufptr + 1) % BUFSIZE;
+}
+static int
+get_from_buffer(void)
+{
+  int item;
+  item = buffer[bufptr];
+  printf("Item %d retrieved from buffer at place %d\n",
+         item, bufptr);
+  bufptr = (bufptr + 1) % BUFSIZE;
+  return item;
+}
+
+static int
+produce_item(void)
+{
+  static int item = 0;
+  printf("Item %d produced\n", item);
+  return item++;
+}
+
+static void
+consume_item(int item)
+{
+  printf("Item %d consumed\n", item);
+}
+
+static struct pt_sem full, empty;
+ 
+static 
+PT_THREAD(producer(struct pt *pt))
+{
+  static int produced;
+  
+  PT_BEGIN(pt);
+  
+  for(produced = 0; produced < NUM_ITEMS; ++produced) {
+  
+    PT_SEM_WAIT(pt, &full);
+    
+    add_to_buffer(produce_item());
+    
+    PT_SEM_SIGNAL(pt, &empty);
+  }
+
+  PT_END(pt);
+}
+ 
+static 
+PT_THREAD(consumer(struct pt *pt))
+{
+  static int consumed;
+  
+  PT_BEGIN(pt);
+ 
+  for(consumed = 0; consumed < NUM_ITEMS; ++consumed) {
+    
+    PT_SEM_WAIT(pt, &empty);
+    
+    consume_item(get_from_buffer());    
+    
+    PT_SEM_SIGNAL(pt, &full);
+  }
+ 
+  PT_END(pt);
+}
+ 
+static 
+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_INIT(&pt_producer);
+  PT_INIT(&pt_consumer);
+ 
+  PT_WAIT_THREAD(pt, producer(&pt_producer) &
+                     consumer(&pt_consumer));
+ 
+  PT_END(pt);
+}
+
+
+int
+main(void)
+{
+  struct pt driver_pt;
+
+  PT_INIT(&driver_pt);
+
+  while(PT_SCHEDULE(driver_thread(&driver_pt))) {
+
+    /*
+     * When running this example on a multitasking system, we must
+     * give other processes a chance to run too and therefore we call
+     * usleep() resp. Sleep() here. On a dedicated embedded system,
+     * we usually do not need to do this.
+     */
+#ifdef _WIN32
+    Sleep(0);
+#else
+    usleep(10);
+#endif
+  }
+  return 0;
+}
+
+

+ + +
+

Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/a00016.html b/doc/html/a00016.html new file mode 100644 index 0000000..743f2bd --- /dev/null +++ b/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
+ + diff --git a/doc/html/a00017.html b/doc/html/a00017.html new file mode 100644 index 0000000..9a37968 --- /dev/null +++ b/doc/html/a00017.html @@ -0,0 +1,226 @@ + + +The Protothreads Library 1.4: Local continuations + + + + +
+
+

Local continuations
+ +[Protothreads] +

Detailed Description

+Local continuations form the basis for implementing protothreads. +

+A local continuation can be set in a specific function to capture the state of the function. After a local continuation has been set can be resumed in order to restore the state of the function at the point where the local continuation was set. +

+ + + + + + + +

+

+ + + +

+

+ + + +

+

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

Files

file  lc.h
 Local continuations.
file  lc-switch.h
 Implementation of local continuations based on switch() statment.
file  lc-addrlabels.h
 Implementation of local continuations based on the "Labels as values" feature of gcc.

Defines

#define LC_INIT(lc)
 Initialize a local continuation.
#define LC_SET(lc)
 Set a local continuation.
#define LC_RESUME(lc)
 Resume a local continuation.
#define LC_END(lc)
 Mark the end of local continuation usage.
+#define LC_INIT(s)   s = 0;
+#define LC_RESUME(s)   switch(s) { case 0:
+#define LC_SET(s)   s = __LINE__; case __LINE__:
+#define LC_END(s)   }
+#define LC_INIT(s)   s = NULL
+#define LC_RESUME(s)
+#define LC_CONCAT2(s1, s2)   s1##s2
+#define LC_CONCAT(s1, s2)   LC_CONCAT2(s1, s2)
+#define LC_SET(s)
+#define LC_END(s)

Typedefs

+typedef unsigned short lc_t
 The local continuation type.
+typedef void * lc_t
+

Define Documentation

+

+ + + + +
+ + + + + + + + + +
#define LC_END ( lc   ) 
+
+ + + + + +
+   + + +

+Mark the end of local continuation usage. +

+The end operation signifies that local continuations should not be used any more in the function. This operation is not needed for most implementations of local continuation, but is required by a few implementations. +

+Definition at line 108 of file lc.h.

+

+ + + + +
+ + + + + + + + + +
#define LC_INIT ( lc   ) 
+
+ + + + + +
+   + + +

+Initialize a local continuation. +

+This operation initializes the local continuation, thereby unsetting any previously set continuation state. +

+Definition at line 71 of file lc.h.

+

+ + + + +
+ + + + + + + + + +
#define LC_RESUME ( lc   ) 
+
+ + + + + +
+   + + +

+Resume a local continuation. +

+The resume operation resumes a previously set local continuation, thus restoring the state in which the function was when the local continuation was set. If the local continuation has not been previously set, the resume operation does nothing. +

+Definition at line 96 of file lc.h.

+

+ + + + +
+ + + + + + + + + +
#define LC_SET ( lc   ) 
+
+ + + + + +
+   + + +

+Set a local continuation. +

+The set operation saves the state of the function at the point where the operation is executed. As far as the set operation is concerned, the state of the function does not include the call-stack or local (automatic) variables, but only the program counter and such CPU registers that needs to be saved. +

+Definition at line 84 of file lc.h.

+

Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/a00018.html b/doc/html/a00018.html new file mode 100644 index 0000000..8f20cba --- /dev/null +++ b/doc/html/a00018.html @@ -0,0 +1,109 @@ + + +The Protothreads Library 1.4: lc-addrlabels.h Source File + + + + +
+
+
+
+

lc-addrlabels.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: lc-addrlabels.h,v 1.4 2006/06/03 11:29:43 adam Exp $
+00034  */
+00035 
+00036 /**
+00037  * \addtogroup lc
+00038  * @{
+00039  */
+00040 
+00041 /**
+00042  * \file
+00043  * Implementation of local continuations based on the "Labels as
+00044  * values" feature of gcc
+00045  * \author
+00046  * Adam Dunkels <adam@sics.se>
+00047  *
+00048  * This implementation of local continuations is based on a special
+00049  * feature of the GCC C compiler called "labels as values". This
+00050  * feature allows assigning pointers with the address of the code
+00051  * corresponding to a particular C label.
+00052  *
+00053  * For more information, see the GCC documentation:
+00054  * http://gcc.gnu.org/onlinedocs/gcc/Labels-as-Values.html
+00055  *
+00056  */
+00057 
+00058 #ifndef __LC_ADDRLABELS_H__
+00059 #define __LC_ADDRLABELS_H__
+00060 
+00061 /** \hideinitializer */
+00062 typedef void * lc_t;
+00063 
+00064 #define LC_INIT(s) s = NULL
+00065 
+00066 #define LC_RESUME(s)                            \
+00067   do {                                          \
+00068     if(s != NULL) {                             \
+00069       goto *s;                                  \
+00070     }                                           \
+00071   } while(0)
+00072 
+00073 #define LC_CONCAT2(s1, s2) s1##s2
+00074 #define LC_CONCAT(s1, s2) LC_CONCAT2(s1, s2)
+00075 
+00076 #define LC_SET(s)                               \
+00077   do {                                          \
+00078     LC_CONCAT(LC_LABEL, __LINE__):              \
+00079     (s) = &&LC_CONCAT(LC_LABEL, __LINE__);      \
+00080   } while(0)
+00081 
+00082 #define LC_END(s)
+00083 
+00084 #endif /* __LC_ADDRLABELS_H__ */
+00085 /** @} */
+
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/a00019.html b/doc/html/a00019.html new file mode 100644 index 0000000..a443882 --- /dev/null +++ b/doc/html/a00019.html @@ -0,0 +1,100 @@ + + +The Protothreads Library 1.4: lc-switch.h Source File + + + + +
+
+
+
+

lc-switch.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: lc-switch.h,v 1.4 2006/06/03 11:29:43 adam Exp $
+00034  */
+00035 
+00036 /**
+00037  * \addtogroup lc
+00038  * @{
+00039  */
+00040 
+00041 /**
+00042  * \file
+00043  * Implementation of local continuations based on switch() statment
+00044  * \author Adam Dunkels <adam@sics.se>
+00045  *
+00046  * This implementation of local continuations uses the C switch()
+00047  * statement to resume execution of a function somewhere inside the
+00048  * function's body. The implementation is based on the fact that
+00049  * switch() statements are able to jump directly into the bodies of
+00050  * control structures such as if() or while() statmenets.
+00051  *
+00052  * This implementation borrows heavily from Simon Tatham's coroutines
+00053  * implementation in C:
+00054  * http://www.chiark.greenend.org.uk/~sgtatham/coroutines.html
+00055  */
+00056 
+00057 #ifndef __LC_SWITCH_H__
+00058 #define __LC_SWITCH_H__
+00059 
+00060 /* WARNING! lc implementation using switch() does not work if an
+00061    LC_SET() is done within another switch() statement! */
+00062 
+00063 /** \hideinitializer */
+00064 typedef unsigned short lc_t;
+00065 
+00066 #define LC_INIT(s) s = 0;
+00067 
+00068 #define LC_RESUME(s) switch(s) { case 0:
+00069 
+00070 #define LC_SET(s) s = __LINE__; case __LINE__:
+00071 
+00072 #define LC_END(s) }
+00073 
+00074 #endif /* __LC_SWITCH_H__ */
+00075 
+00076 /** @} */
+
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/a00020.html b/doc/html/a00020.html new file mode 100644 index 0000000..0381a4c --- /dev/null +++ b/doc/html/a00020.html @@ -0,0 +1,156 @@ + + +The Protothreads Library 1.4: lc.h Source File + + + + +
+
+
+
+

lc.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 protothreads library.
+00030  * 
+00031  * Author: Adam Dunkels <adam@sics.se>
+00032  *
+00033  * $Id: lc.h,v 1.2 2005/02/24 10:36:59 adam Exp $
+00034  */
+00035 
+00036 /**
+00037  * \addtogroup pt
+00038  * @{
+00039  */
+00040 
+00041 /**
+00042  * \defgroup lc Local continuations
+00043  * @{
+00044  *
+00045  * Local continuations form the basis for implementing protothreads. A
+00046  * local continuation can be <i>set</i> in a specific function to
+00047  * capture the state of the function. After a local continuation has
+00048  * been set can be <i>resumed</i> in order to restore the state of the
+00049  * function at the point where the local continuation was set.
+00050  *
+00051  *
+00052  */
+00053 
+00054 /**
+00055  * \file lc.h
+00056  * Local continuations
+00057  * \author
+00058  * Adam Dunkels <adam@sics.se>
+00059  *
+00060  */
+00061 
+00062 #ifdef DOXYGEN
+00063 /**
+00064  * Initialize a local continuation.
+00065  *
+00066  * This operation initializes the local continuation, thereby
+00067  * unsetting any previously set continuation state.
+00068  *
+00069  * \hideinitializer
+00070  */
+00071 #define LC_INIT(lc)
+00072 
+00073 /**
+00074  * Set a local continuation.
+00075  *
+00076  * The set operation saves the state of the function at the point
+00077  * where the operation is executed. As far as the set operation is
+00078  * concerned, the state of the function does <b>not</b> include the
+00079  * call-stack or local (automatic) variables, but only the program
+00080  * counter and such CPU registers that needs to be saved.
+00081  *
+00082  * \hideinitializer
+00083  */
+00084 #define LC_SET(lc)
+00085 
+00086 /**
+00087  * Resume a local continuation.
+00088  *
+00089  * The resume operation resumes a previously set local continuation, thus
+00090  * restoring the state in which the function was when the local
+00091  * continuation was set. If the local continuation has not been
+00092  * previously set, the resume operation does nothing.
+00093  *
+00094  * \hideinitializer
+00095  */
+00096 #define LC_RESUME(lc)
+00097 
+00098 /**
+00099  * Mark the end of local continuation usage.
+00100  *
+00101  * The end operation signifies that local continuations should not be
+00102  * used any more in the function. This operation is not needed for
+00103  * most implementations of local continuation, but is required by a
+00104  * few implementations.
+00105  *
+00106  * \hideinitializer 
+00107  */
+00108 #define LC_END(lc)
+00109 
+00110 /**
+00111  * \var typedef lc_t;
+00112  *
+00113  * The local continuation type.
+00114  *
+00115  * \hideinitializer
+00116  */
+00117 #endif /* DOXYGEN */
+00118 
+00119 #ifndef __LC_H__
+00120 #define __LC_H__
+00121 
+00122 
+00123 #ifdef LC_INCLUDE
+00124 #include LC_INCLUDE
+00125 #else
+00126 #include "lc-switch.h"
+00127 #endif /* LC_INCLUDE */
+00128 
+00129 #endif /* __LC_H__ */
+00130 
+00131 /** @} */
+00132 /** @} */
+
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/a00021.html b/doc/html/a00021.html new file mode 100644 index 0000000..1c4f116 --- /dev/null +++ b/doc/html/a00021.html @@ -0,0 +1,252 @@ + + +The Protothreads Library 1.4: pt-sem.h Source File + + + + +
+
+
+
+

pt-sem.h

Go to the documentation of this file.
00001 /*
+00002  * Copyright (c) 2004, 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 protothreads library.
+00030  * 
+00031  * Author: Adam Dunkels <adam@sics.se>
+00032  *
+00033  * $Id: pt-sem.h,v 1.2 2005/02/24 10:36:59 adam Exp $
+00034  */
+00035 
+00036 /**
+00037  * \addtogroup pt
+00038  * @{
+00039  */
+00040 
+00041 /**
+00042  * \defgroup ptsem Protothread semaphores
+00043  * @{
+00044  *
+00045  * This module implements counting semaphores on top of
+00046  * protothreads. Semaphores are a synchronization primitive that
+00047  * provide two operations: "wait" and "signal". The "wait" operation
+00048  * checks the semaphore counter and blocks the thread if the counter
+00049  * is zero. The "signal" operation increases the semaphore counter but
+00050  * does not block. If another thread has blocked waiting for the
+00051  * semaphore that is signalled, the blocked thread will become
+00052  * runnable again.
+00053  *
+00054  * Semaphores can be used to implement other, more structured,
+00055  * synchronization primitives such as monitors and message
+00056  * queues/bounded buffers (see below).
+00057  *
+00058  * The following example shows how the producer-consumer problem, also
+00059  * known as the bounded buffer problem, can be solved using
+00060  * protothreads and semaphores. Notes on the program follow after the
+00061  * example.
+00062  *
+00063  \code
+00064 #include "pt-sem.h"
+00065 
+00066 #define NUM_ITEMS 32
+00067 #define BUFSIZE 8
+00068 
+00069 static struct pt_sem mutex, full, empty;
+00070 
+00071 PT_THREAD(producer(struct pt *pt))
+00072 {
+00073   static int produced;
+00074   
+00075   PT_BEGIN(pt);
+00076   
+00077   for(produced = 0; produced < NUM_ITEMS; ++produced) {
+00078   
+00079     PT_SEM_WAIT(pt, &full);
+00080     
+00081     PT_SEM_WAIT(pt, &mutex);
+00082     add_to_buffer(produce_item());    
+00083     PT_SEM_SIGNAL(pt, &mutex);
+00084     
+00085     PT_SEM_SIGNAL(pt, &empty);
+00086   }
+00087 
+00088   PT_END(pt);
+00089 }
+00090 
+00091 PT_THREAD(consumer(struct pt *pt))
+00092 {
+00093   static int consumed;
+00094   
+00095   PT_BEGIN(pt);
+00096 
+00097   for(consumed = 0; consumed < NUM_ITEMS; ++consumed) {
+00098     
+00099     PT_SEM_WAIT(pt, &empty);
+00100     
+00101     PT_SEM_WAIT(pt, &mutex);    
+00102     consume_item(get_from_buffer());    
+00103     PT_SEM_SIGNAL(pt, &mutex);
+00104     
+00105     PT_SEM_SIGNAL(pt, &full);
+00106   }
+00107 
+00108   PT_END(pt);
+00109 }
+00110 
+00111 PT_THREAD(driver_thread(struct pt *pt))
+00112 {
+00113   static struct pt pt_producer, pt_consumer;
+00114 
+00115   PT_BEGIN(pt);
+00116   
+00117   PT_SEM_INIT(&empty, 0);
+00118   PT_SEM_INIT(&full, BUFSIZE);
+00119   PT_SEM_INIT(&mutex, 1);
+00120 
+00121   PT_INIT(&pt_producer);
+00122   PT_INIT(&pt_consumer);
+00123 
+00124   PT_WAIT_THREAD(pt, producer(&pt_producer) &
+00125                      consumer(&pt_consumer));
+00126 
+00127   PT_END(pt);
+00128 }
+00129  \endcode
+00130  *
+00131  * The program uses three protothreads: one protothread that
+00132  * implements the consumer, one thread that implements the producer,
+00133  * and one protothread that drives the two other protothreads. The
+00134  * program uses three semaphores: "full", "empty" and "mutex". The
+00135  * "mutex" semaphore is used to provide mutual exclusion for the
+00136  * buffer, the "empty" semaphore is used to block the consumer is the
+00137  * buffer is empty, and the "full" semaphore is used to block the
+00138  * producer is the buffer is full.
+00139  *
+00140  * The "driver_thread" holds two protothread state variables,
+00141  * "pt_producer" and "pt_consumer". It is important to note that both
+00142  * these variables are declared as <i>static</i>. If the static
+00143  * keyword is not used, both variables are stored on the stack. Since
+00144  * protothreads do not store the stack, these variables may be
+00145  * overwritten during a protothread wait operation. Similarly, both
+00146  * the "consumer" and "producer" protothreads declare their local
+00147  * variables as static, to avoid them being stored on the stack.
+00148  * 
+00149  *
+00150  */
+00151    
+00152 /**
+00153  * \file
+00154  * Couting semaphores implemented on protothreads
+00155  * \author
+00156  * Adam Dunkels <adam@sics.se>
+00157  *
+00158  */
+00159 
+00160 #ifndef __PT_SEM_H__
+00161 #define __PT_SEM_H__
+00162 
+00163 #include "pt.h"
+00164 
+00165 struct pt_sem {
+00166   unsigned int count;
+00167 };
+00168 
+00169 /**
+00170  * Initialize a semaphore
+00171  *
+00172  * This macro initializes a semaphore with a value for the
+00173  * counter. Internally, the semaphores use an "unsigned int" to
+00174  * represent the counter, and therefore the "count" argument should be
+00175  * within range of an unsigned int.
+00176  *
+00177  * \param s (struct pt_sem *) A pointer to the pt_sem struct
+00178  * representing the semaphore
+00179  *
+00180  * \param c (unsigned int) The initial count of the semaphore.
+00181  * \hideinitializer
+00182  */
+00183 #define PT_SEM_INIT(s, c) (s)->count = c
+00184 
+00185 /**
+00186  * Wait for a semaphore
+00187  *
+00188  * This macro carries out the "wait" operation on the semaphore. The
+00189  * wait operation causes the protothread to block while the counter is
+00190  * zero. When the counter reaches a value larger than zero, the
+00191  * protothread will continue.
+00192  *
+00193  * \param pt (struct pt *) A pointer to the protothread (struct pt) in
+00194  * which the operation is executed.
+00195  *
+00196  * \param s (struct pt_sem *) A pointer to the pt_sem struct
+00197  * representing the semaphore
+00198  *
+00199  * \hideinitializer
+00200  */
+00201 #define PT_SEM_WAIT(pt, s)      \
+00202   do {                                          \
+00203     PT_WAIT_UNTIL(pt, (s)->count > 0);          \
+00204     --(s)->count;                               \
+00205   } while(0)
+00206 
+00207 /**
+00208  * Signal a semaphore
+00209  *
+00210  * This macro carries out the "signal" operation on the semaphore. The
+00211  * signal operation increments the counter inside the semaphore, which
+00212  * eventually will cause waiting protothreads to continue executing.
+00213  *
+00214  * \param pt (struct pt *) A pointer to the protothread (struct pt) in
+00215  * which the operation is executed.
+00216  *
+00217  * \param s (struct pt_sem *) A pointer to the pt_sem struct
+00218  * representing the semaphore
+00219  *
+00220  * \hideinitializer
+00221  */
+00222 #define PT_SEM_SIGNAL(pt, s) ++(s)->count
+00223 
+00224 #endif /* __PT_SEM_H__ */
+00225 
+00226 /** @} */
+00227 /** @} */
+00228    
+
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/a00022.html b/doc/html/a00022.html new file mode 100644 index 0000000..ceb6716 --- /dev/null +++ b/doc/html/a00022.html @@ -0,0 +1,347 @@ + + +The Protothreads Library 1.4: pt.h Source File + + + + +
+
+
+
+

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 /** @} */
+
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/annotated.html b/doc/html/annotated.html new file mode 100644 index 0000000..461fec4 --- /dev/null +++ b/doc/html/annotated.html @@ -0,0 +1,29 @@ + + +The Protothreads Library 1.4: Data Structures + + + + +
+
+
+
+

The Protothreads Library 1.4 Data Structures

Here are the data structures with brief descriptions: + + +
pt
pt_sem
+
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/doxygen.css b/doc/html/doxygen.css new file mode 100644 index 0000000..05615b2 --- /dev/null +++ b/doc/html/doxygen.css @@ -0,0 +1,310 @@ +BODY,H1,H2,H3,H4,H5,H6,P,CENTER,TD,TH,UL,DL,DIV { + font-family: Geneva, Arial, Helvetica, sans-serif; +} +BODY,TD { + font-size: 90%; +} +H1 { + text-align: center; + font-size: 160%; +} +H2 { + font-size: 120%; +} +H3 { + font-size: 100%; +} +CAPTION { font-weight: bold } +DIV.qindex { + width: 100%; + background-color: #e8eef2; + border: 1px solid #84b0c7; + text-align: center; + margin: 2px; + padding: 2px; + line-height: 140%; +} +DIV.nav { + width: 100%; + background-color: #e8eef2; + border: 1px solid #84b0c7; + text-align: center; + margin: 2px; + padding: 2px; + line-height: 140%; +} +DIV.navtab { + background-color: #e8eef2; + border: 1px solid #84b0c7; + text-align: center; + margin: 2px; + margin-right: 15px; + padding: 2px; +} +TD.navtab { + font-size: 70%; +} +A.qindex { + text-decoration: none; + font-weight: bold; + color: #1A419D; +} +A.qindex:visited { + text-decoration: none; + font-weight: bold; + color: #1A419D +} +A.qindex:hover { + text-decoration: none; + background-color: #ddddff; +} +A.qindexHL { + text-decoration: none; + font-weight: bold; + background-color: #6666cc; + color: #ffffff; + border: 1px double #9295C2; +} +A.qindexHL:hover { + text-decoration: none; + background-color: #6666cc; + color: #ffffff; +} +A.qindexHL:visited { text-decoration: none; background-color: #6666cc; color: #ffffff } +A.el { text-decoration: none; font-weight: bold } +A.elRef { font-weight: bold } +A.code:link { text-decoration: none; font-weight: normal; color: #0000FF} +A.code:visited { text-decoration: none; font-weight: normal; color: #0000FF} +A.codeRef:link { font-weight: normal; color: #0000FF} +A.codeRef:visited { font-weight: normal; color: #0000FF} +A:hover { text-decoration: none; background-color: #f2f2ff } +DL.el { margin-left: -1cm } +.fragment { + font-family: Fixed, monospace; + font-size: 95%; +} +PRE.fragment { + border: 1px solid #CCCCCC; + background-color: #f5f5f5; + margin-top: 4px; + margin-bottom: 4px; + margin-left: 2px; + margin-right: 8px; + padding-left: 6px; + padding-right: 6px; + padding-top: 4px; + padding-bottom: 4px; +} +DIV.ah { background-color: black; font-weight: bold; color: #ffffff; margin-bottom: 3px; margin-top: 3px } +TD.md { background-color: #F4F4FB; font-weight: bold; } +TD.mdPrefix { + background-color: #F4F4FB; + color: #606060; + font-size: 80%; +} +TD.mdname1 { background-color: #F4F4FB; font-weight: bold; color: #602020; } +TD.mdname { background-color: #F4F4FB; font-weight: bold; color: #602020; width: 600px; } +DIV.groupHeader { + margin-left: 16px; + margin-top: 12px; + margin-bottom: 6px; + font-weight: bold; +} +DIV.groupText { margin-left: 16px; font-style: italic; font-size: 90% } +BODY { + background: white; + color: black; + margin-right: 20px; + margin-left: 20px; +} +TD.indexkey { + background-color: #e8eef2; + font-weight: bold; + padding-right : 10px; + padding-top : 2px; + padding-left : 10px; + padding-bottom : 2px; + margin-left : 0px; + margin-right : 0px; + margin-top : 2px; + margin-bottom : 2px; + border: 1px solid #CCCCCC; +} +TD.indexvalue { + background-color: #e8eef2; + font-style: italic; + padding-right : 10px; + padding-top : 2px; + padding-left : 10px; + padding-bottom : 2px; + margin-left : 0px; + margin-right : 0px; + margin-top : 2px; + margin-bottom : 2px; + border: 1px solid #CCCCCC; +} +TR.memlist { + background-color: #f0f0f0; +} +P.formulaDsp { text-align: center; } +IMG.formulaDsp { } +IMG.formulaInl { vertical-align: middle; } +SPAN.keyword { color: #008000 } +SPAN.keywordtype { color: #604020 } +SPAN.keywordflow { color: #e08000 } +SPAN.comment { color: #800000 } +SPAN.preprocessor { color: #806020 } +SPAN.stringliteral { color: #002080 } +SPAN.charliteral { color: #008080 } +.mdTable { + border: 1px solid #868686; + background-color: #F4F4FB; +} +.mdRow { + padding: 8px 10px; +} +.mdescLeft { + padding: 0px 8px 4px 8px; + font-size: 80%; + font-style: italic; + background-color: #FAFAFA; + border-top: 1px none #E0E0E0; + border-right: 1px none #E0E0E0; + border-bottom: 1px none #E0E0E0; + border-left: 1px none #E0E0E0; + margin: 0px; +} +.mdescRight { + padding: 0px 8px 4px 8px; + font-size: 80%; + font-style: italic; + background-color: #FAFAFA; + border-top: 1px none #E0E0E0; + border-right: 1px none #E0E0E0; + border-bottom: 1px none #E0E0E0; + border-left: 1px none #E0E0E0; + margin: 0px; +} +.memItemLeft { + padding: 1px 0px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: solid; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + background-color: #FAFAFA; + font-size: 80%; +} +.memItemRight { + padding: 1px 8px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: solid; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + background-color: #FAFAFA; + font-size: 80%; +} +.memTemplItemLeft { + padding: 1px 0px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: none; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + background-color: #FAFAFA; + font-size: 80%; +} +.memTemplItemRight { + padding: 1px 8px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: none; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + background-color: #FAFAFA; + font-size: 80%; +} +.memTemplParams { + padding: 1px 0px 0px 8px; + margin: 4px; + border-top-width: 1px; + border-right-width: 1px; + border-bottom-width: 1px; + border-left-width: 1px; + border-top-color: #E0E0E0; + border-right-color: #E0E0E0; + border-bottom-color: #E0E0E0; + border-left-color: #E0E0E0; + border-top-style: solid; + border-right-style: none; + border-bottom-style: none; + border-left-style: none; + color: #606060; + background-color: #FAFAFA; + font-size: 80%; +} +.search { color: #003399; + font-weight: bold; +} +FORM.search { + margin-bottom: 0px; + margin-top: 0px; +} +INPUT.search { font-size: 75%; + color: #000080; + font-weight: normal; + background-color: #e8eef2; +} +TD.tiny { font-size: 75%; +} +a { + color: #1A41A8; +} +a:visited { + color: #2A3798; +} +.dirtab { padding: 4px; + border-collapse: collapse; + border: 1px solid #84b0c7; +} +TH.dirtab { background: #e8eef2; + font-weight: bold; +} +HR { height: 1px; + border: none; + border-top: 1px solid black; +} + diff --git a/doc/html/doxygen.png b/doc/html/doxygen.png new file mode 100644 index 0000000..f0a274b Binary files /dev/null and b/doc/html/doxygen.png differ diff --git a/doc/html/files.html b/doc/html/files.html new file mode 100644 index 0000000..bdb9c7f --- /dev/null +++ b/doc/html/files.html @@ -0,0 +1,31 @@ + + +The Protothreads Library 1.4: File Index + + + + +
+
+
+
+

The Protothreads Library 1.4 File List

Here is a list of all documented files with brief descriptions: + + + + + +
lc-addrlabels.h [code]Implementation of local continuations based on the "Labels as values" feature of gcc
lc-switch.h [code]Implementation of local continuations based on switch() statment
lc.h [code]Local continuations
pt-sem.h [code]Couting semaphores implemented on protothreads
pt.h [code]Protothreads implementation
+
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/ftv2blank.png b/doc/html/ftv2blank.png new file mode 100644 index 0000000..493c3c0 Binary files /dev/null and b/doc/html/ftv2blank.png differ diff --git a/doc/html/ftv2doc.png b/doc/html/ftv2doc.png new file mode 100644 index 0000000..f72999f Binary files /dev/null and b/doc/html/ftv2doc.png differ diff --git a/doc/html/ftv2folderclosed.png b/doc/html/ftv2folderclosed.png new file mode 100644 index 0000000..d6d0634 Binary files /dev/null and b/doc/html/ftv2folderclosed.png differ diff --git a/doc/html/ftv2folderopen.png b/doc/html/ftv2folderopen.png new file mode 100644 index 0000000..bbe2c91 Binary files /dev/null and b/doc/html/ftv2folderopen.png differ diff --git a/doc/html/ftv2lastnode.png b/doc/html/ftv2lastnode.png new file mode 100644 index 0000000..e7b9ba9 Binary files /dev/null and b/doc/html/ftv2lastnode.png differ diff --git a/doc/html/ftv2link.png b/doc/html/ftv2link.png new file mode 100644 index 0000000..14f3fed Binary files /dev/null and b/doc/html/ftv2link.png differ diff --git a/doc/html/ftv2mlastnode.png b/doc/html/ftv2mlastnode.png new file mode 100644 index 0000000..09ceb6a Binary files /dev/null and b/doc/html/ftv2mlastnode.png differ diff --git a/doc/html/ftv2mnode.png b/doc/html/ftv2mnode.png new file mode 100644 index 0000000..3254c05 Binary files /dev/null and b/doc/html/ftv2mnode.png differ diff --git a/doc/html/ftv2node.png b/doc/html/ftv2node.png new file mode 100644 index 0000000..c9f06a5 Binary files /dev/null and b/doc/html/ftv2node.png differ diff --git a/doc/html/ftv2plastnode.png b/doc/html/ftv2plastnode.png new file mode 100644 index 0000000..0b07e00 Binary files /dev/null and b/doc/html/ftv2plastnode.png differ diff --git a/doc/html/ftv2pnode.png b/doc/html/ftv2pnode.png new file mode 100644 index 0000000..2001b79 Binary files /dev/null and b/doc/html/ftv2pnode.png differ diff --git a/doc/html/ftv2vertline.png b/doc/html/ftv2vertline.png new file mode 100644 index 0000000..b330f3a Binary files /dev/null and b/doc/html/ftv2vertline.png differ diff --git a/doc/html/functions.html b/doc/html/functions.html new file mode 100644 index 0000000..fd14c80 --- /dev/null +++ b/doc/html/functions.html @@ -0,0 +1,37 @@ + + +The Protothreads Library 1.4: Data Fields + + + + +
+
+
+
+
+ +
+Here is a list of all documented struct and union fields with links to the struct/union documentation for each field: +

+

+
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/functions_vars.html b/doc/html/functions_vars.html new file mode 100644 index 0000000..11f2c17 --- /dev/null +++ b/doc/html/functions_vars.html @@ -0,0 +1,37 @@ + + +The Protothreads Library 1.4: Data Fields - Variables + + + + +
+
+
+
+
+ +
+  +

+

+
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/globals.html b/doc/html/globals.html new file mode 100644 index 0000000..4263758 --- /dev/null +++ b/doc/html/globals.html @@ -0,0 +1,62 @@ + + +The Protothreads Library 1.4: Data Fields + + + + +
+
+
+
+
+ +
+Here is a list of all documented functions, variables, defines, enums, and typedefs with links to the documentation: +

+

+
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/globals_defs.html b/doc/html/globals_defs.html new file mode 100644 index 0000000..e97df36 --- /dev/null +++ b/doc/html/globals_defs.html @@ -0,0 +1,61 @@ + + +The Protothreads Library 1.4: Data Fields + + + + +
+
+
+
+
+ +
+  +

+

+
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/globals_type.html b/doc/html/globals_type.html new file mode 100644 index 0000000..1cfd1df --- /dev/null +++ b/doc/html/globals_type.html @@ -0,0 +1,36 @@ + + +The Protothreads Library 1.4: Data Fields + + + + +
+
+
+
+
+ +
+  +

+

+
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/hierarchy.html b/doc/html/hierarchy.html new file mode 100644 index 0000000..1a654ba --- /dev/null +++ b/doc/html/hierarchy.html @@ -0,0 +1,29 @@ + + +The Protothreads Library 1.4: Hierarchical Index + + + + +
+
+
+
+

The Protothreads Library 1.4 Class Hierarchy

This inheritance list is sorted roughly, but not completely, alphabetically: +
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/index.hhc b/doc/html/index.hhc new file mode 100644 index 0000000..7e0f7f4 --- /dev/null +++ b/doc/html/index.hhc @@ -0,0 +1,43 @@ + + + + + + diff --git a/doc/html/index.hhk b/doc/html/index.hhk new file mode 100644 index 0000000..837b6f0 --- /dev/null +++ b/doc/html/index.hhk @@ -0,0 +1,56 @@ + + + + + + diff --git a/doc/html/index.hhp b/doc/html/index.hhp new file mode 100644 index 0000000..071ac3d --- /dev/null +++ b/doc/html/index.hhp @@ -0,0 +1,44 @@ +[OPTIONS] +Compatibility=1.1 +Full-text search=Yes +Contents file=index.hhc +Default Window=main +Default topic=main.html +Index file=index.hhk +Language=0x409 English (United States) +Title=The Protothreads Library 1.4 + +[WINDOWS] +main="The Protothreads Library 1.4","index.hhc","index.hhk","main.html","main.html",,,,,0x23520,,0x387e,,,,,,,,0 + +[FILES] +main.html +files.html +a00018.html +a00019.html +a00020.html +a00021.html +a00022.html +a00009.html +a00010.html +a00011.html +a00012.html +a00013.html +annotated.html +hierarchy.html +functions.html +functions_vars.html +a00005.html +a00006.html +a00014.html +a00015.html +a00016.html +a00017.html +modules.html +globals.html +globals_type.html +globals_defs.html +tabs.css +tab_b.gif +tab_l.gif +tab_r.gif diff --git a/doc/html/index.html b/doc/html/index.html new file mode 100644 index 0000000..a0bcca8 --- /dev/null +++ b/doc/html/index.html @@ -0,0 +1,8 @@ + + +The Protothreads Library 1.4 + + + + + diff --git a/doc/html/main.html b/doc/html/main.html new file mode 100644 index 0000000..d539dbc --- /dev/null +++ b/doc/html/main.html @@ -0,0 +1,81 @@ + + +The Protothreads Library 1.4: The Protothreads Library + + + + +
+
+

The Protothreads Library

+

+

Author:
Adam Dunkels <adam@sics.se>
+Protothreads are a type of lightweight stackless threads designed for severly memory constrained systems such as deeply embedded systems or sensor network nodes. Protothreads provides linear code execution for event-driven systems implemented in C. Protothreads can be used with or without an RTOS.

+Protothreads are a extremely lightweight, stackless type of threads that provides a blocking context on top of an event-driven system, without the overhead of per-thread stacks. The purpose of protothreads is to implement sequential flow of control without complex state machines or full multi-threading. Protothreads provides conditional blocking inside C functions.

+Main features:

+

+

+

+

+

+

+

+

+

+

+Examples applications:

+

+

+

+

+

+

+

+

+

See also:
Example programs

+Protothreads API documentation

+The protothreads library is released under a BSD-style license that allows for both non-commercial and commercial usage. The only requirement is that credit is given.

+More information and new version of the code can be found at the Protothreads homepage:

+http://www.sics.se/~adam/pt/

+Authors

+The protothreads library was written by Adam Dunkels <adam@sics.se> with support from Oliver Schmidt <ol.sc@web.de>.

+Using protothreads

+Using protothreads in a project is easy: simply copy the files pt.h, lc.h and lc-switch.h into the include files directory of the project, and #include "pt.h" in all files that should use protothreads.

+Protothreads

+Protothreads are a extremely lightweight, stackless threads that provides a blocking context on top of an event-driven system, without the overhead of per-thread stacks. The purpose of protothreads is to implement sequential flow of control without using complex state machines or full multi-threading. Protothreads provides conditional blocking inside a C function.

+In memory constrained systems, such as deeply embedded systems, traditional multi-threading may have a too large memory overhead. In traditional multi-threading, each thread requires its own stack, that typically is over-provisioned. The stacks may use large parts of the available memory.

+The main advantage of protothreads over ordinary threads is that protothreads are very lightweight: a protothread does not require its own stack. Rather, all protothreads run on the same stack and context switching is done by stack rewinding. This is advantageous in memory constrained systems, where a stack for a thread might use a large part of the available memory. A protothread only requires only two bytes of memory per protothread. Moreover, protothreads are implemented in pure C and do not require any machine-specific assembler code.

+A protothread runs within a single C function and cannot span over other functions. A protothread may call normal C functions, but cannot block inside a called function. Blocking inside nested function calls is instead made by spawning a separate protothread for each potentially blocking function. The advantage of this approach is that blocking is explicit: the programmer knows exactly which functions that block that which functions the never blocks.

+Protothreads are similar to asymmetric co-routines. The main difference is that co-routines uses a separate stack for each co-routine, whereas protothreads are stackless. The most similar mechanism to protothreads are Python generators. These are also stackless constructs, but have a different purpose. Protothreads provides blocking contexts inside a C function, whereas Python generators provide multiple exit points from a generator function.

+Local variables

+
Note:
Because protothreads do not save the stack context across a blocking call, local variables are not preserved when the protothread blocks. This means that local variables should be used with utmost care - if in doubt, do not use local variables inside a protothread!
+

+Scheduling

+A protothread is driven by repeated calls to the function in which the protothread is running. Each time the function is called, the protothread will run until it blocks or exits. Thus the scheduling of protothreads is done by the application that uses protothreads.

+Implementation

+Protothreads are implemented using local continuations. A local continuation represents the current state of execution at a particular place in the program, but does not provide any call history or local variables. A local continuation can be set in a specific function to capture the state of the function. After a local continuation has been set can be resumed in order to restore the state of the function at the point where the local continuation was set.

+Local continuations can be implemented in a variety of ways:

+

    +
  1. by using machine specific assembler code,
  2. by using standard C constructs, or
  3. by using compiler extensions.
+

+The first way works by saving and restoring the processor state, except for stack pointers, and requires between 16 and 32 bytes of memory per protothread. The exact amount of memory required depends on the architecture.

+The standard C implementation requires only two bytes of state per protothread and utilizes the C switch() statement in a non-obvious way that is similar to Duff's device. This implementation does, however, impose a slight restriction to the code that uses protothreads: a protothread cannot perform a blocking wait (PT_WAIT_UNTIL() or PT_YIELD()) inside a switch() statement.

+Certain compilers has C extensions that can be used to implement protothreads. GCC supports label pointers that can be used for this purpose. With this implementation, protothreads require 4 bytes of RAM per protothread.

Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/modules.html b/doc/html/modules.html new file mode 100644 index 0000000..dcc1841 --- /dev/null +++ b/doc/html/modules.html @@ -0,0 +1,27 @@ + + +The Protothreads Library 1.4: Module Index + + + + +
+
+

The Protothreads Library 1.4 Modules

Here is a list of all modules: +
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by  + +doxygen 1.4.6
+ + diff --git a/doc/html/tab_b.gif b/doc/html/tab_b.gif new file mode 100644 index 0000000..0d62348 Binary files /dev/null and b/doc/html/tab_b.gif differ diff --git a/doc/html/tab_l.gif b/doc/html/tab_l.gif new file mode 100644 index 0000000..9b1e633 Binary files /dev/null and b/doc/html/tab_l.gif differ diff --git a/doc/html/tab_r.gif b/doc/html/tab_r.gif new file mode 100644 index 0000000..ce9dd9f Binary files /dev/null and b/doc/html/tab_r.gif differ diff --git a/doc/html/tabs.css b/doc/html/tabs.css new file mode 100644 index 0000000..a61552a --- /dev/null +++ b/doc/html/tabs.css @@ -0,0 +1,102 @@ +/* tabs styles, based on http://www.alistapart.com/articles/slidingdoors */ + +DIV.tabs +{ + float : left; + width : 100%; + background : url("tab_b.gif") repeat-x bottom; + margin-bottom : 4px; +} + +DIV.tabs UL +{ + margin : 0px; + padding-left : 10px; + list-style : none; +} + +DIV.tabs LI, DIV.tabs FORM +{ + display : inline; + margin : 0px; + padding : 0px; +} + +DIV.tabs FORM +{ + float : right; +} + +DIV.tabs A +{ + float : left; + background : url("tab_r.gif") no-repeat right top; + border-bottom : 1px solid #84B0C7; + font-size : x-small; + font-weight : bold; + text-decoration : none; +} + +DIV.tabs A:hover +{ + background-position: 100% -150px; +} + +DIV.tabs A:link, DIV.tabs A:visited, +DIV.tabs A:active, DIV.tabs A:hover +{ + color: #1A419D; +} + +DIV.tabs SPAN +{ + float : left; + display : block; + background : url("tab_l.gif") no-repeat left top; + padding : 5px 9px; + white-space : nowrap; +} + +DIV.tabs INPUT +{ + float : right; + display : inline; + font-size : 1em; +} + +DIV.tabs TD +{ + font-size : x-small; + font-weight : bold; + text-decoration : none; +} + + + +/* Commented Backslash Hack hides rule from IE5-Mac \*/ +DIV.tabs SPAN {float : none;} +/* End IE5-Mac hack */ + +DIV.tabs A:hover SPAN +{ + background-position: 0% -150px; +} + +DIV.tabs LI#current A +{ + background-position: 100% -150px; + border-width : 0px; +} + +DIV.tabs LI#current SPAN +{ + background-position: 0% -150px; + padding-bottom : 6px; +} + +DIV.nav +{ + background : none; + border : none; + border-bottom : 1px solid #84B0C7; +} diff --git a/doc/html/tree.html b/doc/html/tree.html new file mode 100644 index 0000000..be8ac5d --- /dev/null +++ b/doc/html/tree.html @@ -0,0 +1,108 @@ + + + + + + + TreeView + + + + + +
+

The Protothreads Library 1.4

+
+

o*The Protothreads Library

+

o+File List

+ +

o+Data Structures

+
+

|o*pt

+

|\*pt_sem

+
+

o+Class Hierarchy

+
+

|o*pt

+

|\*pt_sem

+
+

o*Data Fields

+

o+Modules

+ +

\*Globals

+
+
+ + diff --git a/doc/pt-doc.txt b/doc/pt-doc.txt new file mode 100644 index 0000000..2d6742e --- /dev/null +++ b/doc/pt-doc.txt @@ -0,0 +1,58 @@ +/** +\defgroup pt Protothreads +@{ +Protothreads are implemented in a single header file, pt.h, which +includes the local continuations header file, lc.h. This file in turn +includes the actual implementation of local continuations, which +typically also is contained in a single header file. + +*/ + +/** @} */ + +/** +\defgroup examples Examples +@{ + +\section example-small A small example + +This first example shows a very simple program: two protothreads +waiting for each other to toggle two flags. The code illustrates how +to write protothreads code, how to initialize protothreads, and how to +schedule them. + +\include example-small.c + + +\section example-code-lock A code-lock +This example shows how to implement a simple code lock - the kind of +device that is placed next to doors and that you have to push a four +digit number into in order to unlock the door. + +The code lock waits for key presses from a numeric keyboard and if the +correct code is entered, the lock is unlocked. There is a maximum time +of one second between each key press, and after the correct code has +been entered, no more keys must be pressed for 0.5 seconds before the +lock is opened. + +\include example-codelock.c + +\section example-buffer The bounded buffer with protothread semaphores + +The following example shows how to implement the bounded buffer +problem using the protothreads semaphore library. The example uses +three protothreads: one producer() protothread that produces items, +one consumer() protothread that consumes items, and one +driver_thread() that schedules the producer and consumer protothreads. + +Note that there is no need for a mutex to guard the add_to_buffer() +and get_from_buffer() functions because of the implicit locking +semantics of protothreads - a protothread will never be preempted and +will never block except in an explicit PT_WAIT statement. + +\include example-buffer.c + +*/ + + +/** @} */ diff --git a/doc/pt-mainpage.txt b/doc/pt-mainpage.txt new file mode 100644 index 0000000..60eb016 --- /dev/null +++ b/doc/pt-mainpage.txt @@ -0,0 +1,156 @@ +/** + +\mainpage The Protothreads Library + +\author Adam Dunkels + +Protothreads are a type of lightweight stackless threads designed for +severly memory constrained systems such as deeply embedded systems or +sensor network nodes. Protothreads provides linear code execution for +event-driven systems implemented in C. Protothreads can be used with +or without an RTOS. + +Protothreads are a extremely lightweight, stackless type of threads +that provides a blocking context on top of an event-driven system, +without the overhead of per-thread stacks. The purpose of protothreads +is to implement sequential flow of control without complex state +machines or full multi-threading. Protothreads provides conditional +blocking inside C functions. + +Main features: + + - No machine specific code - the protothreads library is pure C + + - Does not use error-prone functions such as longjmp() + + - Very small RAM overhead - only two bytes per protothread + + - Can be used with or without an OS + + - Provides blocking wait without full multi-threading or + stack-switching + +Examples applications: + + - Memory constrained systems + + - Event-driven protocol stacks + + - Deeply embedded systems + + - Sensor network nodes + + +\sa \ref examples "Example programs" +\sa \ref pt "Protothreads API documentation" + +The protothreads library is released under a BSD-style license that +allows for both non-commercial and commercial usage. The only +requirement is that credit is given. + +More information and new version of the code can be found at the +Protothreads homepage: + + http://www.sics.se/~adam/pt/ + +\section authors Authors + +The protothreads library was written by Adam Dunkels +with support from Oliver Schmidt . + +\section using Using protothreads + +Using protothreads in a project is easy: simply copy the files pt.h, +lc.h and lc-switch.h into the include files directory of the project, +and \#include "pt.h" in all files that should use protothreads. + +\section pt-desc Protothreads + +Protothreads are a extremely lightweight, stackless threads that +provides a blocking context on top of an event-driven system, without +the overhead of per-thread stacks. The purpose of protothreads is to +implement sequential flow of control without using complex state +machines or full multi-threading. Protothreads provides conditional +blocking inside a C function. + +In memory constrained systems, such as deeply embedded systems, +traditional multi-threading may have a too large memory overhead. In +traditional multi-threading, each thread requires its own stack, that +typically is over-provisioned. The stacks may use large parts of the +available memory. + +The main advantage of protothreads over ordinary threads is that +protothreads are very lightweight: a protothread does not require its +own stack. Rather, all protothreads run on the same stack and context +switching is done by stack rewinding. This is advantageous in memory +constrained systems, where a stack for a thread might use a large part +of the available memory. A protothread only requires only two bytes of +memory per protothread. Moreover, protothreads are implemented in pure +C and do not require any machine-specific assembler code. + +A protothread runs within a single C function and cannot span over +other functions. A protothread may call normal C functions, but cannot +block inside a called function. Blocking inside nested function calls +is instead made by spawning a separate protothread for each +potentially blocking function. The advantage of this approach is that +blocking is explicit: the programmer knows exactly which functions +that block that which functions the never blocks. + +Protothreads are similar to asymmetric co-routines. The main +difference is that co-routines uses a separate stack for each +co-routine, whereas protothreads are stackless. The most similar +mechanism to protothreads are Python generators. These are also +stackless constructs, but have a different purpose. Protothreads +provides blocking contexts inside a C function, whereas Python +generators provide multiple exit points from a generator function. + +\section pt-autovars Local variables + +\note +Because protothreads do not save the stack context across a blocking +call, local variables are not preserved when the protothread +blocks. This means that local variables should be used with utmost +care - if in doubt, do not use local variables inside a protothread! + +\section pt-scheduling Scheduling + +A protothread is driven by repeated calls to the function in which the +protothread is running. Each time the function is called, the +protothread will run until it blocks or exits. Thus the scheduling of +protothreads is done by the application that uses protothreads. + +\section pt-impl Implementation + +Protothreads are implemented using local continuations. A local +continuation represents the current state of execution at a particular +place in the program, but does not provide any call history or local +variables. A local continuation can be set in a specific function to +capture the state of the function. After a local continuation has been +set can be resumed in order to restore the state of the function at +the point where the local continuation was set. + + +Local continuations can be implemented in a variety of ways: + + -# by using machine specific assembler code, + -# by using standard C constructs, or + -# by using compiler extensions. + +The first way works by saving and restoring the processor state, +except for stack pointers, and requires between 16 and 32 bytes of +memory per protothread. The exact amount of memory required depends on +the architecture. + +The standard C implementation requires only two bytes of state per +protothread and utilizes the C switch() statement in a non-obvious way +that is similar to Duff's device. This implementation does, however, +impose a slight restriction to the code that uses protothreads: a +protothread cannot perform a blocking wait (PT_WAIT_UNTIL() or +PT_YIELD()) inside a switch() statement. + +Certain compilers has C extensions that can be used to implement +protothreads. GCC supports label pointers that can be used for this +purpose. With this implementation, protothreads require 4 bytes of RAM +per protothread. + +*/ diff --git a/doc/pt-refman.pdf b/doc/pt-refman.pdf new file mode 100644 index 0000000..2ee4db0 Binary files /dev/null and b/doc/pt-refman.pdf differ diff --git a/doc/sicslogo.pdf b/doc/sicslogo.pdf new file mode 100644 index 0000000..239a1bf Binary files /dev/null and b/doc/sicslogo.pdf differ diff --git a/example-buffer.c b/example-buffer.c new file mode 100644 index 0000000..44fa4a7 --- /dev/null +++ b/example-buffer.c @@ -0,0 +1,165 @@ +/* + * 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 protothreads library. + * + * Author: Adam Dunkels + * + * $Id: example-buffer.c,v 1.5 2005/10/07 05:21:33 adam Exp $ + */ + +#ifdef _WIN32 +#include +#else +#include +#endif +#include + +#include "pt-sem.h" + +#define NUM_ITEMS 32 +#define BUFSIZE 8 + +static int buffer[BUFSIZE]; +static int bufptr; + +static void +add_to_buffer(int item) +{ + printf("Item %d added to buffer at place %d\n", item, bufptr); + buffer[bufptr] = item; + bufptr = (bufptr + 1) % BUFSIZE; +} +static int +get_from_buffer(void) +{ + int item; + item = buffer[bufptr]; + printf("Item %d retrieved from buffer at place %d\n", + item, bufptr); + bufptr = (bufptr + 1) % BUFSIZE; + return item; +} + +static int +produce_item(void) +{ + static int item = 0; + printf("Item %d produced\n", item); + return item++; +} + +static void +consume_item(int item) +{ + printf("Item %d consumed\n", item); +} + +static struct pt_sem full, empty; + +static +PT_THREAD(producer(struct pt *pt)) +{ + static int produced; + + PT_BEGIN(pt); + + for(produced = 0; produced < NUM_ITEMS; ++produced) { + + PT_SEM_WAIT(pt, &full); + + add_to_buffer(produce_item()); + + PT_SEM_SIGNAL(pt, &empty); + } + + PT_END(pt); +} + +static +PT_THREAD(consumer(struct pt *pt)) +{ + static int consumed; + + PT_BEGIN(pt); + + for(consumed = 0; consumed < NUM_ITEMS; ++consumed) { + + PT_SEM_WAIT(pt, &empty); + + consume_item(get_from_buffer()); + + PT_SEM_SIGNAL(pt, &full); + } + + PT_END(pt); +} + +static +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_INIT(&pt_producer); + PT_INIT(&pt_consumer); + + PT_WAIT_THREAD(pt, producer(&pt_producer) & + consumer(&pt_consumer)); + + PT_END(pt); +} + + +int +main(void) +{ + struct pt driver_pt; + + PT_INIT(&driver_pt); + + while(PT_SCHEDULE(driver_thread(&driver_pt))) { + + /* + * When running this example on a multitasking system, we must + * give other processes a chance to run too and therefore we call + * usleep() resp. Sleep() here. On a dedicated embedded system, + * we usually do not need to do this. + */ +#ifdef _WIN32 + Sleep(0); +#else + usleep(10); +#endif + } + return 0; +} diff --git a/example-codelock.c b/example-codelock.c new file mode 100644 index 0000000..cbeeb96 --- /dev/null +++ b/example-codelock.c @@ -0,0 +1,414 @@ +/* + * 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 protothreads library. + * + * Author: Adam Dunkels + * + * $Id: example-codelock.c,v 1.5 2005/10/06 07:57:08 adam Exp $ + */ + +/* + * + * This example shows how to implement a simple code lock. The code + * lock waits for key presses from a numeric keyboard and if the + * correct code is entered, the lock is unlocked. There is a maximum + * time of one second between each key press, and after the correct + * code has been entered, no more keys must be pressed for 0.5 seconds + * before the lock is opened. + * + * This is an example that shows two things: + * - how to implement a code lock key input mechanism, and + * - how to implement a sequential timed routine. + * + * The program consists of two protothreads, one that implements the + * code lock reader and one that implements simulated keyboard input. + * + * + */ + +#ifdef _WIN32 +#include +#else +#include +#include +#endif +#include + +#include "pt.h" + +/*---------------------------------------------------------------------------*/ +/* + * The following definitions are just for the simple timer library + * used in this example. The actual implementation of the functions + * can be found at the end of this file. + */ +struct timer { int start, interval; }; +static int timer_expired(struct timer *t); +static void timer_set(struct timer *t, int usecs); +/*---------------------------------------------------------------------------*/ +/* + * This example uses two timers: one for the code lock protothread and + * one for the simulated key input protothread. + */ +static struct timer codelock_timer, input_timer; +/*---------------------------------------------------------------------------*/ +/* + * This is the code that has to be entered. + */ +static const char code[4] = {'1', '4', '2', '3'}; +/*---------------------------------------------------------------------------*/ +/* + * This example has two protothread and therefor has two protothread + * control structures of type struct pt. These are initialized with + * PT_INIT() in the main() function below. + */ +static struct pt codelock_pt, input_pt; +/*---------------------------------------------------------------------------*/ +/* + * The following code implements a simple key input. Input is made + * with the press_key() function, and the function key_pressed() + * checks if a key has been pressed. The variable "key" holds the + * latest key that was pressed. The variable "key_pressed_flag" is set + * when a key is pressed and cleared when a key press is checked. + */ +static char key, key_pressed_flag; + +static void +press_key(char k) +{ + printf("--- Key '%c' pressed\n", k); + key = k; + key_pressed_flag = 1; +} + +static int +key_pressed(void) +{ + if(key_pressed_flag != 0) { + key_pressed_flag = 0; + return 1; + } + return 0; +} +/*---------------------------------------------------------------------------*/ +/* + * Declaration of the protothread function implementing the code lock + * logic. The protothread function is declared using the PT_THREAD() + * macro. The function is declared with the "static" keyword since it + * is local to this file. The name of the function is codelock_thread + * and it takes one argument, pt, of the type struct pt. + * + */ +static +PT_THREAD(codelock_thread(struct pt *pt)) +{ + /* This is a local variable that holds the number of keys that have + * been pressed. Note that it is declared with the "static" keyword + * to make sure that the variable is *not* allocated on the stack. + */ + static int keys; + + /* + * Declare the beginning of the protothread. + */ + PT_BEGIN(pt); + + /* + * We'll let the protothread loop until the protothread is + * expliticly exited with PT_EXIT(). + */ + while(1) { + + /* + * We'll be reading key presses until we get the right amount of + * correct keys. + */ + for(keys = 0; keys < sizeof(code); ++keys) { + + /* + * If we haven't gotten any keypresses, we'll simply wait for one. + */ + if(keys == 0) { + + /* + * The PT_WAIT_UNTIL() function will block until the condition + * key_pressed() is true. + */ + PT_WAIT_UNTIL(pt, key_pressed()); + } else { + + /* + * If the "key" variable was larger than zero, we have already + * gotten at least one correct key press. If so, we'll not + * only wait for the next key, but we'll also set a timer that + * expires in one second. This gives the person pressing the + * keys one second to press the next key in the code. + */ + timer_set(&codelock_timer, 1000); + + /* + * The following statement shows how complex blocking + * conditions can be easily expressed with protothreads and + * the PT_WAIT_UNTIL() function. + */ + PT_WAIT_UNTIL(pt, key_pressed() || timer_expired(&codelock_timer)); + + /* + * If the timer expired, we should break out of the for() loop + * and start reading keys from the beginning of the while(1) + * loop instead. + */ + if(timer_expired(&codelock_timer)) { + printf("Code lock timer expired.\n"); + + /* + * Break out from the for() loop and start from the + * beginning of the while(1) loop. + */ + break; + } + } + + /* + * Check if the pressed key was correct. + */ + if(key != code[keys]) { + printf("Incorrect key '%c' found\n", key); + /* + * Break out of the for() loop since the key was incorrect. + */ + break; + } else { + printf("Correct key '%c' found\n", key); + } + } + + /* + * Check if we have gotten all keys. + */ + if(keys == sizeof(code)) { + printf("Correct code entered, waiting for 500 ms before unlocking.\n"); + + /* + * Ok, we got the correct code. But to make sure that the code + * was not just a fluke of luck by an intruder, but the correct + * code entered by a person that knows the correct code, we'll + * wait for half a second before opening the lock. If another + * key is pressed during this time, we'll assume that it was a + * fluke of luck that the correct code was entered the first + * time. + */ + timer_set(&codelock_timer, 500); + PT_WAIT_UNTIL(pt, key_pressed() || timer_expired(&codelock_timer)); + + /* + * If we continued from the PT_WAIT_UNTIL() statement without + * the timer expired, we don't open the lock. + */ + if(!timer_expired(&codelock_timer)) { + printf("Key pressed during final wait, code lock locked again.\n"); + } else { + + /* + * If the timer expired, we'll open the lock and exit from the + * protothread. + */ + printf("Code lock unlocked.\n"); + PT_EXIT(pt); + } + } + } + + /* + * Finally, we'll mark the end of the protothread. + */ + PT_END(pt); +} +/*---------------------------------------------------------------------------*/ +/* + * This is the second protothread in this example. It implements a + * simulated user pressing the keys. This illustrates how a linear + * sequence of timed instructions can be implemented with + * protothreads. + */ +static +PT_THREAD(input_thread(struct pt *pt)) +{ + PT_BEGIN(pt); + + printf("Waiting 1 second before entering first key.\n"); + + timer_set(&input_timer, 1000); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('1'); + + timer_set(&input_timer, 100); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('2'); + + timer_set(&input_timer, 100); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('3'); + + timer_set(&input_timer, 2000); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('1'); + + timer_set(&input_timer, 200); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('4'); + + timer_set(&input_timer, 200); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('2'); + + timer_set(&input_timer, 2000); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('3'); + + timer_set(&input_timer, 200); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('1'); + + timer_set(&input_timer, 200); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('4'); + + timer_set(&input_timer, 200); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('2'); + + timer_set(&input_timer, 100); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('3'); + + timer_set(&input_timer, 100); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('4'); + + timer_set(&input_timer, 1500); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('1'); + + timer_set(&input_timer, 300); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('4'); + + timer_set(&input_timer, 400); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('2'); + + timer_set(&input_timer, 500); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + press_key('3'); + + timer_set(&input_timer, 2000); + PT_WAIT_UNTIL(pt, timer_expired(&input_timer)); + + PT_END(pt); +} +/*---------------------------------------------------------------------------*/ +/* + * This is the main function. It initializes the two protothread + * control structures and schedules the two protothreads. The main + * function returns when the protothread the runs the code lock exits. + */ +int +main(void) +{ + /* + * Initialize the two protothread control structures. + */ + PT_INIT(&input_pt); + PT_INIT(&codelock_pt); + + /* + * Schedule the two protothreads until the codelock_thread() exits. + */ + while(PT_SCHEDULE(codelock_thread(&codelock_pt))) { + PT_SCHEDULE(input_thread(&input_pt)); + + /* + * When running this example on a multitasking system, we must + * give other processes a chance to run too and therefore we call + * usleep() resp. Sleep() here. On a dedicated embedded system, + * we usually do not need to do this. + */ +#ifdef _WIN32 + Sleep(0); +#else + usleep(10); +#endif + } + + return 0; +} +/*---------------------------------------------------------------------------*/ +/* + * Finally, the implementation of the simple timer library follows. + */ +#ifdef _WIN32 + +static int clock_time(void) +{ return (int)GetTickCount(); } + +#else /* _WIN32 */ + +static int clock_time(void) +{ + struct timeval tv; + struct timezone tz; + gettimeofday(&tv, &tz); + return tv.tv_sec * 1000 + tv.tv_usec / 1000; +} + +#endif /* _WIN32 */ + +static int timer_expired(struct timer *t) +{ return (int)(clock_time() - t->start) >= (int)t->interval; } + +static void timer_set(struct timer *t, int interval) +{ t->interval = interval; t->start = clock_time(); } +/*---------------------------------------------------------------------------*/ diff --git a/example-small.c b/example-small.c new file mode 100644 index 0000000..37c1716 --- /dev/null +++ b/example-small.c @@ -0,0 +1,97 @@ +/** + * This is a very small example that shows how to use + * protothreads. The program consists of two protothreads that wait + * for each other to toggle a variable. + */ + +/* We must always include pt.h in our protothreads code. */ +#include "pt.h" + +#include /* For printf(). */ + +/* Two flags that the two protothread functions use. */ +static int protothread1_flag, protothread2_flag; + +/** + * The first protothread function. A protothread function must always + * return an integer, but must never explicitly return - returning is + * performed inside the protothread statements. + * + * The protothread function is driven by the main loop further down in + * the code. + */ +static int +protothread1(struct pt *pt) +{ + /* A protothread function must begin with PT_BEGIN() which takes a + pointer to a struct pt. */ + PT_BEGIN(pt); + + /* We loop forever here. */ + while(1) { + /* Wait until the other protothread has set its flag. */ + PT_WAIT_UNTIL(pt, protothread2_flag != 0); + printf("Protothread 1 running\n"); + + /* We then reset the other protothread's flag, and set our own + flag so that the other protothread can run. */ + protothread2_flag = 0; + protothread1_flag = 1; + + /* And we loop. */ + } + + /* All protothread functions must end with PT_END() which takes a + pointer to a struct pt. */ + PT_END(pt); +} + +/** + * The second protothread function. This is almost the same as the + * first one. + */ +static int +protothread2(struct pt *pt) +{ + PT_BEGIN(pt); + + while(1) { + /* Let the other protothread run. */ + protothread2_flag = 1; + + /* Wait until the other protothread has set its flag. */ + PT_WAIT_UNTIL(pt, protothread1_flag != 0); + printf("Protothread 2 running\n"); + + /* We then reset the other protothread's flag. */ + protothread1_flag = 0; + + /* And we loop. */ + } + PT_END(pt); +} + +/** + * Finally, we have the main loop. Here is where the protothreads are + * initialized and scheduled. First, however, we define the + * protothread state variables pt1 and pt2, which hold the state of + * the two protothreads. + */ +static struct pt pt1, pt2; +int +main(void) +{ + /* Initialize the protothread state variables with PT_INIT(). */ + PT_INIT(&pt1); + PT_INIT(&pt2); + + /* + * Then we schedule the two protothreads by repeatedly calling their + * protothread functions and passing a pointer to the protothread + * state variables as arguments. + */ + while(1) { + protothread1(&pt1); + protothread2(&pt2); + } +} diff --git a/lc-addrlabels.h b/lc-addrlabels.h new file mode 100644 index 0000000..3e6474e --- /dev/null +++ b/lc-addrlabels.h @@ -0,0 +1,85 @@ +/* + * 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 + * + * $Id: lc-addrlabels.h,v 1.4 2006/06/03 11:29:43 adam Exp $ + */ + +/** + * \addtogroup lc + * @{ + */ + +/** + * \file + * Implementation of local continuations based on the "Labels as + * values" feature of gcc + * \author + * Adam Dunkels + * + * This implementation of local continuations is based on a special + * feature of the GCC C compiler called "labels as values". This + * feature allows assigning pointers with the address of the code + * corresponding to a particular C label. + * + * For more information, see the GCC documentation: + * http://gcc.gnu.org/onlinedocs/gcc/Labels-as-Values.html + * + */ + +#ifndef __LC_ADDRLABELS_H__ +#define __LC_ADDRLABELS_H__ + +/** \hideinitializer */ +typedef void * lc_t; + +#define LC_INIT(s) s = NULL + +#define LC_RESUME(s) \ + do { \ + if(s != NULL) { \ + goto *s; \ + } \ + } while(0) + +#define LC_CONCAT2(s1, s2) s1##s2 +#define LC_CONCAT(s1, s2) LC_CONCAT2(s1, s2) + +#define LC_SET(s) \ + do { \ + LC_CONCAT(LC_LABEL, __LINE__): \ + (s) = &&LC_CONCAT(LC_LABEL, __LINE__); \ + } while(0) + +#define LC_END(s) + +#endif /* __LC_ADDRLABELS_H__ */ +/** @} */ diff --git a/lc-switch.h b/lc-switch.h new file mode 100644 index 0000000..dbdde01 --- /dev/null +++ b/lc-switch.h @@ -0,0 +1,76 @@ +/* + * 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 + * + * $Id: lc-switch.h,v 1.4 2006/06/03 11:29:43 adam Exp $ + */ + +/** + * \addtogroup lc + * @{ + */ + +/** + * \file + * Implementation of local continuations based on switch() statment + * \author Adam Dunkels + * + * This implementation of local continuations uses the C switch() + * statement to resume execution of a function somewhere inside the + * function's body. The implementation is based on the fact that + * switch() statements are able to jump directly into the bodies of + * control structures such as if() or while() statmenets. + * + * This implementation borrows heavily from Simon Tatham's coroutines + * implementation in C: + * http://www.chiark.greenend.org.uk/~sgtatham/coroutines.html + */ + +#ifndef __LC_SWITCH_H__ +#define __LC_SWITCH_H__ + +/* WARNING! lc implementation using switch() does not work if an + LC_SET() is done within another switch() statement! */ + +/** \hideinitializer */ +typedef unsigned short lc_t; + +#define LC_INIT(s) s = 0; + +#define LC_RESUME(s) switch(s) { case 0: + +#define LC_SET(s) s = __LINE__; case __LINE__: + +#define LC_END(s) } + +#endif /* __LC_SWITCH_H__ */ + +/** @} */ diff --git a/lc.h b/lc.h new file mode 100644 index 0000000..a965956 --- /dev/null +++ b/lc.h @@ -0,0 +1,132 @@ +/* + * 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 protothreads library. + * + * Author: Adam Dunkels + * + * $Id: lc.h,v 1.2 2005/02/24 10:36:59 adam Exp $ + */ + +/** + * \addtogroup pt + * @{ + */ + +/** + * \defgroup lc Local continuations + * @{ + * + * Local continuations form the basis for implementing protothreads. A + * local continuation can be set in a specific function to + * capture the state of the function. After a local continuation has + * been set can be resumed in order to restore the state of the + * function at the point where the local continuation was set. + * + * + */ + +/** + * \file lc.h + * Local continuations + * \author + * Adam Dunkels + * + */ + +#ifdef DOXYGEN +/** + * Initialize a local continuation. + * + * This operation initializes the local continuation, thereby + * unsetting any previously set continuation state. + * + * \hideinitializer + */ +#define LC_INIT(lc) + +/** + * Set a local continuation. + * + * The set operation saves the state of the function at the point + * where the operation is executed. As far as the set operation is + * concerned, the state of the function does not include the + * call-stack or local (automatic) variables, but only the program + * counter and such CPU registers that needs to be saved. + * + * \hideinitializer + */ +#define LC_SET(lc) + +/** + * Resume a local continuation. + * + * The resume operation resumes a previously set local continuation, thus + * restoring the state in which the function was when the local + * continuation was set. If the local continuation has not been + * previously set, the resume operation does nothing. + * + * \hideinitializer + */ +#define LC_RESUME(lc) + +/** + * Mark the end of local continuation usage. + * + * The end operation signifies that local continuations should not be + * used any more in the function. This operation is not needed for + * most implementations of local continuation, but is required by a + * few implementations. + * + * \hideinitializer + */ +#define LC_END(lc) + +/** + * \var typedef lc_t; + * + * The local continuation type. + * + * \hideinitializer + */ +#endif /* DOXYGEN */ + +#ifndef __LC_H__ +#define __LC_H__ + + +#ifdef LC_INCLUDE +#include LC_INCLUDE +#else +#include "lc-switch.h" +#endif /* LC_INCLUDE */ + +#endif /* __LC_H__ */ + +/** @} */ +/** @} */ diff --git a/pt-sem.h b/pt-sem.h new file mode 100644 index 0000000..98ae25d --- /dev/null +++ b/pt-sem.h @@ -0,0 +1,228 @@ +/* + * Copyright (c) 2004, 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 protothreads library. + * + * Author: Adam Dunkels + * + * $Id: pt-sem.h,v 1.2 2005/02/24 10:36:59 adam Exp $ + */ + +/** + * \addtogroup pt + * @{ + */ + +/** + * \defgroup ptsem Protothread semaphores + * @{ + * + * 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. + * + \code +#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); +} + \endcode + * + * 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. + * + * + */ + +/** + * \file + * Couting semaphores implemented on protothreads + * \author + * Adam Dunkels + * + */ + +#ifndef __PT_SEM_H__ +#define __PT_SEM_H__ + +#include "pt.h" + +struct pt_sem { + unsigned int count; +}; + +/** + * 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. + * + * \param s (struct pt_sem *) A pointer to the pt_sem struct + * representing the semaphore + * + * \param c (unsigned int) The initial count of the semaphore. + * \hideinitializer + */ +#define PT_SEM_INIT(s, c) (s)->count = c + +/** + * 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. + * + * \param pt (struct pt *) A pointer to the protothread (struct pt) in + * which the operation is executed. + * + * \param s (struct pt_sem *) A pointer to the pt_sem struct + * representing the semaphore + * + * \hideinitializer + */ +#define PT_SEM_WAIT(pt, s) \ + do { \ + PT_WAIT_UNTIL(pt, (s)->count > 0); \ + --(s)->count; \ + } while(0) + +/** + * 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. + * + * \param pt (struct pt *) A pointer to the protothread (struct pt) in + * which the operation is executed. + * + * \param s (struct pt_sem *) A pointer to the pt_sem struct + * representing the semaphore + * + * \hideinitializer + */ +#define PT_SEM_SIGNAL(pt, s) ++(s)->count + +#endif /* __PT_SEM_H__ */ + +/** @} */ +/** @} */ + diff --git a/pt.h b/pt.h new file mode 100644 index 0000000..7f20e40 --- /dev/null +++ b/pt.h @@ -0,0 +1,315 @@ +/* + * 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 + * + * $Id: pt.h,v 1.7 2006/10/02 07:52:56 adam Exp $ + */ + +/** + * \addtogroup pt + * @{ + */ + +/** + * \file + * Protothreads implementation. + * \author + * Adam Dunkels + * + */ + +#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 ³õʼ»¯ + * @{ + */ + +/** + * ³õʼ»¯protothreadÏß³Ì + * + * ³õʼ»¯protothreadÏ̡߳£³õʼ»¯±ØÐëÔÚ¿ªÊ¼Ö´ÐÐÔ­ÐÍÏß³Ì֮ǰÍê³É¡£ + * + * \param pt Ö¸ÏòprotothreadÏ߳̿ØÖƽṹµÄÖ¸Õë + * + * \sa PT_SPAWN() + * + * \hideinitializer + */ +#define PT_INIT(pt) LC_INIT((pt)->lc) + +/** @} */ + +/** + * \name ÉùÃ÷ºÍ¶¨Òå + * @{ + */ + +/** + * ÉùÃ÷protothreadÏ̡߳£ + * + * ´ËºêÓÃÓÚÉùÃ÷protothreadÏ̡߳£±ØÐëʹÓô˺êÉùÃ÷ËùÓÐprotothreadÏß³Ì + * + * \param name_args ʵÏÖprotothreadÏß³ÌµÄ C º¯ÊýµÄÃû³ÆºÍ²ÎÊý¡£ + * + * \hideinitializer + */ +#define PT_THREAD(name_args) char name_args + +/** + * ÔÚʵÏÖprotothreadÏß³ÌµÄ C º¯ÊýÖÐÉùÃ÷protothreadÏ̵߳ĿªÊ¼ + * + * ´ËºêÓÃÓÚÉùÃ÷protothreadÏ̵߳ÄÆðµã¡£ËüÓ¦¸Ã·ÅÔÚÔËÐÐprotothreadÏ̵߳ĺ¯ÊýµÄ¿ªÍ·¡£ + * ÿ´Îµ÷¶È protothread ʱ£¬¶¼½«Ö´ÐÐ PT_BEGIN£¨£© µ÷ÓÃÉÏ·½µÄËùÓÐ C Óï¾ä¡£ + * + * \param pt Ö¸ÏòÔ­ÐÍÏ߳̿ØÖƽṹµÄÖ¸Õë¡£ + * + * \hideinitializer + */ +#define PT_BEGIN(pt) { char PT_YIELD_FLAG = 1; LC_RESUME((pt)->lc) + +/** + * ÉùÃ÷Ô­ÐÍÏ̵߳ĽáÊø¡£ + * + * ´ËºêÓÃÓÚÉùÃ÷Ô­ÐÍÏ߳̽áÊø¡£Ëü±ØÐëʼÖÕÓëÆ¥ÅäµÄ PT_BEGIN£¨£© ºêÒ»ÆðʹÓᣠ+ * + * \param pt Ö¸ÏòÔ­ÐÍÏ߳̿ØÖƽṹµÄÖ¸Õë¡£ + * + * \hideinitializer + */ +#define PT_END(pt) LC_END((pt)->lc); PT_YIELD_FLAG = 0; \ + PT_INIT(pt); return PT_ENDED; } + +/** @} */ + +/** + * \name ×èÖ¹µÈ´ý + * @{ + */ + +/** + * ×èÖ¹²¢µÈ´ýÌõ¼þΪÕæ + * + * ´Ëºê»á×èÈûÔ­ÐÍỊ̈߳¬Ö±µ½Ö¸¶¨µÄÌõ¼þΪÕæ + * + * \param pt Ö¸ÏòÔ­ÐÍÏ߳̿ØÖƽṹµÄÖ¸Õë + * \param condition Ìõ¼þ¡£ + * + * \hideinitializer + */ +#define PT_WAIT_UNTIL(pt, condition) \ + do { \ + LC_SET((pt)->lc); \ + if(!(condition)) { \ + return PT_WAITING; \ + } \ + } while(0) + +/** + * ×èÖ¹²¢µÈ´ýÌõ¼þΪÕæ¡£ + * + * ´Ë¹¦ÄÜÔÚÌõ¼þΪÕæʱ×èÖ¹²¢µÈ´ý. See + * PT_WAIT_UNTIL(). + * + * \param pt Ö¸ÏòÔ­ÐÍÏ߳̿ØÖƽṹµÄÖ¸Õë + * \param cond Ìõ¼þ¡£ + * + * \hideinitializer + */ +#define PT_WAIT_WHILE(pt, cond) PT_WAIT_UNTIL((pt), !(cond)) + +/** @} */ + +/** + * \name ·Ö²ãÔ­ÐÍÏß³Ì + * @{ + */ + +/** + * ×èÖ¹²¢µÈ´ý×ÓÔ­ÐÍÏß³ÌÍê³É¡£ + * + * 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__ */ + +/** @} */