2 % $Id: glasgow_exts.vsgml,v 1.1 1998/01/30 17:02:18 simonm Exp $
4 % GHC Language Extensions.
7 As with all known Haskell systems, GHC implements some extensions to
8 the language. To use them, you'll need to give a @-fglasgow-exts@%
9 <nidx>-fglasgow-exts option</nidx> option.
11 Virtually all of the Glasgow extensions serve to give you access to
12 the underlying facilities with which we implement Haskell. Thus, you
13 can get at the Raw Iron, if you are willing to write some non-standard
14 code at a more primitive level. You need not be ``stuck'' on
15 performance because of the implementation costs of Haskell's
16 ``high-level'' features---you can always code ``under'' them. In an
17 extreme case, you can write all your time-critical code in C, and then
18 just glue it together with Haskell!
20 Executive summary of our extensions:
24 <tag>Unboxed types and primitive operations:</tag>
26 You can get right down to the raw machine types and operations;
27 included in this are ``primitive arrays'' (direct access to Big Wads
28 of Bytes). Please see Section <ref name="Unboxed types"
29 id="glasgow-unboxed"> and following.
31 <tag>Multi-parameter type classes:</tag>
33 GHC's type system supports extended type classes with multiple
34 parameters. Please see Section <ref name="Mult-parameter type
35 classes" id="multi-param-type-classes">.
37 <tag>Local universal quantification:</tag>
39 GHC's type system supports explicit unversal quantification in
40 constructor fields and function arguments. This is useful for things
41 like defining @runST@ from the state-thread world amongst other
42 things. See Section <ref name="Local universal quantification"
43 id="universal-quantification">.
45 <tag>Calling out to C:</tag>
47 Just what it sounds like. We provide <em>lots</em> of rope that you
48 can dangle around your neck. Please see Section <ref name="Calling~C
49 directly from Haskell" id="glasgow-ccalls">.
53 Before you get too carried away working at the lowest level (e.g.,
54 sloshing @MutableByteArray#@s around your program), you may wish to
55 check if there are system libraries that provide a ``Haskellised
56 veneer'' over the features you want. See Section <ref name="GHC
57 Prelude and libraries" id="ghc-prelude">.
59 %************************************************************************
62 <label id="glasgow-unboxed">
64 <nidx>Unboxed types (Glasgow extension)</nidx>
66 %************************************************************************
68 These types correspond to the ``raw machine'' types you would use in
69 C: @Int#@ (long int), @Double#@ (double), @Addr#@ (void *), etc. The
70 <em>primitive operations</em> (PrimOps) on these types are what you
71 might expect; e.g., @(+#)@ is addition on @Int#@s, and is the
72 machine-addition that we all know and love---usually one instruction.
74 A numerically-intensive program using unboxed types can go a <em>lot</em>
75 faster than its ``standard'' counterpart---we saw a threefold speedup
78 Please see Section <ref name="The module PrelGHC: really primitive
79 stuff" id="ghc-libs-ghc"> for the details of unboxed types and the
82 %************************************************************************
84 <sect1>Primitive state-transformer monad
85 <label id="glasgow-ST-monad">
87 <nidx>state transformers (Glasgow extensions)</nidx>
88 <nidx>ST monad (Glasgow extension)</nidx>
90 %************************************************************************
92 This monad underlies our implementation of arrays, mutable and
93 immutable, and our implementation of I/O, including ``C calls''.
95 The @ST@ library, which provides access to the @ST@ monad, is a
96 GHC/Hugs extension library and is described in the separate <htmlurl
97 name="GHC/Hugs Extension Libraries" url="libs.html"> document.
99 %************************************************************************
101 <sect1>Primitive arrays, mutable and otherwise
102 <label id="glasgow-prim-arrays">
104 <nidx>primitive arrays (Glasgow extension)</nidx>
105 <nidx>arrays, primitive (Glasgow extension)</nidx>
107 %************************************************************************
109 GHC knows about quite a few flavours of Large Swathes of Bytes.
111 First, GHC distinguishes between primitive arrays of (boxed) Haskell
112 objects (type @Array# obj@) and primitive arrays of bytes (type
115 Second, it distinguishes between...
117 <tag>Immutable:</tag>
118 Arrays that do not change (as with ``standard'' Haskell arrays); you
119 can only read from them. Obviously, they do not need the care and
120 attention of the state-transformer monad.
123 Arrays that may be changed or ``mutated.'' All the operations on them
124 live within the state-transformer monad and the updates happen
127 <tag>``Static'' (in C land):</tag>
128 A C~routine may pass an @Addr#@ pointer back into Haskell land. There
129 are then primitive operations with which you may merrily grab values
130 over in C land, by indexing off the ``static'' pointer.
132 <tag>``Stable'' pointers:</tag>
133 If, for some reason, you wish to hand a Haskell pointer (i.e.,
134 <em>not</em> an unboxed value) to a C~routine, you first make the
135 pointer ``stable,'' so that the garbage collector won't forget that it
136 exists. That is, GHC provides a safe way to pass Haskell pointers to
139 Please see Section <ref name="Subverting automatic unboxing with
140 ``stable pointers''" id="glasgow-stablePtrs"> for more details.
142 <tag>``Foreign objects'':</tag>
143 A ``foreign object'' is a safe way to pass an external object (a
144 C~allocated pointer, say) to Haskell and have Haskell do the Right
145 Thing when it no longer references the object. So, for example, C
146 could pass a large bitmap over to Haskell and say ``please free this
147 memory when you're done with it.''
149 Please see Section <ref name="Pointing outside the Haskell heap"
150 id="glasgow-foreignObjs"> for more details.
154 The libraries section give more details on all these ``primitive
155 array'' types and the operations on them, Section <ref name="The GHC
156 Prelude and Libraries" id="ghc-prelude">. Some of these extensions
157 are also supported by Hugs, and the supporting libraries are described
158 in the <htmlurl name="GHC/Hugs Extension Libraries" url="libs.html">
161 %************************************************************************
163 <sect1>Using your own @mainIO@
164 <label id="own-mainIO">
166 <nidx>mainIO, rolling your own</nidx>
167 <nidx>GHCmain, module containing mainIO</nidx>
169 %************************************************************************
171 Normally, the GHC runtime system begins things by called an internal
178 which, in turn, fires up your @Main.main@. The standard
179 definition of @mainIO@ looks like this:
182 mainIO = catch Main.main
183 (\err -> error ("I/O error: " ++ show err ++ "\n"))
186 That is, all it does is run @Main.main@, catching any I/O errors that
187 occur and displaying them on standard error before exiting the
190 To subvert the above process, you need only provide a @mainIO@ of your
191 own (in a module named @PrelMain@).
193 Here's a little example, stolen from Alastair Reid:
196 module GHCmain ( mainIO ) where
203 _ccall_ printf "%d\n" (14::Int)
206 %************************************************************************
208 <sect1>Calling~C directly from Haskell
209 <label id="glasgow-ccalls">
211 <nidx>C calls (Glasgow extension)</nidx>
212 <nidx>_ccall_ (Glasgow extension)</nidx>
213 <nidx>_casm_ (Glasgow extension)</nidx>
215 %************************************************************************
217 GOOD ADVICE: Because this stuff is not Entirely Stable as far as names
218 and things go, you would be well-advised to keep your C-callery
219 corraled in a few modules, rather than sprinkled all over your code.
220 It will then be quite easy to update later on.
222 WARNING AS OF 2.03: Yes, the @_ccall_@ stuff probably <em>will
223 change</em>, to something better, of course! One step in that
224 direction is Green Card, a foreign function interface pre-processor
225 for Haskell (``Glasgow'' Haskell in particular) --- check out
228 ftp://ftp.dcs.gla.ac.uk/pub/haskell/glasgow/green-card.ANNOUNCE
229 ftp://ftp.dcs.gla.ac.uk/pub/haskell/glasgow/green-card-src.tar.gz
232 %************************************************************************
234 <sect2>@_ccall_@ and @_casm_@: an introduction
235 <label id="ccall-intro">
238 %************************************************************************
240 The simplest way to use a simple C function
243 double fooC( FILE *in, char c, int i, double d, unsigned int u )
246 is to provide a Haskell wrapper:
249 fooH :: Char -> Int -> Double -> Word -> IO Double
250 fooH c i d w = _ccall_ fooC (``stdin''::Addr) c i d w
253 The function @fooH@ will unbox all of its arguments, call the C
254 function @fooC@ and box the corresponding arguments.
256 One of the annoyances about @_ccall_@s is when the C types don't quite
257 match the Haskell compiler's ideas. For this, the @_casm_@ variant
258 may be just the ticket (NB: <em>no chance</em> of such code going
259 through a native-code generator):
263 = _casm_ ``%r = getenv((char *) %0);'' name >>= \ litstring@(A# str#) ->
265 if (litstring == ``NULL'') then
266 Left ("Fail:oldGetEnv:"++name)
268 Right (unpackCString# str#)
272 The first literal-literal argument to a @_casm_@ is like a @printf@
273 format: @%r@ is replaced with the ``result,'' @%0@--@%n-1@ are
274 replaced with the 1st--nth arguments. As you can see above, it is an
275 easy way to do simple C~casting. Everything said about @_ccall_@ goes
276 for @_casm_@ as well.
278 %************************************************************************
280 <sect2>Using function headers
281 <label id="glasgow-foreign-headers">
283 <nidx>C calls, function headers</nidx>
285 %************************************************************************
287 When generating C (using the @-fvia-C@ directive), one can assist the
288 C compiler in detecting type errors by using the @-#include@ directive
289 to provide @.h@ files containing function headers.
294 typedef unsigned long *StgForeignObj;
297 void initialiseEFS (StgInt size);
298 StgInt terminateEFS (void);
299 StgForeignObj emptyEFS(void);
300 StgForeignObj updateEFS (StgForeignObj a, StgInt i, StgInt x);
301 StgInt lookupEFS (StgForeignObj a, StgInt i);
304 You can find appropriate definitions for @StgInt@, @StgForeignObj@,
305 etc using @gcc@ on your architecture by consulting
306 @ghc/includes/StgTypes.lh@. The following table summarises the
307 relationship between Haskell types and C types.
310 <bf>C type name</bf> | <bf>Haskell Type</bf> @@
312 @StgChar@ | @Char#@ @@
314 @StgWord@ | @Word#@ @@
315 @StgAddr@ | @Addr#@ @@
316 @StgFloat@ | @Float#@ @@
317 @StgDouble@ | @Double#@ @@
319 @StgArray@ | @Array#@ @@
320 @StgByteArray@ | @ByteArray#@ @@
321 @StgArray@ | @MutableArray#@ @@
322 @StgByteArray@ | @MutableByteArray#@ @@
324 @StgStablePtr@ | @StablePtr#@ @@
325 @StgForeignObj@ | @ForeignObj#@
328 Note that this approach is only <em>essential</em> for returning
329 @float@s (or if @sizeof(int) != sizeof(int *)@ on your
330 architecture) but is a Good Thing for anyone who cares about writing
331 solid code. You're crazy not to do it.
333 %************************************************************************
335 <sect2>Subverting automatic unboxing with ``stable pointers''
336 <label id="glasgow-stablePtrs">
338 <nidx>stable pointers (Glasgow extension)</nidx>
340 %************************************************************************
342 The arguments of a @_ccall_@ are automatically unboxed before the
343 call. There are two reasons why this is usually the Right Thing to
348 C is a strict language: it would be excessively tedious to pass
349 unevaluated arguments and require the C programmer to force their
350 evaluation before using them.
352 <item> Boxed values are stored on the Haskell heap and may be moved
353 within the heap if a garbage collection occurs---that is, pointers
354 to boxed objects are not <em>stable</em>.
357 It is possible to subvert the unboxing process by creating a ``stable
358 pointer'' to a value and passing the stable pointer instead. For
359 example, to pass/return an integer lazily to C functions @storeC@ and
360 @fetchC@, one might write:
363 storeH :: Int -> IO ()
364 storeH x = makeStablePtr x >>= \ stable_x ->
365 _ccall_ storeC stable_x
368 fetchH x = _ccall_ fetchC >>= \ stable_x ->
369 deRefStablePtr stable_x >>= \ x ->
370 freeStablePtr stable_x >>
374 The garbage collector will refrain from throwing a stable pointer away
375 until you explicitly call one of the following from C or Haskell.
378 void freeStablePointer( StgStablePtr stablePtrToToss )
379 freeStablePtr :: StablePtr a -> IO ()
382 As with the use of @free@ in C programs, GREAT CARE SHOULD BE
383 EXERCISED to ensure these functions are called at the right time: too
384 early and you get dangling references (and, if you're lucky, an error
385 message from the runtime system); too late and you get space leaks.
387 And to force evaluation of the argument within @fooC@, one would
388 call one of the following C functions (according to type of argument).
391 void performIO ( StgStablePtr stableIndex /* StablePtr s (IO ()) */ );
392 StgInt enterInt ( StgStablePtr stableIndex /* StablePtr s Int */ );
393 StgFloat enterFloat ( StgStablePtr stableIndex /* StablePtr s Float */ );
396 <nidx>performIO</nidx>
397 <nidx>enterInt</nidx>
398 <nidx>enterFloat</nidx>
400 % ToDo ADR: test these functions!
402 Note Bene: @_ccall_GC_@<nidx>_ccall_GC_</nidx> must be used if any of
403 these functions are used.
405 %************************************************************************
407 <sect2>Pointing outside the Haskell heap
408 <label id="glasgow-foreignObjs">
410 <nidx>foreign objects (Glasgow extension)</nidx>
412 %************************************************************************
414 There are two types that @ghc@ programs can use to reference
415 (heap-allocated) objects outside the Haskell world: @Addr@ and
418 If you use @Addr@, it is up to you to the programmer to arrange
419 allocation and deallocation of the objects.
421 If you use @ForeignObj@, @ghc@'s garbage collector will call upon the
422 user-supplied <em>finaliser</em> function to free the object when the
423 Haskell world no longer can access the object. (An object is
424 associated with a finaliser function when the abstract
425 Haskell type @ForeignObj@ is created). The finaliser function is
426 expressed in C, and is passed as argument the object:
429 void foreignFinaliser ( StgForeignObj fo )
432 when the Haskell world can no longer access the object. Since
433 @ForeignObj@s only get released when a garbage collection occurs, we
434 provide ways of triggering a garbage collection from within C and from
438 void StgPerformGarbageCollection()
442 More information on the programmers' interface to @ForeignObj@ can be
443 found in Section <ref name="Foreign objects" id="sec:foreign-obj">.
445 %************************************************************************
447 <sect2>Avoiding monads
448 <label id="glasgow-avoiding-monads">
450 <nidx>C calls to `pure C'</nidx>
451 <nidx>unsafePerformIO</nidx>
453 %************************************************************************
455 The @_ccall_@ construct is part of the @IO@ monad because 9 out of 10
456 uses will be to call imperative functions with side effects such as
457 @printf@. Use of the monad ensures that these operations happen in a
458 predictable order in spite of laziness and compiler optimisations.
460 To avoid having to be in the monad to call a C function, it is
461 possible to use @unsafePerformIO@, which is available from the
462 @IOExts@ module. There are three situations where one might like to
463 call a C function from outside the IO world:
467 Calling a function with no side-effects:
469 atan2d :: Double -> Double -> Double
470 atan2d y x = unsafePerformIO (_ccall_ atan2d y x)
472 sincosd :: Double -> (Double, Double)
473 sincosd x = unsafePerformIO $ do
474 da <- newDoubleArray (0, 1)
475 _casm_ ``sincosd( %0, &((double *)%1[0]), &((double *)%1[1]) );'' x da
476 s <- readDoubleArray da 0
477 c <- readDoubleArray da 1
481 <item> Calling a set of functions which have side-effects but which can
482 be used in a purely functional manner.
484 For example, an imperative implementation of a purely functional
485 lookup-table might be accessed using the following functions.
489 update :: EFS x -> Int -> x -> EFS x
490 lookup :: EFS a -> Int -> a
492 empty = unsafePerformIO (_ccall_ emptyEFS)
494 update a i x = unsafePerformIO $
495 makeStablePtr x >>= \ stable_x ->
496 _ccall_ updateEFS a i stable_x
498 lookup a i = unsafePerformIO $
499 _ccall_ lookupEFS a i >>= \ stable_x ->
500 deRefStablePtr stable_x
503 You will almost always want to use @ForeignObj@s with this.
505 <item> Calling a side-effecting function even though the results will
506 be unpredictable. For example the @trace@ function is defined by:
509 trace :: String -> a -> a
512 ((_ccall_ PreTraceHook sTDERR{-msg-}):: IO ()) >>
513 fputs sTDERR string >>
514 ((_ccall_ PostTraceHook sTDERR{-msg-}):: IO ()) >>
517 sTDERR = (``stderr'' :: Addr)
520 (This kind of use is not highly recommended --- it is only really
521 useful in debugging code.)
524 %************************************************************************
526 <sect2>C-calling ``gotchas'' checklist
527 <label id="ccall-gotchas">
529 <nidx>C call dangers</nidx>
531 %************************************************************************
533 And some advice, too.
536 <item> For modules that use @_ccall_@s, etc., compile with
537 @-fvia-C@.<nidx>-fvia-C option</nidx> You don't have to, but you should.
539 Also, use the @-#include "prototypes.h"@ flag (hack) to inform the C
540 compiler of the fully-prototyped types of all the C functions you
541 call. (Section <ref name="Using function headers"
542 id="glasgow-foreign-headers"> says more about this...)
544 This scheme is the <em>only</em> way that you will get <em>any</em>
545 typechecking of your @_ccall_@s. (It shouldn't be that way,
549 Try to avoid @_ccall_@s to C~functions that take @float@
550 arguments or return @float@ results. Reason: if you do, you will
551 become entangled in (ANSI?) C's rules for when arguments/results are
552 promoted to @doubles@. It's a nightmare and just not worth it.
553 Use @doubles@ if possible.
555 If you do use @floats@, check and re-check that the right thing is
556 happening. Perhaps compile with @-keep-hc-file-too@ and look at
557 the intermediate C (@.hc@ file).
559 <item> The compiler uses two non-standard type-classes when
560 type-checking the arguments and results of @_ccall_@: the arguments
561 (respectively result) of @_ccall_@ must be instances of the class
562 @CCallable@ (respectively @CReturnable@). Both classes may be
563 imported from the module @CCall@, but this should only be
564 necessary if you want to define a new instance. (Neither class
565 defines any methods --- their only function is to keep the
568 The type checker must be able to figure out just which of the
569 C-callable/returnable types is being used. If it can't, you have to
570 add type signatures. For example,
576 is not good enough, because the compiler can't work out what type @x@
577 is, nor what type the @_ccall_@ returns. You have to write, say:
580 f :: Int -> IO Double
584 This table summarises the standard instances of these classes.
586 % ToDo: check this table against implementation!
589 <bf>Type</bf> |<bf>CCallable</bf>|<bf>CReturnable</bf> | <bf>Which is probably...</bf> @@
591 @Char@ | Yes | Yes | @unsigned char@ @@
592 @Int@ | Yes | Yes | @long int@ @@
593 @Word@ | Yes | Yes | @unsigned long int@ @@
594 @Addr@ | Yes | Yes | @void *@ @@
595 @Float@ | Yes | Yes | @float@ @@
596 @Double@ | Yes | Yes | @double@ @@
597 @()@ | No | Yes | @void@ @@
598 @[Char]@ | Yes | No | @char *@ (null-terminated) @@
600 @Array@ | Yes | No | @unsigned long *@ @@
601 @ByteArray@ | Yes | No | @unsigned long *@ @@
602 @MutableArray@ | Yes | No | @unsigned long *@ @@
603 @MutableByteArray@ | Yes | No | @unsigned long *@ @@
605 @State@ | Yes | Yes | nothing!@@
607 @StablePtr@ | Yes | Yes | @unsigned long *@ @@
608 @ForeignObjs@ | Yes | Yes | see later @@
611 The brave and careful programmer can add their own instances of these
612 classes for the following types:
616 A <em>boxed-primitive</em> type may be made an instance of both
617 @CCallable@ and @CReturnable@.
619 A boxed primitive type is any data type with a
620 single unary constructor with a single primitive argument. For
621 example, the following are all boxed primitive types:
626 data XDisplay = XDisplay Addr#
627 data EFS a = EFS# ForeignObj#
631 instance CCallable (EFS a)
632 instance CReturnable (EFS a)
635 <item> Any datatype with a single nullary constructor may be made an
636 instance of @CReturnable@. For example:
640 instance CReturnable MyVoid
643 <item> As at version 2.09, @String@ (i.e., @[Char]@) is still
644 not a @CReturnable@ type.
646 Also, the now-builtin type @PackedString@ is neither
647 @CCallable@ nor @CReturnable@. (But there are functions in
648 the PackedString interface to let you get at the necessary bits...)
651 <item> The code-generator will complain if you attempt to use @%r@ in
652 a @_casm_@ whose result type is @IO ()@; or if you don't use @%r@
653 <em>precisely</em> once for any other result type. These messages are
654 supposed to be helpful and catch bugs---please tell us if they wreck
657 <item> If you call out to C code which may trigger the Haskell garbage
658 collector (examples of this later...), then you must use the
659 @_ccall_GC_@<nidx>_ccall_GC_ primitive</nidx> or
660 @_casm_GC_@<nidx>_casm_GC_ primitive</nidx> variant of C-calls. (This
661 does not work with the native code generator - use @\fvia-C@.) This
662 stuff is hairy with a capital H! </itemize>
664 <sect1> Multi-parameter type classes
665 <label id="multi-param-type-classes">
670 <sect1> Local universal quantification
671 <label id="universal-quantification">