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