A Context stores various information needed to produce the files with the C code derived from the inline C snippets.

Contexts can be composed with their Monoid instance, where mappend is right-biased -- in mappend x y y will take precedence over x.

Context useful to work with vanilla C. Used by default.

ctxTypesTable: converts C basic types to their counterparts in Foreign.C.Types.

No ctxAntiQuoters.

This Context adds support for ForeignPtr arguments. It adds a unique marshaller called fptr-ptr. For example, $fptr-ptr:(int *x) extracts the bare C pointer out of foreign pointer x.

This Context includes a AntiQuoter that removes the need for explicitely creating FunPtrs, named "fun" along with one which allocates new memory which must be manually freed named "fun-alloc".

For example, we can capture function f of type CInt -> CInt -> IO CInt in C code using $fun:(int (*f)(int, int)).

When used in a pure embedding, the Haskell function will have to be pure too. Continuing the example above we'll have CInt -> CInt -> IO CInt.

Does not include the baseCtx, since most of the time it's going to be included as part of larger contexts.

IMPORTANT: When using the fun anti quoter, one must be aware that the function pointer which is automatically generated is freed when the code contained in the block containing the anti quoter exits. Thus, if you need the function pointer to be longer-lived, you must allocate it and free it manually using freeHaskellFunPtr. We provide utilities to easily allocate them (see mkFunPtr).

IMPORTANT: When using the fun-alloc anti quoter, one must free the allocated function pointer. The GHC runtime provides a function to do this, hs_free_fun_ptr available in the h header.

This Context includes two AntiQuoters that allow to easily use Haskell vectors in C.

Specifically, the vec-len and vec-ptr will get the length and the pointer underlying mutable (IOVector) and immutable (Vector) storable vectors.

Note that if you use vecCtx to manipulate immutable vectors you must make sure that the vector is not modified in the C code.

To use vec-len, simply write $vec-len:x, where x is something of type IOVector a or Vector a, for some a. To use vec-ptr you need to specify the type of the pointer, e.g. $vec-len:(int *x) will work if x has type IOVector CInt.

bsCtx serves exactly the same purpose as vecCtx, but only for ByteString. vec-ptr becomes bs-ptr, and vec-len becomes bs-len. You don't need to specify the type of the pointer in bs-ptr, it will always be char*.

Moreover, bs-cstr works as bs-ptr but it provides a null-terminated copy of the given ByteString.

Sets the Context for the current module. This function, if called, must be called before any of the other TH functions in this module. Fails if that's not the case.

Define macros that can be used in the nested Template Haskell expression. Macros can be used as @MACRO_NAME(input) in inline-c quotes, and will transform their input with the given function. They can be useful for passing in types when defining Haskell instances for C++ template types.

Given a C type name, return the Haskell type in Template Haskell. The first parameter controls whether function pointers should be mapped as pure or IO functions.

C expressions.

Variant of exp, for use with expressions known to have no side effects.

BEWARE: Use this function with caution, only when you know what you are doing. If an expression does in fact have side-effects, then indiscriminate use of pure may endanger referential transparency, and in principle even type safety. Also note that the function might be called multiple times, given that unsafeDupablePerformIO is used to call the provided C code. Please refer to the documentation for unsafePerformIO for more details. unsafeDupablePerformIO is used to ensure good performance using the threaded runtime.

C code blocks (i.e. statements).

Emits a CPP include directive for C code associated with the current module. To avoid having to escape quotes, the function itself adds them when appropriate, so that

include "foo.h" ==> #include "foo.h"

but

include "<foo>" ==> #include <foo>

Emits an arbitrary C string to the C code associated with the current module. Use with care.

Like alloca, but also peeks the contents of the Ptr and returns them once the provided action has finished.

Type class with methods useful to allocate and peek multiple pointers at once:

withPtrs_ :: (Storable a, Storable b) => ((Ptr a, Ptr b) -> IO ()) -> IO (a, b)
withPtrs_ :: (Storable a, Storable b, Storable c) => ((Ptr a, Ptr b, Ptr c) -> IO ()) -> IO (a, b, c)
...

Easily get a FunPtr:

let fp :: FunPtr (Ptr CInt -> IO ()) = [C.funPtr| void poke42(int *ptr) { *ptr = 42; } |]

Especially useful to generate finalizers that require C code.

Most importantly, this allows you to write newForeignPtr invocations conveniently:

do
  let c_finalizer_funPtr =
        [C.funPtr| void myfree(char * ptr) { free(ptr); } |]
  fp <- newForeignPtr c_finalizer_funPtr objPtr

Using where possible newForeignPtr is superior to resorting to its delayed-by-a-thread alternative newForeignPtr from Foreign.Concurrent which takes an IO () Haskell finaliser action: With the non-concurrent newForeignPtr you can guarantee that the finaliser will actually be run

• when a GC is executed under memory pressure, because it can point directly to a C function that doesn't have to run any Haskell code (which is problematic when you're out of memory)
• when the program terminates (newForeignPtr's finaliser will likely NOT be called if your main thread exits, making your program e.g. not Valgrind-clean if your finaliser is free or C++'s delete).

funPtr makes the normal newForeignPtr as convenient as its concurrent counterpart.

$(mkFunPtr [t| CDouble -> IO CDouble |] generates a foreign import wrapper of type

(CDouble -> IO CDouble) -> IO (FunPtr (CDouble -> IO CDouble))

And invokes it.

$(mkFunPtrFromName 'foo), if foo :: CDouble -> IO CDouble, splices in an expression of type IO (FunPtr (CDouble -> IO CDouble)).

$(peekFunPtr [t| CDouble -> IO CDouble |]) generates a foreign import dynamic of type

FunPtr (CDouble -> IO CDouble) -> (CDouble -> IO CDouble)

And invokes it.