Portability Requirements for Coco

LuaJIT

# Portability Requirements for Coco

Coco needs some machine-specific features which are inherently non-portable. Although the coverage is pretty good, this means that Coco will probably never be a standard part of the Lua core (which is pure ANSI C).

## Context Switching Methods

Coco relies on four different machine-specific methods for allocating a C stack and switching context. The appropriate method is automatically selected at compile time.

### GCC Inline Assembler

This method is only available when GCC 3.x/4.x is used to compile the source. This is the fastest method for context switching, but only available for a few CPUs (see below).

### Modified setjmp Buffer

This method changes a few fields in the setjmp buffer to redirect the next longjmp to a new function with a new stack frame. It needs a bit of guesswork and lots of #ifdef's to handle the supported CPU/OS combinations, but this is quite manageable.

This is the fallback method if inline assembler is not available. It's pretty fast because it doesn't have to save or restore signals (which is slow and generally undesirable for Lua coroutines).

### POSIX ucontext

The POSIX calls getcontext, makecontext and switchcontext are used to set up and switch between different C stacks. Although highly portable and even available for some esoteric platforms, it's slower than the setjmp method because it saves and restores signals, too (using at least one syscall for each context switch).

You can force the use of ucontext (instead of setjmp) by enabling `-DCOCO_USE_UCONTEXT` in `src/Makefile`.

### Windows Fibers

This is the standard method to set up and switch between different C stacks on Windows. It's available on Windows 98 and later.

None of the other methods work for Windows because OS specific code is required to switch exception handling contexts.

## Supported Platforms

Coco has support for the following platforms:

CPU | System | Method
x86 | (any OS) | gccasm
x86 | Linux | setjmp
x86 | FreeBSD | setjmp
x86 | NetBSD | setjmp
x86 | OpenBSD | setjmp
x86 | Solaris | setjmp
x86 | Mac OS X | setjmp
x64 | Linux | setjmp
x64 | Solaris | setjmp
MIPS32 | (any OS) | gccasm
MIPS32 | Linux | setjmp
ARM | Linux | setjmp
PPC32 | Mac OS X | setjmp
(any CPU) | POSIX | ucontext
(any CPU) | Windows | fibers

It should work pretty much anywhere where a correct POSIX ucontext implementation is available. It has been tested on every systems I could get hold of (e.g. Sparc, PPC32/PPC64, IA64, Alpha, HPPA with various operating systems).

## Caveats

- Some older operating systems may have defective ucontext implementations because this feature is not widely used. E.g. some implementations don't mix well with other C library functions like `malloc()` or with native threads. This is really not the fault of Coco — please upgrade your OS.
- Note for Windows: Please read the explanation for the default » Thread Stack Size in case you want to create large numbers of Fiber-based coroutines.
- Note for MinGW/Cygwin: Older releases of GCC (before 4.0) generate wrong unwind information when `-fomit-frame-pointer` is used with stdcalls. This may lead to crashes when exceptions are thrown. The workaround is to always use two flags:
  `-fomit-frame-pointer -maccumulate-outgoing-args`.
- Note for MIPS CPUs without FPU: It's recommended to compile all sources with `-msoft-float`, even if you don't use any floating point ops anywhere. Otherwise context switching must save and restore FPU registers (which needs to go through the slow kernel emulation).
- To run Coco with » Valgrind (a memory debugger) you must add `-DUSE_VALGRIND` to `MYCFLAGS` and recompile. You will get random errors if you don't! Valgrind 3.x or later is required. Earlier versions do not work well with newly allocated C stacks.

Copyright © 2005-2008 Mike Pall · Contact