TODO: Clean up the formatting!
foreign import ccall
Import the primitive exactly as if it were a standard FFI c-call. This allows for the possibility that the primitive might block and so it is run in a seperate OS thread.
foreign import fastccall
Same as ccall but don't run the primitive call in a seperate OS-level thread because we promise it won't block.
foreign import primitive
make a call to the C-function but don't try and convert the arguments or result to/from Haskell nodes. This is necessary because some primitives are so low level they need to work on the Haskell nodes directly.
foreign import cast
this is a standard part of the FFI. Essentially it says this might look like we're importing something but actually just cast the argument to the result and forget about it. You can implement this as a 'fastccall' but it's quicker and standard FFI in any case.
foreign import builtin
the primitive uses EVAL or APPLY internally and thus can't be implemented as C code - it has to be written as byte code. Nor can the function be written in Haskell. Currently there is only one primitive in this category which is primCatch.
primCatch :: a -> (b -> a) -> a primCatch e h CATCH_BEGIN handler PUSH_ZAP_ARG e EVAL CATCH_END RETURN handler: PUSH_ARG h APPLY 1 RETURN_EVAL
it would be possible to implement this as compiler magic. i.e. define primCatch as
primCatch e h = undefined -- MAGIC!!
and have the compiler rewrite it as the above bytecode, but I figured you wouldn't fancy that ;-)