setcontext is one of a family of C library functions (the others being getcontext, makecontext and swapcontext) used for context control. setcontext et al allow the implementation in C of advanced control flow patterns such as iterators and coroutines. A C library is a collection of libraries used in programming with the C programming language. ... In computer science, an iterator is an object allowing one to sequence through all of the elements or parts contained in some other object, typically a container or list. ... In computer science, coroutines are program components that generalize subroutines to allow multiple entry points and suspending and resuming of execution at certain locations. ...

setcontext et al can be viewed as a more advanced version of setjmp/longjmp; where the latter just allows a single non-local jump up the stack, setcontext allows the creation of multiple coöperative threads of control, each with their own stack. The source is licensed under the GFDL, but has large invariant sections and cover texts. ...

Usage

The four function calls, along with the types ucontext_t and mcontext_t, are defined in <ucontext.h>.

The ucontext_t type stores execution state, including all registers and flags, the instruction pointer, and the stack pointer.

See below for an example of usage.

• setcontext(const ucontext_t *ucp): transfer control to the context in ucp. Does not return.
• getcontext(ucontext_t *ucp): store the current context into ucp. Will appear to return both after the initial call and whenever the context in ucp is jumped to; unfortunately, getcontext does not provide a return value to distinguish the cases, so the programmer must use a flag variable (defined volatile, and not a register variable, for obvious reasons).
• makecontext(ucontext_t *ucp, void *func(), int argc, ...): set up an alternate thread of control, to be stored in ucp (which should have been initialised with getcontext first). ucp.uc_stack should contain an appropriately sized stack. ucp will begin control at the entry point to func, which will be called with argc arguments as supplied. When func terminates, control will pass to ucp.uc_link.
• swapcontext(ucontext_t *oucp, ucontext_t *ucp): transfer control to ucp, saving the current execution state into oucp.

Specification

setcontext et al are described in the Single Unix Specification, version 2. Not all Unix-like operating systems have the functions, a fact which has possibly led to their being little-used. The Single UNIX Specification (SUS) is the collective name of a family of standards for computer operating systems to qualify for the name Unix. The SUS is developed and maintained by the Austin Group, based on earlier work by the IEEE and The Open Group. ...

Example

 #include <stdio.h> #include <stdlib.h> #include <ucontext.h> static void loop_iter (ucontext_t *my_ucp, ucontext_t *loop_ucp, int *yield_i) { int i; for (i = 0; i < 10; ++i) { *yield_i = i; swapcontext (my_ucp, loop_ucp); } } int main (void) { ucontext_t main_uc, loop_uc, iterator_uc; char iterator_stack[SIGSTKSZ]; volatile int has_run; volatile int yield_i; volatile const char *yield_path; iterator_uc.uc_link = &main_uc; iterator_uc.uc_stack.ss_sp = iterator_stack; iterator_uc.uc_stack.ss_size = sizeof iterator_stack; getcontext (&iterator_uc); makecontext (&iterator_uc, (void (*) (void)) loop_iter, 3, &iterator_uc, &loop_uc, &yield_i); has_run = 0; getcontext (&main_uc); if (!has_run) { has_run = 1; while (1) { swapcontext (&loop_uc, &iterator_uc); printf ("%dn", yield_i); } } return 0; } 

See also

• setjmp/longjmp

The source is licensed under the GFDL, but has large invariant sections and cover texts. ...

External links

• System V Contexts - The GNU C Library Manual