futhask-1.0.0: README.md

# Futhask
Futhask is a code generator that aims to create safe, Haskell friendly wrappers for Futhark libraries.

## Installation
```Shell
cabal install futhask
```

## Generating code 
### Syntax
```Shell
futhask [LIBNAME] [LIBVER] [PROGRAM.c] [PROGRAM.json] [DEST]
```

#### Example
```Shell
futhark opencl --library myprogram.fut
futhask mylib 1.0 myprogram.c myprogram.json mylibrary
```

### Using the generated code
To use local libraries, add them to the `cabal.project`
    
    packages:
        DEST/*.cabal
        *.cabal
    
Then add them as imports in the cabal file as usual
```cabal
    ...
    build-depends:
        ...
        mylib
        ...
```
and then 

```haskell
import Mylib
```

to get the basic interface which should be sufficient for many cases. For more granular imports, or if the access to the raw interface is desired, The following submodules are available

 - `Context` wrapped context instance
 - `Monad` Fut monad definition
 - `TypeDec` wrapped type declarations
 - `TypeOps` instances of various classes for the wrapped types 
 - `Types` reexports `TypeDec` and `TypeOps`
 - `Conversion` instances of `Convertible`
 - `EntryPoints` wrapped entry points
 - `Raw` simply the C-API imported with the FFI
    - `Context` context and config functions
    - `TypeDec` raw type declarations
    - `TypeOps` type specific utility functions
    - `Types` reexports `TypeDec` and `TypeOps`
    - `EntryPoints` raw entry points
 - `Unpacked` 
    - `Types` Unpacked futhark types, useful for constructing or deconstructing values
 - `Native`
    - `Types` Native type equivalents for (almost all) futhark types

#### Code example
Given the futhark file 
```futhark
type someopaque = (f32, i64)

entry foo (input:f32) : someopaque = (input, i64.f32 input)

entry bar (input:someopaque) : []f32 = replicate (input.1) (input.0)
```

the generated library can be used like

```haskell
module FutharkUsageExample where
import Mylib

-- `foobar` composes `foo` and `bar`,
-- and converts the output array to a haskell native array
foobar :: Monad m => F32 -> m (Array F32)
foobar input = runFutT $ do
    foores <- foo input
    barres <- bar foores
    fromFuthark barres

-- `foobar'` does the same thing as `foobar` 
-- but also immediately finalizes the intermediate results
foobar' :: MonadIO m => F32 -> m (Array F32)
foobar' input = runFutT $ do
    foores <- foo input
    barres <- bar foores
    finalizeFO foores
    native_barres <- fromFuthark barres
    finalizeFO barres
    pure native_barres
```        

## Documentation
The base library contains basic documentation on the general classes and other core functions. `cabal haddock` can be used to obtain documentation specific to the generated library. 

## Generated Code
The generated code can be split in two main parts, raw and wrapped. The raw interface is simply the C-functions wrapped in the `IO`-monad, providing no added safety and requiring manual memory management. The wrapped interface uses `newForeignPtr` to introduce all Futhark pointers to the GC, and provides function types closer to those used within Futhark. In particular, unnamed tuple structures are transparent, so the arguments and return values have the same structure as in the futhark type declaration. 

### Primitive types
Primitive types are given aliases based on their name in futhark. 
For example the haskell type `Float` is called `F32`. These aliases are used in all generated type signatures.

### Tuples
Unnamed tuples are recursively unpacked in all function arguments and return values in the wrapped interface, and as such are simply tuples in Haskell too. This adds a little bit of overhead at each use but can be convenient when values need to be composed or when multiple return values are desired. If unpacking is undesired, simply make a type synonym in futhark.

### Opaques
Opaque values are values such as records, sums, nonprimitive arrays, and any type with an alias in the futhark file with the entry points. Unnamed types are given a name by parsing and reformatting the futhark type to a format allowed in Haskell. Since these names often end up fairly long and a little cryptic, it is recommended to name the types that are intended to be used. 

#### Value composition and decomposition
For opaque types instances of

```haskell
class (FutharkObject fo) => FutharkComposite fo where
    type Unpacked fo :: Type -> Type
    pack :: (Monad m) => Unpacked fo c -> FutT c m (fo c)
    unpack :: (Monad m) => fo c -> FutT c m (Unpacked fo c) 
```

can be used to compose and decompose values with their `Unpacked` type as an intermediate.

#### Haskell-native Types
In order to facilitate input and output, it is convenient to have a Haskell-native representation of the types used in the Futhark program. These are defined in the `Native.Types` submodule. 

Unnamed types are give a name based on the futhark type, and for arrays this is just a type synonym for the native array type of the element.
Named types retain their futhark name (but capitalized), and in the case of arrays this is a `newtype` around the native array type of the element.

All types are instances of the `Element` class provided by `futhark-base` which defines array types for them and allows the use of generic array functions like `map`, `tabulate`, etc, to be used.

#### Conversion
For conversion between Futhark values and Haskell native values, instances of 

```haskell
class Convertible fo where
    Native fo 
    toFuthark :: Monad m => Native fo -> FutT c m (fo c) 
    fromFuthark :: Monad m => fo c -> FutT c m (Native fo)
```

are defined. Currently instances should exist for all futhark types except those containing arrays of sum types. Note that this does not mean that all Native values can be converted to Futhark values, as only those used by the entrypoints will be defined on the futhark side. Additionally care should be taken when converting nested arrays to Futhark values, as the native array type currently does not enforce regular arrays.


### Context Options
These options can be used change how the context operates. For more information see the [C-API documentation](https://futhark.readthedocs.io/en/stable/c-api.html).
#### All backends
 - `TuningParameters [(String, CSize)]`
 - `CacheFile String` Sets a cachefile for the context. Highly recommended to reduce startup times.
 - `Debug Int`
 - `Log Int`
 - `Profile Int`
#### All GPU backends
 - `Device String`
 - `DefaultThreadBlockSize Int`
 - `DefaultGridSize Int`
 - `DefaultTileSize`
#### OpenCL
 - `Platform String`
 - `BuildOptions [String]`
#### Cuda
 - `NvrtcOptions [String]`
#### Multicore
 - `NumThreads Int`
 

### The Fut monad
To make the wrappers safe, and reduce clutter from explicitly passing around the context, the `Fut` monad is introduced. The `Fut` monad is an environment monad that implicitly passes the context around as necessary. Like the `ST` monad, the `Fut` monad is parameterised by a rigid type variable to prevent references to the context from escaping the monad.

To run computations, the function
```
mkContext :: [ContextOption] -> IO (Context, [String])
``` 
to create a context, and then run the monad with

```haskell
runFutIn :: Context -> (forall c. Fut c a) -> a
```

Additionally

```haskell
runFutWith :: [ContextOption] -> (forall c. Fut c a) -> a
runFut :: (forall c. Fut c a) -> a
```

are defined for convienience for cases where the context doesn't need to be reused.

### The FutT transformer
For more flexibility, the FutT monad transformer can be used. For convenience the type synonyms

```haskell
type Fut c = FutT c Identity
type FutIO c = FutT c IO
```

are defined, but entry-points and most other functions are in the polymorphic `Monad m => FutT c m`.

Actually these are just specialized versions of the more general transformer defined in the `Futhask` base library.

To run the transformer 

```haskell    
runFutTIn :: Context -> (forall c. FutT c m a) -> m a
runFutTWith :: [ContextOption] -> (forall c. FutT c m a) -> m a
runFutT :: (forall c. FutT c m a) -> m a
```

For lifting

```haskell
mapFutT :: (m a -> n b) -> FutT c m a -> FutT c n b
map2FutT :: (m a -> n b -> k c) -> FutT c' m a -> FutT c' n b -> FutT c' k c
pureFut :: Monad m => Fut c a -> FutT c m a
unsafeFromFutIO :: FutIO c a -> FutT c m a
```

#### Running transformer stacks
When using `FutT c` with other transformers in a stack the type of the function running the monad may need to be defined explicitly. 
In the same way as `runFutT`, these signatures require an explicit `forall` to force `c` to be fully polymorphic.

```haskell
runMyMonad :: (forall c. MyMonad c a) -> a 
```

This requires the `RankNTypes` extension.

### Memory management
All of the wrapped values have finalizers, and should *eventually* be garbage collected. However, GHCs GC does not know how much memory the context is using, and so collection will not always be triggered frequently enough. This is primarily an issue when the program iterates on Futhark values, without any Haskell-side allocations.

One way to deal with this is to manually manage the memory using

```haskell
finalizeFO :: (MonadIO m, FutharkObject fo) => fo c -> FutT c m ()
```

As with any manual memory management, the programmer is responsible for ensuring that the finalized value will not be used afterwards. For cases where the object is used in more than one thread without synchronisation,

```haskell
addReferenceFO :: (MonadIO m, FutharkObject fo) => fo c -> FutT c m ()
``` 

can be used. `addReferenceFO` increments the reference counter of the object and `finalizeFO` will just decrement this counter until it's `0`.