1 %************************************************************************
3 \section[glasgow-exts]{Glasgow extensions to Haskell}
4 \index{Haskell, Glasgow extensions}
5 \index{extensions, Glasgow Haskell}
7 %************************************************************************
9 As with all known Haskell systems, GHC implements some extensions to
11 To use them, you'll need to give
12 a \tr{-fglasgow-exts}%
13 \index{-fglasgow-exts option} option.
15 Virtually all of the Glasgow extensions serve to give you access to the
16 underlying facilities with which we implement Haskell. Thus, you can
17 get at the Raw Iron, if you are willing to write some non-standard
18 code at a more primitive level. You need not be ``stuck'' on
19 performance because of the implementation costs of Haskell's
20 ``high-level'' features---you can always code ``under'' them. In an
21 extreme case, you can write all your time-critical code in C, and then
22 just glue it together with Haskell!
24 Executive summary of our extensions:
26 \item[Unboxed types and primitive operations:] You can get right down
27 to the raw machine types and operations; included in this are
28 ``primitive arrays'' (direct access to Big Wads of Bytes).
29 Please see \Sectionref{glasgow-unboxed} and following.
31 \item[Calling out to C:] Just what it sounds like. We provide {\em
32 lots} of rope that you can dangle around your neck.
33 Please see \Sectionref{glasgow-ccalls}.
35 \item[``HBC-ish'' extensions:] Extensions implemented because people said,
36 ``HBC does Y. Could you teach GHC to do the same?'' Please see
37 \Sectionref{glasgow-hbc-exts} for a quick list.
40 Before you get too carried away working at the lowest level (e.g.,
41 sloshing \tr{MutableByteArray#}s around your program), you may wish to
42 check if there are system libraries that provide a ``Haskellised
43 veneer'' over the features you want. See \Sectionref{syslibs}.
45 \Sectionref{ghc-prelude} is the definitive guide for many of the
46 low-level facilities in GHC.
48 %************************************************************************
50 \subsection[glasgow-unboxed]{Unboxed types}
51 \index{Unboxed types (Glasgow extension)}
53 %************************************************************************
55 These types correspond to the ``raw machine'' types you would use in
56 C: \tr{Int#} (long int), \tr{Double#} (double),
57 \tr{Addr#} (void *), etc. The {\em primitive
58 operations} (PrimOps) on these types are what you might expect; e.g.,
59 \tr{(+#)} is addition on \tr{Int#}s, and is the machine-addition that
60 we all know and love---usually one instruction.
62 A numerically-intensive program using unboxed types can go a {\em lot}
63 faster than its ``standard'' counterpart---we saw a threefold speedup
66 Please see \Sectionref{ghc-libs-ghc} for the details of
67 unboxed types and the operations on them.
69 %************************************************************************
71 \subsection[glasgow-ST-monad]{Primitive state-transformer monad}
72 \index{state transformers (Glasgow extensions)}
73 \index{ST monad (Glasgow extension)}
75 %************************************************************************
77 This monad underlies our implementation of arrays, mutable and immutable,
78 and our implementation of I/O, including ``C calls''.
80 You probably won't use the monad directly, but you might use all those
83 More information on the state-related types can be found in the
84 elsewhere, \Sectionref{ghc-prelude}.
86 %************************************************************************
88 \subsection[glasgow-prim-arrays]{Primitive arrays, mutable and otherwise}
89 \index{primitive arrays (Glasgow extension)}
90 \index{arrays, primitive (Glasgow extension)}
92 %************************************************************************
94 GHC knows about quite a few flavours of Large Swathes of Bytes.
96 First, GHC distinguishes between primitive arrays of (boxed) Haskell
97 objects (type \tr{Array# obj}) and primitive arrays of bytes (type
100 Second, it distinguishes between...
103 Arrays that do not change (as with ``standard'' Haskell arrays); you
104 can only read from them. Obviously, they do not need the care and
105 attention of the state-transformer monad.
108 Arrays that may be changed or ``mutated.'' All the operations on them
109 live within the state-transformer monad and the updates happen {\em
112 \item[``Static'' (in C land):]
113 A C~routine may pass an \tr{Addr#} pointer back into Haskell land.
114 There are then primitive operations with which you may merrily grab
115 values over in C land, by indexing off the ``static'' pointer.
117 \item[``Stable'' pointers:]
118 If, for some reason, you wish to hand a Haskell pointer (i.e., {\em
119 not} an unboxed value) to a C~routine, you first make the pointer
120 ``stable,'' so that the garbage collector won't forget that it exists.
121 That is, GHC provides a safe way to pass Haskell pointers to C.
123 Please see \Sectionref{glasgow-stablePtrs} for more details.
125 \item[``Foreign objects'':]
126 A ``foreign object'' is a safe way to pass an external object (a
127 C~allocated pointer, say) to Haskell and have Haskell do the Right
128 Thing when it no longer references the object. So, for example, C
129 could pass a large bitmap over to Haskell and say ``please free this
130 memory when you're done with it.''
132 Please see \Sectionref{glasgow-foreignObjs} for more details.
135 The libraries section give more details on all these
136 ``primitive array'' types and the operations on them,
137 \Sectionref{ghc-prelude}.
140 %************************************************************************
142 \subsection[own-mainIO]{Using your own @mainIO@}
143 \index{mainIO, rolling your own}
144 \index{GHCmain, module containing mainIO}
146 %************************************************************************
148 Normally, the GHC runtime system begins things by called an internal
149 function @mainIO :: IO ()@ which, in turn, fires up your @Main.main@.
150 The standard definition of @mainIO@ looks like this:
153 mainIO = catch Main.main
154 (\err -> error ("I/O error: " ++ showsPrec 0 err "\n"))
157 \noindent that is, all it does is to run @Main.main@, catching any I/O
158 errors that occur and displaying them on standard error before exiting
161 To subvert the above process, you need only provide a @mainIO :: IO
162 ()@ of your own (in a module named \tr{GHCmain}).
164 Here's a little example, stolen from Alastair Reid:
167 module GHCmain ( mainIO ) where
174 _ccall_ printf "%d\n" (14::Int)
176 sleep :: Int -> IO ()
177 sleep t = _ccall_ sleep t
180 %************************************************************************
182 \subsection[glasgow-ccalls]{Calling~C directly from Haskell}
183 \index{C calls (Glasgow extension)}
184 \index{_ccall_ (Glasgow extension)}
185 \index{_casm_ (Glasgow extension)}
187 %************************************************************************
189 GOOD ADVICE: Because this stuff is not Entirely Stable as far as names
190 and things go, you would be well-advised to keep your C-callery
191 corraled in a few modules, rather than sprinkled all over your code.
192 It will then be quite easy to update later on.
194 WARNING AS OF 2.03: Yes, the \tr{_ccall_} stuff probably {\em will
195 change}, to something better, of course! One step in that direction
196 is Green Card, a foreign function interface pre-processor for Haskell
197 (``Glasgow'' Haskell in particular) --- check out
199 ftp://ftp.dcs.gla.ac.uk/pub/haskell/glasgow/green-card.ANNOUNCE
200 ftp://ftp.dcs.gla.ac.uk/pub/haskell/glasgow/green-card-src.tar.gz
203 %************************************************************************
205 \subsubsection[ccall-intro]{\tr{_ccall_} and \tr{_casm_}: an introduction}
207 %************************************************************************
209 The simplest way to use a simple C function
211 double fooC( FILE *in, char c, int i, double d, unsigned int u )
213 is to provide a Haskell wrapper:
215 fooH :: Char -> Int -> Double -> Word -> IO Double
216 fooH c i d w = _ccall_ fooC (``stdin''::Addr) c i d w
218 The function @fooH@ will unbox all of its arguments, call the C
219 function \tr{fooC} and box the corresponding arguments.
221 One of the annoyances about \tr{_ccall_}s is when the C types don't quite
222 match the Haskell compiler's ideas. For this, the \tr{_casm_} variant
223 may be just the ticket (NB: {\em no chance} of such code going through
224 a native-code generator):
227 = _casm_ ``%r = getenv((char *) %0);'' name >>= \ litstring@(A# str#) ->
229 if (litstring == ``NULL'') then
230 Left ("Fail:oldGetEnv:"++name)
232 Right (unpackCString# str#)
236 The first literal-literal argument to a \tr{_casm_} is like a
237 \tr{printf} format: \tr{%r} is replaced with the ``result,''
238 \tr{%0}--\tr{%n-1} are replaced with the 1st--nth arguments. As you
239 can see above, it is an easy way to do simple C~casting. Everything
240 said about \tr{_ccall_} goes for \tr{_casm_} as well.
242 %************************************************************************
244 \subsubsection[glasgow-foreign-headers]{Using function headers}
245 \index{C calls---function headers}
247 %************************************************************************
249 When generating C (using the \tr{-fvia-C} directive), one can assist
250 the C compiler in detecting type errors by using the \tr{-#include}
251 directive to provide \tr{.h} files containing function headers.
255 typedef unsigned long *StgForeignObj;
258 void initialiseEFS (StgInt size);
259 StgInt terminateEFS (void);
260 StgForeignObj emptyEFS(void);
261 StgForeignObj updateEFS (StgForeignObj a, StgInt i, StgInt x);
262 StgInt lookupEFS (StgForeignObj a, StgInt i);
265 You can find appropriate definitions for \tr{StgInt},
266 \tr{StgForeignObj}, etc using \tr{gcc} on your architecture by
267 consulting \tr{ghc/includes/StgTypes.lh}. The following table
268 summarises the relationship between Haskell types and C types.
271 C type name & Haskell Type \\ \hline
272 %----- & ---------------
273 \tr{StgChar} & \tr{Char#}\\
274 \tr{StgInt} & \tr{Int#}\\
275 \tr{StgWord} & \tr{Word#}\\
276 \tr{StgAddr} & \tr{Addr#}\\
277 \tr{StgFloat} & \tr{Float#}\\
278 \tr{StgDouble} & \tr{Double#}\\
280 \tr{StgArray} & \tr{Array#}\\
281 \tr{StgByteArray} & \tr{ByteArray#}\\
282 \tr{StgArray} & \tr{MutableArray#}\\
283 \tr{StgByteArray} & \tr{MutableByteArray#}\\
285 \tr{StgStablePtr} & \tr{StablePtr#}\\
286 \tr{StgForeignObj} & \tr{ForeignObj#}
289 Note that this approach is only {\em essential\/} for returning
290 \tr{float}s (or if \tr{sizeof(int) != sizeof(int *)} on your
291 architecture) but is a Good Thing for anyone who cares about writing
292 solid code. You're crazy not to do it.
294 %************************************************************************
296 \subsubsection[glasgow-stablePtrs]{Subverting automatic unboxing with ``stable pointers''}
297 \index{stable pointers (Glasgow extension)}
299 %************************************************************************
301 The arguments of a \tr{_ccall_} are automatically unboxed before the
302 call. There are two reasons why this is usually the Right Thing to do:
305 C is a strict language: it would be excessively tedious to pass
306 unevaluated arguments and require the C programmer to force their
307 evaluation before using them.
309 \item Boxed values are stored on the Haskell heap and may be moved
310 within the heap if a garbage collection occurs---that is, pointers
311 to boxed objects are not {\em stable\/}.
314 It is possible to subvert the unboxing process by creating a ``stable
315 pointer'' to a value and passing the stable pointer instead. For example, to
316 pass/return an integer lazily to C functions \tr{storeC} and
317 \tr{fetchC}, one might write:
319 storeH :: Int -> IO ()
320 storeH x = makeStablePtr x >>= \ stable_x ->
321 _ccall_ storeC stable_x
324 fetchH x = _ccall_ fetchC >>= \ stable_x ->
325 deRefStablePtr stable_x >>= \ x ->
326 freeStablePtr stable_x >>
330 The garbage collector will refrain from throwing a stable pointer away
331 until you explicitly call one of the following from C or Haskell.
333 void freeStablePointer( StgStablePtr stablePtrToToss )
334 freeStablePtr :: StablePtr a -> IO ()
337 As with the use of \tr{free} in C programs, GREAT CARE SHOULD BE
338 EXERCISED to ensure these functions are called at the right time: too
339 early and you get dangling references (and, if you're lucky, an error
340 message from the runtime system); too late and you get space leaks.
342 And to force evaluation of the argument within \tr{fooC}, one would
343 call one of the following C functions (according to type of argument).
346 void performIO ( StgStablePtr stableIndex /* StablePtr s (IO ()) */ );
347 StgInt enterInt ( StgStablePtr stableIndex /* StablePtr s Int */ );
348 StgFloat enterFloat ( StgStablePtr stableIndex /* StablePtr s Float */ );
351 \index{performIO, call a haskell IO computation from C}
352 \index{enterInt, call a haskell function from C}
353 \index{enterFloat, call a haskell function from C}
355 % ToDo ADR: test these functions!
357 Note Bene: \tr{_ccall_GC_} must be used if any of these functions are used.
360 %************************************************************************
362 \subsubsection[glasgow-foreignObjs]{Pointing outside the Haskell heap}
363 \index{foreign objects (Glasgow extension)}
365 %************************************************************************
367 There are two types that \tr{ghc} programs can use to reference
368 (heap-allocated) objects outside the Haskell world: \tr{Addr} and
371 If you use \tr{Addr}, it is up to you to the programmer to arrange
372 allocation and deallocation of the objects.
374 If you use \tr{ForeignObj}, \tr{ghc}'s garbage collector will
375 call upon the user-supplied {\em finaliser} function to free
376 the object when the Haskell world no longer can access the object.
377 (An object is associated with a finaliser function when the abstract
378 Haskell type @ForeignObj@ is created). The finaliser function is
379 expressed in C, and is passed as argument the object:
382 void foreignFinaliser ( StgForeignObj fo )
384 when the Haskell world can no longer access the object. Since
385 \tr{ForeignObj}s only get released when a garbage collection occurs,
386 we provide ways of triggering a garbage collection from within C and
389 void StgPerformGarbageCollection()
393 %************************************************************************
395 \subsubsection[glasgow-avoiding-monads]{Avoiding monads}
396 \index{C calls to `pure C'}
397 \index{unsafePerformIO (GlaExts)}
399 %************************************************************************
401 The \tr{_ccall_} construct is part of the \tr{IO} monad because 9 out
402 of 10 uses will be to call imperative functions with side effects such
403 as \tr{printf}. Use of the monad ensures that these operations happen
404 in a predictable order in spite of laziness and compiler
407 To avoid having to be in the monad to call a C function, it is
408 possible to use @unsafePerformIO@, which is available from the
409 @IOExts@ module. There are three situations where one might like to
410 call a C function from outside the IO world:
414 Calling a function with no side-effects:
416 atan2d :: Double -> Double -> Double
417 atan2d y x = unsafePerformIO (_ccall_ atan2d y x)
419 sincosd :: Double -> (Double, Double)
420 sincosd x = unsafePerformIO $ do
421 da <- newDoubleArray (0, 1)
422 _casm_ ``sincosd( %0, &((double *)%1[0]), &((double *)%1[1]) );'' x da
423 s <- readDoubleArray da 0
424 c <- readDoubleArray da 1
428 \item Calling a set of functions which have side-effects but which can
429 be used in a purely functional manner.
431 For example, an imperative implementation of a purely functional
432 lookup-table might be accessed using the following functions.
436 update :: EFS x -> Int -> x -> EFS x
437 lookup :: EFS a -> Int -> a
439 empty = unsafePerformIO (_ccall_ emptyEFS)
441 update a i x = unsafePerformIO $
442 makeStablePtr x >>= \ stable_x ->
443 _ccall_ updateEFS a i stable_x
445 lookup a i = unsafePerformIO $
446 _ccall_ lookupEFS a i >>= \ stable_x ->
447 deRefStablePtr stable_x
450 You will almost always want to use \tr{ForeignObj}s with this.
452 \item Calling a side-effecting function even though the results will
453 be unpredictable. For example the \tr{trace} function is defined by:
456 trace :: String -> a -> a
459 ((_ccall_ PreTraceHook sTDERR{-msg-}):: IO ()) >>
460 fputs sTDERR string >>
461 ((_ccall_ PostTraceHook sTDERR{-msg-}):: IO ()) >>
464 sTDERR = (``stderr'' :: Addr)
467 (This kind of use is not highly recommended --- it is only really
468 useful in debugging code.)
471 %************************************************************************
473 \subsubsection[ccall-gotchas]{C-calling ``gotchas'' checklist}
474 \index{C call dangers}
476 %************************************************************************
478 And some advice, too.
482 \tr{_ccall_} is part of the \tr{IO} monad --- not the \tr{ST} monad.
485 ioToST :: IO a -> ST RealWorld a
486 stToIO :: ST RealWorld a -> IO a
488 \index{ioToST function}
489 \index{stToIO function}
490 to coerce computations back and forth between the two monads.
492 \item For modules that use \tr{_ccall_}s, etc., compile with
493 \tr{-fvia-C}.\index{-fvia-C option} You don't have to, but you should.
495 Also, use the \tr{-#include "prototypes.h"} flag (hack) to inform the
496 C compiler of the fully-prototyped types of all the C functions you
497 call. (\Sectionref{glasgow-foreign-headers} says more about this...)
499 This scheme is the {\em only} way that you will get {\em any}
500 typechecking of your \tr{_ccall_}s. (It shouldn't be that way,
504 Try to avoid \tr{_ccall_}s to C~functions that take \tr{float}
505 arguments or return \tr{float} results. Reason: if you do, you will
506 become entangled in (ANSI?) C's rules for when arguments/results are
507 promoted to \tr{doubles}. It's a nightmare and just not worth it.
508 Use \tr{doubles} if possible.
510 If you do use \tr{floats}, check and re-check that the right thing is
511 happening. Perhaps compile with \tr{-keep-hc-file-too} and look at
512 the intermediate C (\tr{.hc} file).
515 The compiler uses two non-standard type-classes when
516 type-checking the arguments and results of \tr{_ccall_}: the arguments
517 (respectively result) of \tr{_ccall_} must be instances of the class
518 \tr{CCallable} (respectively \tr{CReturnable}). (Neither class
519 defines any methods --- their only function is to keep the
522 The type checker must be able to figure out just which of the
523 C-callable/returnable types is being used. If it can't, you have to
524 add type signatures. For example,
528 is not good enough, because the compiler can't work out what type @x@ is, nor
529 what type the @_ccall_@ returns. You have to write, say:
531 f :: Int -> IO Double
535 This table summarises the standard instances of these classes.
537 % ToDo: check this table against implementation!
539 \begin{tabular}{llll}
540 Type &CCallable&CReturnable & Which is probably... \\ \hline
541 %------ ---------- ------------ -------------
542 \tr{Char} & Yes & Yes & \tr{unsigned char} \\
543 \tr{Int} & Yes & Yes & \tr{long int} \\
544 \tr{Word} & Yes & Yes & \tr{unsigned long int} \\
545 \tr{Addr} & Yes & Yes & \tr{char *} \\
546 \tr{Float} & Yes & Yes & \tr{float} \\
547 \tr{Double} & Yes & Yes & \tr{double} \\
548 \tr{()} & No & Yes & \tr{void} \\
549 \tr{[Char]} & Yes & No & \tr{char *} (null-terminated) \\
551 \tr{Array} & Yes & No & \tr{unsigned long *}\\
552 \tr{ByteArray} & Yes & No & \tr{unsigned long *}\\
553 \tr{MutableArray} & Yes & No & \tr{unsigned long *}\\
554 \tr{MutableByteArray} & Yes & No & \tr{unsigned long *}\\
556 \tr{State} & Yes & Yes & nothing!\\
558 \tr{StablePtr} & Yes & Yes & \tr{unsigned long *}\\
559 \tr{ForeignObjs} & Yes & Yes & see later\\
562 The brave and careful programmer can add their own instances of these
563 classes for the following types:
566 A {\em boxed-primitive} type may be made an instance of both
567 \tr{CCallable} and \tr{CReturnable}.
569 A boxed primitive type is any data type with a
570 single unary constructor with a single primitive argument. For
571 example, the following are all boxed primitive types:
576 data XDisplay = XDisplay Addr#
577 data EFS a = EFS# ForeignObj#
581 instance CCallable (EFS a)
582 instance CReturnable (EFS a)
585 \item Any datatype with a single nullary constructor may be made an
586 instance of \tr{CReturnable}. For example:
590 instance CReturnable MyVoid
593 \item As at version 2.09, \tr{String} (i.e., \tr{[Char]}) is still
594 not a \tr{CReturnable} type.
596 Also, the now-builtin type \tr{PackedString} is neither
597 \tr{CCallable} nor \tr{CReturnable}. (But there are functions in
598 the PackedString interface to let you get at the necessary bits...)
602 The code-generator will complain if you attempt to use \tr{%r}
603 in a \tr{_casm_} whose result type is \tr{IO ()}; or if you don't
604 use \tr{%r} {\em precisely\/} once for any other result type. These
605 messages are supposed to be helpful and catch bugs---please tell us
606 if they wreck your life.
608 \item If you call out to C code which may trigger the Haskell garbage
609 collector (examples of this later...), then you must use the
610 \tr{_ccall_GC_}\index{_ccall_GC_ primitive} or
611 \tr{_casm_GC_}\index{_casm_GC_ primitive} variant of C-calls. (This
612 does not work with the native code generator - use \tr{\fvia-C}.) This
613 stuff is hairy with a capital H! \end{itemize}
615 %************************************************************************
617 \subsection[glasgow-hbc-exts]{``HBC-ish'' extensions implemented by GHC}
618 \index{HBC-like Glasgow extensions}
619 \index{extensions, HBC-like}
621 %************************************************************************
624 %-------------------------------------------------------------------
625 \item[@fromInt@ method in class @Num@:]
626 It's there. Converts from an \tr{Int} to the type.
628 %-------------------------------------------------------------------
629 \item[@toInt@ method in class @Integral@:]
630 Converts from type type to an \tr{Int}.
632 %-------------------------------------------------------------------
633 \item[Overlapping instance declarations:]
634 \index{overlapping instances}
635 \index{instances, overlapping}
637 In \tr{instance <context> => Class (T x1 ... xn)}, the \tr{xi}s can be
638 {\em types}, rather than just {\em type variables}.
640 Thus, you can have an instance \tr{instance Foo [Char]}, as well as
641 the more general \tr{instance Foo [a]}; the former will be used in
642 preference to the latter, where applicable.
644 As Lennart says, ``This is a dubious feature and should not be used
647 See also: \tr{SPECIALIZE instance} pragmas, in \Sectionref{faster}.