# Haskell/FFI

* FFI (Solutions)
* General Practices
* Debugging
* Testing
* Packaging your software (Cabal)
* Using the Foreign Function Interface (FFI)
* Generic programming: Scrap your boilerplate
Using Haskell is fine, but in the real world there are a large number of useful libraries in other languages, especially C. To use these libraries, and let C code use Haskell functions, there is the Foreign Function Interface (FFI).

## Calling C from Haskell
### Marshalling (Type Conversion)

When using C functions, it is necessary to convert Haskell types to the appropriate C types. These are available in the Foreign.C.Types module; some examples are given in the following table.
| Haskell | Foreign.C.Types | C |
| Double | CDouble | double |
| Char | CUChar | unsigned char |
| Int | CLong | long int |
The operation of converting Haskell types into C types is called marshalling (and the opposite, predictably, unmarshalling). For basic types this is quite straightforward: for floating-point one uses realToFrac (either way, as e.g. both Double and CDouble are instances of classes Real and Fractional), for integers fromIntegral, and so on.

### Calling a pure C function

A pure function implemented in C does not present significant trouble in Haskell. The sin function of the C standard library is a fine example:
First, we specify a GHC extension for the FFI in the first line. We then import the Foreign and Foreign.C.Types modules, the latter of which contains information about CDouble, the representation of double-precision floating-point numbers in C.
We then specify that we are importing a foreign function, with a call to C. A "safety level" has to be specified with the keyword safe (the default) or unsafe. In general, unsafe is more efficient, and safe is required only for C code that could call back a Haskell function. Since that is a very particular case, it is actually quite safe to use the unsafe keyword in most cases. Finally, we need to specify header and function name, separated by a space.
The Haskell function name is then given, in our case we use a standard c_sin, but it could have been anything. Note that the function signature must be correct—GHC will not check the C header to confirm that the function actually takes a CDouble and returns another, and writing a wrong one could have unpredictable results.
It is then possible to generate a wrapper around the function using CDouble so that it looks exactly like any Haskell function.
Importing C's sin is simple because it is a pure function that takes a plain double as input and returns another as output: things will complicate with impure functions and pointers, which are ubiquitous in more complicated C libraries.

### Impure C Functions

A classic impure C function is rand, for the generation of pseudo-random numbers. Suppose you do not want to use Haskell's System.Random.randomIO, for example because you want to replicate exactly the series of pseudo-random numbers output by some C routine. Then, you could import it just like sin before:
If you try this naïve implementation in GHCI, you will notice that c_rand is returning always the same value:
indeed, we have told GHC that it is a pure function, and GHC sees no point in calculating twice the result of a pure function. Note that GHC did not give any error or warning message.
In order to make GHC understand this is no pure function, we have to use the IO monad:
Here, we also imported the srand function, to be able to seed the C pseudo-random generator.

### Working with C Pointers

The most useful C functions are often those that do complicated calculations with several parameters, and with increasing complexity the need of returning control codes arises. This means that a typical paradigm of C libraries is to give pointers of allocated memory as "targets" in which the results may be written, while the function itself returns an integer value (typically, if 0, computation was successful, otherwise there was a problem specified by the number). Another possibility is that the function will return a pointer to a structure (possibly defined in the implementation, and therefore unavailable to us).
As a pedagogical example, we consider the gsl_frexp function of the GNU Scientific Library, a freely available library for scientific computation. It is a simple C function with prototype:
The function takes a double x, and it returns its normalised fraction f and integer exponent e so that:
    $x=f\times 2^{e}\qquad e\in \mathbb {Z} ,\quad 0.5\leq f<1$
We interface this C function into Haskell with the following code:
The new part is Ptr, which can be used with any instance of the Storable class, among which all C types, but also several Haskell types.
Notice how the result of the gsl_frexp function is in the IO monad. This is typical when working with pointers, be they used for input or output (as in this case); we will see shortly what would happen had we used a simple CDouble for the function.
The frexp function is implemented in pure Haskell code as follows:
We know that, memory management details aside, the function is pure: that's why the signature returns a tuple with f and e outside of the IO monad. Yet, f is provided inside of it: to extract it, we use the function unsafePerformIO, which extracts values from the IO monad: obviously, it is legitimate to use it only when we know the function is pure, and we can allow GHC to optimise accordingly.
To allocate pointers, we use the alloca function, which also takes responsibility for freeing memory. As an argument, alloca takes a function of type Ptr a -> IO b, and returns the IO b. In practice, this translates to the following usage pattern with λ functions:
The pattern can easily be nested if several pointers are required:
Back to our frexp function: in the λ function that is the argument to alloca, the function is evaluated and the pointer is read immediately afterwards with peek. Here we can understand why we wanted the imported C function gsl_frexp to return a value in the IO monad: if GHC could decide when to calculate the quantity f, it would likely decide not to do it until it is necessary: that is at the last line when return uses it, and after e has been read from an allocated, but yet uninitialised memory address, which will contain random data. In short, we want gsl_frexp to return a monadic value because we want to determine the sequence of computations ourselves.
If some other function had required a pointer to provide input instead of storing output, one would have used the similar poke function to set the pointed value, obviously before evaluating the function:
In the final line, the results are arranged in a tuple and returned, after having been converted from C types.
To test the function, remember to link GHC to the GSL; in GHCI, do:
(Note that most systems do not come with the GSL preinstalled, and you may have to download and install its development packages.)

### Working with C Structures

Very often data are returned by C functions in form of structs or pointers to these. In some rare cases, these structures are returned directly, but more often they are returned as pointers; the return value is most often an int that indicates the correctness of execution.
We will consider another GSL function, gsl_sf_bessel_Jn_e. This function provides the regular cylindrical Bessel function for a given order n, and returns the result as a gsl_sf_result structure pointer. The structure contains two doubles, one for the result and one for the error. The integer error code returned by the function can be transformed in a C string by the function gsl_strerror. The signature of the Haskell function we are looking for is therefore:
where the first argument is the order of the cylindrical Bessel function, the second is the function's argument, and the returned value is either an error message or a tuple with result and margin of error.

#### Making a New Instance of the Storable class

In order to allocate and read a pointer to a gsl_sf_result structure, it is necessary to make it an instance of the Storable class.
In order to do that, it is useful to use the hsc2hs program: we create first a Bessel.hsc file, with a mixed syntax of Haskell and C macros, which is later expanded into Haskell by the command:
After that, we simply load the Bessel.hs file in GHC.
This is the first part of file Bessel.hsc:
We use the #include directive to make sure hsc2hs knows where to find information about gsl_sf_result. We then define a Haskell data structure mirroring the GSL's, with two CDoubles: this is the class we make an instance of Storable. Strictly, we need only sizeOf, alignment and peek for this example; poke is added for completeness.
* sizeOf is obviously fundamental to the allocation process, and is calculated by hsc2hs with the #size macro.
* alignment is the size in bytes of the data structure alignment. In general, it should be the largest alignment of the elements of the structure; in our case, since the two elements are the same, we simply use CDouble's. The value of the argument to alignment is inconsequential, what is important is the type of the argument.
* peek is implemented using a do-block and the #peek macros, as shown. val and err are the names used for the structure fields in the GSL source code.
* Similarly, poke is implemented with the #poke macro.

#### Importing the C Functions

We import several functions from the GSL libraries: first, the Bessel function itself, which will do the actual work. Then, we need a particular function, gsl_set_error_handler_off, because the default GSL error handler will simply crash the program, even if called by Haskell: we, instead, plan to deal with errors ourselves. The last function is the GSL-wide interpreter that translates error codes in human-readable C strings.

#### Implementing the Bessel Function

Finally, we can implement the Haskell version of the GSL cylindrical Bessel function of order n.
Again, we use unsafePerformIO because the function is pure, even though its nuts-and-bolts implementation is not. After allocating a pointer to a GSL result structure, we deactivate the GSL error handler to avoid crashes in case something goes wrong, and finally we can call the GSL function. At this point, if the status returned by the function is 0, we unmarshal the result and return it as a tuple. Otherwise, we call the GSL error-string function, and pass the error as a Left result instead.

#### Examples

Once we are finished writing the Bessel.hsc function, we have to convert it to proper Haskell and load the produced file:
We can then call the Bessel function with several values:

### Advanced Topics

This section contains an advanced example with some more complex features of the FFI. We will import into Haskell one of the more complicated functions of the GSL, the one used to calculate the integral of a function between two given points with an adaptive Gauss-Kronrod algorithm. The GSL function is gsl_integration_qag.
This example will illustrate function pointers, export of Haskell functions to C routines, enumerations, and handling pointers of unknown structures.

#### Available C Functions and Structures

The GSL has three functions which are necessary to integrate a given function with the considered method:
The first two deal with allocation and deallocation of a "workspace" structure of which we know nothing (we just pass a pointer around). The actual work is done by the last function, which requires a pointer to a workspace.
To provide functions, the GSL specifies an appropriate structure for C:
The reason for the void pointer is that it is not possible to define λ functions in C, so the function cannot be partially applied with some general parameters independent of x and these parameters are therefore passed in a pointer of an unknown type. In Haskell, we do not need the params element, and will consistently ignore it.

#### Imports and Inclusions

We start our qag.hsc file with the following:
We declare the EmptyDataDecls pragma, which we will use later for the Workspace data type. Since this file will have a good number of functions that should not be available to the outside world, we also declare it a module and export only the final function qag and the gauss- flags. We also include the relevant C headers of the GSL. The import of C functions for error messages and deactivation of the error handler was described before.

#### Enumerations

One of the arguments of gsl_integration_qag is key, an integer value that can have values from 1 to 6 and indicates the integration rule. GSL defines a macro for each value, but in Haskell it is more appropriate to define a type, which we call IntegrationRule. Also, to have its values automatically defined by hsc2hs, we can use the enum macro:
hsc2hs will search the headers for the macros and give our variables the correct values. The enum directive will define a function with an appropriate type signature for each of the enum values. The above example will get translated to something like this (with the C macros appropriately replaced by their values):
The variables cannot be modified and are essentially constant flags. Since we did not export the IntegrationRule constructor in the module declaration, but only the gauss flags, it is impossible for a user to even construct an invalid value. One thing less to worry about!

#### Haskell Function Target

We can now write down the signature of the function we desire:
Note how the order of arguments is different from the C version: indeed, since C does not have the possibility of partial application, the ordering criteria are different than in Haskell.
As in the previous example, we indicate errors with a Either String (Double, Double) result.

#### Passing Haskell Functions to the C Algorithm

We define a shorthand type, CFunction, for readability. Note that the void pointer has been translated to a Ptr, since we have no intention of using it. Then it is the turn of the gsl_function structure: no surprises here. Note that the void pointer is always assumed to be null, both in peek and in poke, and is never really read nor written.
To make a Haskell Double -> Double function available to the C algorithm, we make two steps: first, we re-organise the arguments using a λ function in makeCfunction; then, in makeFunPtr, we take the function with reordered arguments and produce a function pointer that we can pass on to poke, so we can construct the GslFunction data structure.

#### Handling Unknown Structures

The reason we imported the EmptyDataDecls pragma is this: we are declaring the data structure Workspace without providing any constructor. This is a way to make sure it will always be handled as a pointer, and never actually instantiated.
Otherwise, we normally import the allocating and deallocating routines. We can now import the integration function, since we have all the required pieces (GslFunction and Workspace).

#### The Complete Function

It is now possible to implement a function with the same functionality as the GSL's QAG algorithm.
First and foremost, we deactivate the GSL error handler, that would crash the program instead of letting us report the error.
We then proceed to allocate the workspace; notice that, if the returned pointer is null, there was an error (typically, too large size) that has to be reported.
If the workspace was allocated correctly, we convert the given function to a function pointer and allocate the GslFunction struct, in which we place the function pointer. Allocating memory for the result and its error margin is the last thing before calling the main routine.
After calling, we have to do some housekeeping and free the memory allocated by the workspace and the function pointer. Note that it would be possible to skip the bookkeeping using ForeignPtr, but the work required to get it to work is more than the effort to remember one line of cleanup.
We then proceed to check the return value and return the result, as was done for the Bessel function.

### Self-Deallocating Pointers

In the previous example, we manually handled the deallocation of the GSL integration workspace, a data structure we know nothing about, by calling its C deallocation function. It happens that the same workspace is used in several integration routines, which we may want to import in Haskell.
Instead of replicating the same allocation/deallocation code each time, which could lead to memory leaks when someone forgets the deallocation part, we can provide a sort of "smart pointer", which will deallocate the memory when it is not needed any more. This is called ForeignPtr (do not confuse with Foreign.Ptr: this one's qualified name is actually Foreign.ForeignPtr!). The function handling the deallocation is called the finalizer.
In this section we will write a simple module to allocate GSL workspaces and provide them as appropriately configured ForeignPtrs, so that users do not have to worry about deallocation.
The module, written in file GSLWorkspace.hs, is as follows:
We first declare our empty data structure Workspace, just like we did in the previous section.
The gsl_integration_workspace_alloc and gsl_integration_workspace_free functions will no longer be needed in any other file: here, note that the deallocation function is called with an ampersand ("&"), because we do not actually want the function, but rather a pointer to it to set as a finalizer.
The workspace creation function returns a IO (Maybe) value, because there is still the possibility that allocation is unsuccessful and the null pointer is returned. The GSL does not specify what happens if the deallocation function is called on the null pointer, so for safety we do not set a finalizer in that case and return IO Nothing; the user code will then have to check for "Just-ness" of the returned value.
If the pointer produced by the allocation function is non-null, we build a foreign pointer with the deallocation function, inject into the Maybe and then the IO monad. That's it, the foreign pointer is ready for use!
The qag.hsc file must now be modified to use the new module; the parts that change are:
Obviously, we do not need the EmptyDataDecls extension here any more; instead we import the GSLWorkSpace module, and also a couple of nice-to-have functions from Data.Maybe. We also remove the foreign declarations of the workspace allocation and deallocation functions.
The most important difference is in the main function, where we (try to) allocate a workspace ws, test for its Justness, and if everything is fine we use the withForeignPtr function to extract the workspace pointer. Everything else is the same.

## Calling Haskell from C

Sometimes it is also convenient to call Haskell from C, in order to take advantage of some of Haskell's features which are tedious to implement in C, such as lazy evaluation.
We will consider a typical Haskell example, Fibonacci numbers. These are produced in an elegant, haskellian one-liner as:
Our task is to export the ability to calculate Fibonacci numbers from Haskell to C. However, in Haskell, we typically use the Integer type, which is unbounded: this cannot be exported to C, since there is no such corresponding type. To provide a larger range of outputs, we specify that the C function shall output, whenever the result is beyond the bounds of its integer type, an approximation in floating-point. If the result is also beyond the range of floating-point, the computation will fail. The status of the result (whether it can be represented as a C integer, a floating-point type or not at all) is signalled by the status integer returned by the function. Its desired signature is therefore:

### Haskell Source

The Haskell source code for file fibonacci.hs is:
When exporting, we need to wrap our functions in a module (it is a good habit anyway). We have already seen the Fibonacci infinite list, so let's focus on the exported function: it takes an argument, two pointers to the target unsigned long long and double, and returns the status in the IO monad (since writing on pointers is a side effect).
The function is implemented with input guards, defined in the where clause at the bottom. A successful computation will return 0, a partially successful 1 (in which we still can use the floating-point value as an approximation), and a completely unsuccessful one will return 2.
Note that the function does not call alloca, since the pointers are assumed to have been already allocated by the calling C function.
The Haskell code can then be compiled with GHC:

### C Source

The compilation of fibonacci.hs has spawned several files, among which fibonacci_stub.h, which we include in our C code in file fib.c:
The notable thing is that we need to initialise the Haskell environment with hs_init, which we call passing it the command-line arguments of main; we also have to shut Haskell down with hs_exit when we are done. The rest is fairly standard C code for allocation and error handling.
Note that you have to compile the C code with GHC, not your C compiler!
You can then proceed to test the algorithm:
* FFI
* Solutions to exercises
* General Practices
* Debugging
* >> Testing
* >> Packaging your software (Cabal)
* >> Using the Foreign Function Interface (FFI)
* >> Generic programming: Scrap your boilerplate
* Haskell
* Haskell Basics
* >> Elementary Haskell
* >> Intermediate Haskell
* >> Monads
* Advanced Haskell
* >> Fun with Types
* >> Wider Theory
* >> Haskell Performance
* Libraries Reference
* >> General Practices
* >> Specialised Tasks