C-calling "gotchas" checklist

And some advice, too.

• `_ccall_' is part of the `PrimIO' monad -- not the 1.3 `IO' Monad. Use the function

  primIOToIO :: PrimIO a -> IO a
  

  to promote a `_ccall_' to the `IO' monad.
• For modules that use `_ccall_'s, etc., compile with `-fvia-C'. You don't have to, but you should. Also, use the `-#include "prototypes.h"' flag (hack) to inform the C compiler of the fully-prototyped types of all the C functions you call. (Section See section Using function headers says more about this...) This scheme is the only way that you will get any typechecking of your `_ccall_'s. (It shouldn't be that way, but...)
• Try to avoid `_ccall_'s to C functions that take `float' arguments or return `float' results. Reason: if you do, you will become entangled in (ANSI?) C's rules for when arguments/results are promoted to `doubles'. It's a nightmare and just not worth it. Use `doubles' if possible. If you do use `floats', check and re-check that the right thing is happening. Perhaps compile with `-keep-hc-file-too' and look at the intermediate C (`.hc' file).
• The compiler uses two non-standard type-classes when type-checking the arguments and results of `_ccall_': the arguments (respectively result) of `_ccall_' must be instances of the class `_CCallable' (respectively `_CReturnable'. (Neither class defines any methods -- their only function is to keep the type-checker happy.) The type checker must be able to figure out just which of the C-callable/returnable types is being used. If it can't, you have to add type signatures. For example,

  f x = _ccall_ foo x
  

  is not good enough, because the compiler can't work out what type `x' is, nor what type the `_ccall_' returns. You have to write, say:

  f :: Int -> PrimIO Double
  f x = _ccall_ foo x
  

  This table summarises the standard instances of these classes.

  Type                          CCallable  CReturnable  Which is probably...                 
  -----------------------------------------------------------------------------------------
  `Char'               Yes        Yes          `unsigned char'             
  `Int'                Yes        Yes          `long int'                  
  `_Word'              Yes        Yes          `unsigned long int'         
  `_Addr'              Yes        Yes          `char *'                    
  `Float'              Yes        Yes          `float'                     
  `Double'             Yes        Yes          `double'                    
  `()'                 No         Yes          `void'                      
  `[Char]'             Yes        No           `char *' (null-terminated)  
  `Array'              Yes        No           `unsigned long *'           
  `_ByteArray'         Yes        No           `unsigned long *'           
  `_MutableArray'      Yes        No           `unsigned long *'           
  `_MutableByteArray'  Yes        No           `unsigned long *'           
  `_State'             Yes        Yes          nothing!                             
  `_StablePtr'         Yes        Yes          `unsigned long *'           
  `_MallocPtr'         Yes        Yes          see later                            
  

  The brave and careful programmer can add their own instances of these classes for the following types:
  • A boxed-primitive type may be made an instance of both `_CCallable' and `_CReturnable'. A boxed primitive type is any data type with a single unary constructor with a single primitive argument. For example, the following are all boxed primitive types:

    Int
    Double
    data XDisplay = XDisplay Addr#
    data EFS a = EFS# MallocPtr#
    

    instance _CCallable   (EFS a)
    instance _CReturnable (EFS a)
    

  • Any datatype with a single nullary constructor may be made an instance of `_CReturnable'. For example:

    data MyVoid = MyVoid
    instance _CReturnable MyVoid
    

  • As at version 0.26, `String' (i.e., `[Char]') is still not a `_CReturnable' type. Also, the now-builtin type `_PackedString' is neither `_CCallable' nor `_CReturnable'. (But there are functions in the PackedString interface to let you get at the necessary bits...)
• The code-generator will complain if you attempt to use `%r' in a `_casm_' whose result type is `PrimIO ()'; or if you don't use `%r' precisely once for any other result type. These messages are supposed to be helpful and catch bugs -- please tell us if they wreck your life.
• If you call out to C code which may trigger the Haskell garbage collector (examples of this later...), then you must use the `_ccall_GC_' or `_casm_GC_' variant of C-calls. (This does not work with the native code generator - use `\fvia-C'.) This stuff is hairy with a capital H!