↑ arvau

Wikipedia / Setcontext

setcontext is one of a family of C library functionss (the others being getcontext, makecontext and swapcontext) used for context control. The setcontext family allows the implementation in C of advanced control flow patternss such as iterators, fibers, and coroutines. They may be viewed as an advanced version of setjmp/longjmp; whereas the latter allows only a single non-local jump up the stack, setcontext allows the creation of multiple cooperative threads of control, each with its own stack.

Specification

setcontext is specified in POSIX.1-2001 and the Single Unix Specification, version 2, but not all Unix-like operating systems provide them. POSIX.1-2004 obsoleted these functions, and in POSIX.1-2008 they are not included, with POSIX Threads indicated as a possible replacement.

Definitions

The functions and associated types are defined in the ucontext.h system header file. This includes the ucontext_t type, with which all four functions operate:

uc_link points to the context which will be resumed when the current context exits, if the context was created with makecontext (a secondary context). uc_sigmask is used to store the set of signalss blocked in the context, and uc_stack is the stack used by the context. uc_mcontext stores execution state, including all registers and CPU flagss, the instruction pointer, and the stack pointer; mcontext_t is an opaque type.

The functions are:

  1. This function transfers control to the context in ucp. Execution continues from the point at which the context was stored in ucp. setcontext does not return.

  2. Saves current context into ucp. This function returns in two possible cases: after the initial call, or when a thread switches to the context in ucp via setcontext or swapcontext. The getcontext function does not provide a return value to distinguish the cases (its return value is used solely to signal error), so the programmer must use an explicit flag variable, which must not be a register variable and must be declared volatile to avoid constant propagation or other compiler optimizations.

  3. The makecontext function sets up an alternate thread of control in ucp, which has previously been initialised using getcontext. The ucp.uc_stack member should be pointed to an appropriately sized stack; the constant SIGSTKSZ is commonly used. When ucp is jumped to using setcontext or swapcontext, execution will begin at the entry point to the function pointed to by func, with argc arguments as specified. When func terminates, control is returned to ucp.uc_link.

  4. Transfers control to ucp and saves the current execution state into oucp.

Example

The example below demonstrates an iterator using setcontext.

NOTE: this example is not correct, but may work as intended in some cases. The function makecontext requires additional parameters to be type int, but the example passes pointers. Thus, the example may fail on 64-bit machines (specifically LP64-architectures, where ). This problem can be worked around by breaking up and reconstructing 64-bit values, but that introduces a performance penalty.

For get and set context, a smaller context can be handy: This makes an infinite loop because context holds the program counter.

References