Protothreads
The Protothreads Library 1.3 Reference Manual
June 2006
Adam Dunkels
adam@sics.se
Swedish Institute of Computer Science
CONTENTS 1
Contents
1 The Protothreads Library 1
2 The Protothreads Library 1.4 Module Index 3
3 The Protothreads Library 1.4 Hierarchical Index 3
4 The Protothreads Library 1.4 Data Structure Index 4
5 The Protothreads Library 1.4 File Index 4
6 The Protothreads Library 1.4 Module Documentation 4
7 The Protothreads Library 1.4 Data Structure Documentation 25
8 The Protothreads Library 1.4 File Documentation 25
1 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:
• 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
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by Doxygen
1.1 Authors 2
• Deeply embedded systems
• Sensor network nodes
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/
1.1 Authors
The protothreads library was written by Adam Dunkels <adam@sics.se> with support from Oliver
Schmidt <
ol.sc@web.de>.
1.2 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.
1.3 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 imple-
ment 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.
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by Doxygen
1.4 Local variables 3
1.4 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!
1.5 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.
1.6 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 point-
ers that can be used for this purpose. With this implementation, protothreads require 4 bytes of RAM per
protothread.
2 The Protothreads Library 1.4 Module Index
2.1 The Protothreads Library 1.4 Modules
Here is a list of all modules:
Protothreads 4
Protothread semaphores 20
Local continuations 23
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by Doxygen
3 The Protothreads Library 1.4 Hierarchical Index 4
Examples 9
3 The Protothreads Library 1.4 Hierarchical Index
3.1 The Protothreads Library 1.4 Class Hierarchy
This inheritance list is sorted roughly, but not completely, alphabetically:
pt 25
pt_sem 25
4 The Protothreads Library 1.4 Data Structure Index
4.1 The Protothreads Library 1.4 Data Structures
Here are the data structures with brief descriptions:
pt 25
pt_sem 25
5 The Protothreads Library 1.4 File Index
5.1 The Protothreads Library 1.4 File List
Here is a list of all documented files with brief descriptions:
lc-addrlabels.h (Implementation of local continuations based on the "Labels as values" fea-
ture of gcc ) 25
lc-switch.h (Implementation of local continuations based on switch() statment ) 26
lc.h (Local continuations ) 26
pt-sem.h (Couting semaphores implemented on protothreads ) 27
pt.h (Protothreads implementation ) 27
6 The Protothreads Library 1.4 Module Documentation
6.1 Protothreads
6.1.1 Detailed Description
Protothreads are implemented in a single header file, pt.h, which includes the local continuations header
file, lc.h.
Generated on Mon Oct 2 10:06:29 2006 for The Protothreads Library 1.4 by Doxygen
