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 <adam@sics.se>
with support from Oliver Schmidt <ol.sc@web.de>.

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

\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
