Awesome
<!--madoko Title : Libhandler Author : Daan Leijen Logo : True code { background-color: #EEE; } [TITLE] -->Overview
Warning: this library is still under active development and the API may change.
libhandler
implements algebraic effect handlers in C. It works by
capturing stacks in safe and portable manner. Algebraic effects
handlers can for example be used to program asynchronous code in
straightline manner and we hope to use it to make programming with
libuv
more convenient.
This library is described in detail in the accompanying technical report. For a primer on algebraic effects, see the relevant section in the koka book.
Enjoy!
-- Daan.
Building
Building libhandler
consists of generating a static C library that
can be linked in your own projects. libhandler
is written to be
as portable as possible but it depends on some platform specific
assumptions regarding stacks and setjmp
implementations. On new
platforms please test carefully. Currently tested platforms include:
-
(
gcc
,clang
,cl
)-x86-pc-windows
(32 bit, Windows) -
(
gcc
,clang
,cl
)-x64-pc-windows
(64 bit, Windows) -
(
gcc
,clang
)-amd64-pc-linux
(64 bit, Ubuntu 16.04) -
(
gcc
,clang
)-arm-linux
(32 bit, ARMv7 (raspberry pi 3, Raspbian/Debian Jessie)) -
gcc-arm64-linux
(64 bit, ARMv8 (raspberry pi 3, Gentoo Linux))
C++ support is working but still under development.
There is an initial test code for integrating with libuv
in the
test/libuv
directory (in the dev
branch). The Microsoft IDE solution
contains a project for building with libuv
.
Unix/MacOSX
Build using regular configure
and make
:
$ ./configure
$ make depend
$ make
Use VARIANT=release
to build a release version, and tests
as a target to run tests. For example:
$ make tests VARIANT=release
Configuration options:
--cc=<cc>
: Specify the c-compiler to use (e.g.gcc
,clang
, etc.)--cc-opts=<options>
: Specify extra c-compiler flags to use (e.g.-m64
).--asm-opts=<options>
: Specify extra assembler flags to use (e.g.-m64
).--abi=<abi>
: Specify the calling convention ABI. For example,--abi=amd64
or--abi=x64
.--os=<os>
: Specify the target OS, for example,--os=windows
.--ar=<archiver>
: Specify the archiver for creating a static library (=ar
).--cxx=<c++ compiler>
: Specify the C++ compiler to use (=$cc++
).--link=<linker>
: Specify the linker to use (=$cc
).
Make parameters:
VARIANT=
<debug
|testopt
|release
> : Specify the build variant.testopt
builds optimized but with assertions enabled.VALGRIND=1
: Run the tests under valgrind for memory leak detection.
Make targets:
staticlib
: Build a static library.tests
: Build and run tests.bench
: Build and run benchmarks.clean
: Clean all outputs.staticlibxx
: Build the library for C++ (with exception and destructor unwinding support).testsxx
: Build and run tests for C++.
Windows
There are three ways to build on Windows:
-
Use the Microsoft Visual C++ IDE. The 2015 Community edition is available for free for non-commercial use. The solution can be found at:
ide/msvc/libhandler.sln
-
Enable the "Linux subsystem" on Windows 10. See MSDN for installation instructions. Once enabled, you can simply run
bash
on the command prompt to enter Ubuntu Linux from Windows. Useapt
to install the development tools:sudo apt-get update
sudo apt install build-essential
sudo apt install clang
After this you can run
configure
andmake
as described above. -
On older Windows versions, you can use
msys2
, available at http://msys2.github.io. Please follow the installation instruction carefully. After install, you can install further tools using themsys2
package manager:pacman -S mingw-w64-x86_64-gcc
(c compiler)pacman -S mingw-w64-x86_64-gdb
(debugger)pacman -S make
(make)
After this you can run
configure
andmake
as described above.
Successful configurations bash
on Windows have been:
gcc-amd64-pc-linux-gnu
Using just./configure
clang-amd64-pc-linux-gnu
Usesudo apt install clang
followed by./configure --cc=clang
Successful configurations on Windows using msys2
have been:
gcc-x64-w64-mingw32
Using just./configure
gcc-x86-w64-mingw32
Using themingw32
shell withmingw-w64-i686-toolchain
installed.clang-x64-pc-windows
Using./configure --cc=/c/programs/llvm/bin/clang
.clang-x86-pc-windows
(32-bit)
Using./configure --cc=/c/programs/llvm/bin/clang --cc-opts=-m32 --asm-opts=-m32
.
Using the Visual Studio IDE:
cl-x64-pc-windows
Selecting 64-bit build.cl-x86-pc-windows
Selecting 32-bit build.
LibUV on Windows
Enabled in Visual Studio for x64 builds. You need to put the libuv
headers
and binaries in a libuv
folder under the main libhandler
folder. Binaries
for Windows can be found on libuv.org
.