1 \documentstyle[a4wide,grasp]{article}
2 \renewcommand{\textfraction}{0.1}
3 \renewcommand{\floatpagefraction}{0.9}
4 \renewcommand{\dblfloatpagefraction}{0.9}
11 \title{GHC prelude: types and operations}
12 \author{Simon L Peyton Jones \and John Launchbury \and Will Partain}
17 This ``state interface document'' corresponds to Glasgow Haskell
20 \section{Really primitive stuff}
22 This section defines all the types which are primitive in Glasgow Haskell, and the
23 operations provided for them.
25 A primitive type is one which cannot be defined in Haskell, and which is
26 therefore built into the language and compiler.
27 Primitive types are always unboxed; that is, a value of primitive type cannot be
30 Primitive values are often represented by a simple bit-pattern, such as @Int#@,
31 @Float#@, @Double#@. But this is not necessarily the case: a primitive value
32 might be represented by a pointer to a heap-allocated object. Examples include
33 @Array#@, the type of primitive arrays. You might think this odd: doesn't being
34 heap-allocated mean that it has a box? No, it does not. A primitive array is
35 heap-allocated because it is too big a value to fit in a register, and would be
36 too expensive to copy around; in a sense, it is accidental that it is represented
37 by a pointer. If a pointer represents a primitive value, then it really does
38 point to that value: no unevaluated thunks, no indirections...nothing can be at
39 the other end of the pointer than the primitive value.
41 This section also describes a few non-primitive types, which are needed
42 to express the result types of some primitive operations.
44 \subsection{Character and numeric types}
46 There are the following obvious primitive types:
49 type Int# -- see also Word# and Addr#, later
53 If you want to know their exact equivalents in C, see
54 @ghc/includes/StgTypes.lh@ in the GHC source.
56 Literals for these types may be written as follows:
61 'a'# a Char#; for weird characters, use '\o<octal>'#
62 "a"# an Addr# (a `char *')
65 \subsubsection{Comparison operations}
67 {gt,ge,eq,ne,lt,le}Char# :: Char# -> Char# -> Bool
68 -- ditto for Int#, Word#, Float#, Double#, and Addr#
71 \subsubsection{Unboxed-character operations}
77 \subsubsection{Unboxed-@Int@ operations}
79 {plus,minus,times,quot,div,rem}Int# :: Int# -> Int# -> Int#
80 negateInt# :: Int# -> Int#
82 NB: No error/overflow checking!
84 \subsubsection{Unboxed-@Float@ and @Double@ operations}
86 {plus,minus,times,divide}Float# :: Float# -> Float# -> Float#
87 negateFloat# :: Float# -> Float#
89 float2Int# :: Float# -> Int# -- just a cast, no checking!
90 int2Float# :: Int# -> Float#
92 expFloat# :: Float# -> Float#
93 logFloat# :: Float# -> Float#
94 sqrtFloat# :: Float# -> Float#
95 sinFloat# :: Float# -> Float#
96 cosFloat# :: Float# -> Float#
97 tanFloat# :: Float# -> Float#
98 asinFloat# :: Float# -> Float#
99 acosFloat# :: Float# -> Float#
100 atanFloat# :: Float# -> Float#
101 sinhFloat# :: Float# -> Float#
102 coshFloat# :: Float# -> Float#
103 tanhFloat# :: Float# -> Float#
104 powerFloat# :: Float# -> Float# -> Float#
106 There's an exactly-matching set of unboxed-@Double@ ops; replace
107 @Float#@ with @Double#@ in the list above. There are two
108 coercion functions for @Float#@/@Double#@:
110 float2Double# :: Float# -> Double#
111 double2Float# :: Double# -> Float#
113 The primitive versions of @encodeFloat@/@decodeFloat@:
115 encodeFloat# :: Int# -> Int# -> ByteArray# -- Integer mantissa
116 -> Int# -- Int exponent
119 decodeFloat# :: Float#
122 (And the same for @Double#@s.)
124 \subsection{Operations on/for @Integers@ (interface to GMP)}
125 \label{sect:horrid-Integer-pairing-types}
127 We implement @Integers@ (arbitrary-precision integers) using the GNU
128 multiple-precision (GMP) package.
130 The data type for @Integer@ must mirror that for @MP_INT@ in @gmp.h@
131 (see @gmp.info@). It comes out as:
133 data Integer = J# Int# Int# ByteArray#
135 So, @Integer@ is really just a ``pairing'' type for a particular
136 collection of primitive types.
138 The operations in the GMP return other combinations of
139 GMP-plus-something, so we need ``pairing'' types for those, too:
141 type _ReturnGMP = Integer -- synonym
142 data _Return2GMPs = _Return2GMPs Int# Int# ByteArray#
144 data _ReturnIntAndGMP = _ReturnIntAndGMP Int#
147 -- ????? something to return a string of bytes (in the heap?)
149 The primitive ops to support @Integers@ use the ``pieces'' of the
150 representation, and are as follows:
152 negateInteger# :: Int# -> Int# -> ByteArray# -> Integer
154 {plus,minus,times}Integer# :: Int# -> Int# -> ByteArray#
155 -> Int# -> Int# -> ByteArray#
158 cmpInteger# :: Int# -> Int# -> ByteArray#
159 -> Int# -> Int# -> ByteArray#
160 -> Int# -- -1 for <; 0 for ==; +1 for >
162 divModInteger#, quotRemInteger#
163 :: Int# -> Int# -> ByteArray#
164 -> Int# -> Int# -> ByteArray#
167 integer2Int# :: Int# -> Int# -> ByteArray#
170 int2Integer# :: Int# -> Integer -- NB: no error-checking on these two!
171 word2Integer# :: Word# -> Integer
173 addr2Integer# :: Addr# -> Integer
174 -- the Addr# is taken to be a `char *' string
175 -- to be converted into an Integer
179 \subsection{Words and addresses}
181 A @Word#@ is used for bit-twiddling operations. It is the same size as
182 an @Int#@, but has no sign nor any arithmetic operations.
184 type Word# -- Same size/etc as Int# but *unsigned*
185 type Addr# -- A pointer from outside the "Haskell world" (from C, probably);
186 -- described under "arrays"
188 @Word#@s and @Addr#@s have the usual comparison operations.
189 Other unboxed-@Word@ ops (bit-twiddling and coercions):
191 and#, or# :: Word# -> Word# -> Word#
193 not# :: Word# -> Word#
195 shiftL#, shiftRA#, shiftRL# :: Word# -> Int# -> Word#
196 -- shift left, right arithmetic, right logical
198 iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
199 -- same shift ops, but on Int#s
201 int2Word# :: Int# -> Word# -- just a cast, really
202 word2Int# :: Word# -> Int#
205 Unboxed-@Addr@ ops (C casts, really):
207 int2Addr# :: Int# -> Addr#
208 addr2Int# :: Addr# -> Int#
210 Operations for indexing off of C pointers (@Addr#@s) to snatch values
211 are listed under ``arrays''.
215 The type @Array# elt@ is the type of primitive,
216 unboxed arrays of values of type @elt@.
220 @Array#@ is more primitive than a Haskell
221 array --- indeed, Haskell arrays are implemented using @Array#@ ---
222 in that an @Array#@ is indexed only by @Int#@s, starting at zero. It is also
223 more primitive by virtue of being unboxed. That doesn't mean that it isn't
224 a heap-allocated object --- of course, it is. Rather, being unboxed means
225 that it is represented by a pointer to the array itself, and not to a thunk
226 which will evaluate to the array (or to bottom).
227 The components of an @Array#@ are themselves boxed.
229 The type @ByteArray#@ is similar to @Array#@, except that it contains
230 just a string of (non-pointer) bytes.
234 Arrays of these types are useful when a Haskell program wishes to
235 construct a value to pass to a C procedure. It is also possible to
236 use them to build (say) arrays of unboxed characters for internal use
237 in a Haskell program. Given these uses, @ByteArray#@ is deliberately
238 a bit vague about the type of its components. Operations are provided
239 to extract values of type @Char#@, @Int#@, @Float#@, @Double#@, and
240 @Addr#@ from arbitrary offsets within a @ByteArray#@. (For type @Foo#@,
241 the $i$th offset gets you the $i$th @Foo#@, not the @Foo#@ at byte-position $i$. Mumble.)
242 (If you want a @Word#@, grab an @Int#@, then coerce it.)
244 Lastly, we have static byte-arrays, of type @Addr#@ [mentioned
245 previously]. (Remember the duality between arrays and pointers in C.)
246 Arrays of this types are represented by a pointer to an array in the
247 world outside Haskell, so this pointer is not followed by the garbage
248 collector. In other respects they are just like @ByteArray#@. They
249 are only needed in order to pass values from C to Haskell.
251 \subsubsection{Reading and writing.}
253 Primitive arrays are linear, and indexed starting at zero.
255 The size and indices of a @ByteArray#@, @Addr#@, and
256 @MutableByteArray#@ are all in bytes. It's up to the program to
257 calculate the correct byte offset from the start of the array. This
258 allows a @ByteArray#@ to contain a mixture of values of different
259 type, which is often needed when preparing data for and unpicking
260 results from C. (Umm... not true of indices... WDP 95/09)
262 {\em Should we provide some @sizeOfDouble#@ constants?}
264 Out-of-range errors on indexing should be caught by the code which
265 uses the primitive operation; the primitive operations themselves do
266 {\em not} check for out-of-range indexes. The intention is that the
267 primitive ops compile to one machine instruction or thereabouts.
269 We use the terms ``reading'' and ``writing'' to refer to accessing {\em mutable}
270 arrays (see Section~\ref{sect:mutable}), and ``indexing''
271 to refer to reading a value from an {\em immutable}
274 If you want to read/write a @Word#@, read an @Int#@ and coerce.
276 Immutable byte arrays are straightforward to index (all indices in bytes):
278 indexCharArray# :: ByteArray# -> Int# -> Char#
279 indexIntArray# :: ByteArray# -> Int# -> Int#
280 indexAddrArray# :: ByteArray# -> Int# -> Addr#
281 indexFloatArray# :: ByteArray# -> Int# -> Float#
282 indexDoubleArray# :: ByteArray# -> Int# -> Double#
284 indexCharOffAddr# :: Addr# -> Int# -> Char#
285 indexIntOffAddr# :: Addr# -> Int# -> Int#
286 indexFloatOffAddr# :: Addr# -> Int# -> Float#
287 indexDoubleOffAddr# :: Addr# -> Int# -> Double#
288 indexAddrOffAddr# :: Addr# -> Int# -> Addr# -- Get an Addr# from an Addr# offset
290 The last of these, @indexAddrOffAddr#@, extracts an @Addr#@ using an offset
291 from another @Addr#@, thereby providing the ability to follow a chain of
294 Something a bit more interesting goes on when indexing arrays of boxed
295 objects, because the result is simply the boxed object. So presumably
296 it should be entered --- we never usually return an unevaluated
297 object! This is a pain: primitive ops aren't supposed to do
298 complicated things like enter objects. The current solution is to
299 return a lifted value, but I don't like it!
301 indexArray# :: Array# elt -> Int# -> _Lift elt -- Yuk!
304 \subsubsection{The state type}
306 The primitive type @State#@ represents the state of a state transformer.
307 It is parameterised on the desired type of state, which serves to keep
308 states from distinct threads distinct from one another. But the {\em only}
309 effect of this parameterisation is in the type system: all values of type
310 @State#@ are represented in the same way. Indeed, they are all
311 represented by nothing at all! The code generator ``knows'' to generate no
312 code, and allocate no registers etc, for primitive states.
317 The type @_RealWorld@ is truly opaque: there are no values defined
318 of this type, and no operations over it. It is ``primitive'' in that
319 sense---but it is {\em not unboxed!} Its only role in life is to be the type
320 which distinguishes the @PrimIO@ state transformer (see
321 Section~\ref{sect:io-spec}).
326 \subsubsection{States}
328 A single, primitive, value of type @State# _RealWorld@ is provided.
330 realWorld# :: State# _RealWorld
332 (Note: in the compiler, not a @PrimOp@; just a mucho magic @Id@.)
334 \subsection{State pairing types}
335 \label{sect:horrid-pairing-types}
337 This subsection defines some types which, while they aren't quite primitive
338 because we can define them in Haskell, are very nearly so. They define
339 constructors which pair a primitive state with a value of each primitive type.
340 They are required to express the result type of the primitive operations in the
343 data StateAndPtr# s elt = StateAndPtr# (State# s) elt
345 data StateAndChar# s = StateAndChar# (State# s) Char#
346 data StateAndInt# s = StateAndInt# (State# s) Int#
347 data StateAndWord# s = StateAndWord# (State# s) Word#
348 data StateAndFloat# s = StateAndFloat# (State# s) Float#
349 data StateAndDouble# s = StateAndDouble# (State# s) Double#
350 data StateAndAddr# s = StateAndAddr# (State# s) Addr#
352 data StateAndStablePtr# s a = StateAndStablePtr# (State# s) (StablePtr# a)
353 data StateAndForeignObj# s = StateAndForeignObj# (State# s) ForeignObj#
354 data StateAndSynchVar# s a = StateAndSynchVar# (State# s) (SynchVar# a)
356 data StateAndArray# s elt = StateAndArray# (State# s) (Array# elt)
357 data StateAndMutableArray# s elt = StateAndMutableArray# (State# s) (MutableArray# s elt)
358 data StateAndByteArray# s = StateAndByteArray# (State# s) ByteArray#
359 data StateAndMutableByteArray# s = StateAndMutableByteArray# (State# s) (MutableByteArray# s)
363 \subsection{Mutable arrays}
366 Corresponding to @Array#@ and @ByteArray#@,
367 we have the types of mutable versions of each.
368 In each case, the representation is a pointer
369 to a suitable block of (mutable) heap-allocated storage.
371 type MutableArray# s elt
372 type MutableByteArray# s
374 \subsubsection{Allocation.}
376 Mutable arrays can be allocated.
377 Only pointer-arrays are initialised; arrays of non-pointers are filled
378 in by ``user code'' rather than by the array-allocation primitive.
379 Reason: only the pointer case has to worry about GC striking with a
380 partly-initialised array.
382 newArray# :: Int# -> elt -> State# s -> StateAndMutableArray# s elt
384 newCharArray# :: Int# -> State# s -> StateAndMutableByteArray# s
385 newIntArray# :: Int# -> State# s -> StateAndMutableByteArray# s
386 newAddrArray# :: Int# -> State# s -> StateAndMutableByteArray# s
387 newFloatArray# :: Int# -> State# s -> StateAndMutableByteArray# s
388 newDoubleArray# :: Int# -> State# s -> StateAndMutableByteArray# s
390 The size of a @ByteArray#@ is given in bytes.
392 \subsubsection{Reading and writing}
394 %OLD: Remember, offsets in a @MutableByteArray#@ are in bytes.
396 readArray# :: MutableArray# s elt -> Int# -> State# s -> StateAndPtr# s elt
397 readCharArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndChar# s
398 readIntArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndInt# s
399 readAddrArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndAddr# s
400 readFloatArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndFloat# s
401 readDoubleArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndDouble# s
403 writeArray# :: MutableArray# s elt -> Int# -> elt -> State# s -> State# s
404 writeCharArray# :: MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
405 writeIntArray# :: MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
406 writeAddrArray# :: MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
407 writeFloatArray# :: MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
408 writeDoubleArray# :: MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
411 \subsubsection{Equality.}
413 One can take ``equality'' of mutable arrays. What is compared is the
414 {\em name} or reference to the mutable array, not its contents.
416 sameMutableArray# :: MutableArray# s elt -> MutableArray# s elt -> Bool
417 sameMutableByteArray# :: MutableByteArray# s -> MutableByteArray# s -> Bool
420 \subsubsection{Freezing mutable arrays}
422 Only unsafe-freeze has a primitive. (Safe freeze is done directly in Haskell
423 by copying the array and then using @unsafeFreeze@.)
425 unsafeFreezeArray# :: MutableArray# s elt -> State# s -> StateAndArray# s elt
426 unsafeFreezeByteArray# :: MutableByteArray# s -> State# s -> StateAndByteArray# s
429 \subsubsection{Stable pointers}
431 {\em Andy's comment.} {\bf Errors:} The following is not strictly true: the current
432 implementation is not as polymorphic as claimed. The reason for this
433 is that the C programmer will have to use a different entry-routine
434 for each type of stable pointer. At present, we only supply a very
435 limited number (1) of these routines. It might be possible to
436 increase the range of these routines by providing general purpose
437 entry points to apply stable pointers to (stable pointers to)
438 arguments and to enter (stable pointers to) boxed primitive values.
439 {\em End of Andy's comment.}
441 A stable pointer is a name for a Haskell object which can be passed to the
442 external world. It is ``stable'' in the sense that the name does not change when
443 the Haskell garbage collector runs --- in contrast to the address of the object
444 which may well change.
446 The stable pointer type is parameterised by the type of the thing which is named.
450 A stable pointer is represented by an index into the (static)
451 @StablePointerTable@. The Haskell garbage collector treats the
452 @StablePointerTable@ as a source of roots for GC.
454 The @makeStablePointer@ function converts a value into a stable pointer.
455 It is part of the @PrimIO@ monad, because we want to be sure we don't
456 allocate one twice by accident, and then only free one of the copies.
458 makeStablePointer# :: a -> State# _RealWorld -> StateAndStablePtr# _RealWorld a
459 freeStablePointer# :: StablePtr# a -> State# _RealWorld -> State# _RealWorld
460 deRefStablePointer# :: StablePtr# a -> State# _RealWorld -> StateAndPtr _RealWorld a
462 There is also a C procedure @FreeStablePtr@ which frees a stable pointer.
465 % Rewritten and updated for MallocPtr++ -- 4/96 SOF
467 \subsubsection{Foreign objects}
469 A \tr{ForeignObj} is a reference to an object outside the Haskell
470 world (i.e., from the C world, or a reference to an object on another
471 machine completely.), where the Haskell world has been told ``Let me
472 know when you're finished with this ...''.
474 The \tr{ForeignObj} type is just a special @Addr#@ ({\em not} parameterised).
479 A typical use of \tr{ForeignObj} is in constructing Haskell bindings
480 to external libraries. A good example is that of writing a binding to
481 an image-processing library (which was actually the main motivation
482 for implementing \tr{ForeignObj}'s precursor, \tr{MallocPtr}). The
483 images manipulated are not stored in the Haskell heap, either because
484 the library insist on allocating them internally or we (sensibly)
485 decide to spare the GC from having to heave heavy images around.
488 data Image = Image ForeignObj#
490 instance _CCallable Image
493 The \tr{ForeignObj#} type is then used to refer to the externally
494 allocated image, and to acheive some type safety, the Haskell binding
495 defines the @Image@ data type. So, a value of type \tr{ForeignObj#} is
496 used to ``box'' up an external reference into a Haskell heap object
497 that we can then indirectly reference:
500 createImage :: (Int,Int) -> PrimIO Image
503 So far, this looks just like an @Addr#@ type, but \tr{ForeignObj#}
504 offers a bit more, namely that we can specify a {\em finalisation
505 routine} to invoke when the \tr{ForeignObj#} is discarded by the
506 GC. The garbage collector invokes the finalisation routine associated
507 with the \tr{ForeignObj#}, saying `` Thanks, I'm through with this
508 now..'' For the image-processing library, the finalisation routine could for
509 the images free up memory allocated for them. The finalisation routine has
510 currently to be written in C (the finalisation routine can in turn call on
511 @FreeStablePtr@ to deallocate a stable pointer.).
513 Associating a finalisation routine with an external object is done by
514 \tr{makeForeignObj#}:
517 makeForeignObj# :: Addr# -- foreign reference
518 -> Addr# -- pointer to finalisation routine
519 -> StateAndForeignObj# _RealWorld ForeignObj#
522 (Implementation: a linked list of all @ForeignObj#@s is maintained to allow the
523 garbage collector to detect when a @ForeignObj#@ becomes garbage.)
525 Like @Array@, @ForeignObj#@s are represented by heap objects.
527 {\bf ToDo:} Decide whether @FreeCHeapPointer@ is allowed to call on a
528 stable pointer. (I sincerely hope not since we will still be in the
531 \subsubsection{Synchronizing variables (I-vars, M-vars)}
536 type SynchVar# s elt -- primitive
538 newSynchVar#:: State# s -> StateAndSynchVar# s elt
540 takeMVar# :: SynchVar# s elt -> State# s -> StateAndPtr# s elt
541 putMVar# :: SynchVar# s elt -> State# s -> State# s
543 readIVar# :: SynchVar# s elt -> State# s -> StateAndPtr# s elt
544 writeIVar# :: SynchVar# s elt -> State# s -> State# s
547 \subsubsection{Controlling the garbage collector}
549 The C function {\tt PerformGC\/}, allows the C world to force Haskell
550 to do a garbage collection. It can only be called while Haskell
551 is performing a C Call.
553 Note that this function can be used to define a Haskell IO operation
554 with the same effect:
556 > performGCIO :: PrimIO ()
557 > performGCIO = _ccall_gc_ PerformGC
560 {\bf ToDo:} Is there any need for abnormal/normal termination to force
561 a GC too? Is there any need for a function that provides finer
562 control over GC: argument = amount of space required; result = amount
565 \subsection{@spark#@ primitive operation (for parallel execution)}
567 {\em ToDo: say something} It's used in the unfolding for @par@.
569 \subsection{The @errorIO#@ primitive operation}
571 The @errorIO#@ primitive takes an argument of type @PrimIO@. It aborts execution of
572 the current program, and continues instead by performing the given @PrimIO@ value
573 on the current state of the world.
575 errorIO# :: PrimIO () -> a
580 {\bf ToDo:} current implementation has state variable as second
581 argument not last argument.
583 The @ccall#@ primitive can't be given an ordinary type, because it has
584 a variable number of arguments. The nearest we can get is:
586 ccall# :: CRoutine -> a1# -> ... -> an# -> State# _RealWorld -> StateAndR# _RealWorld
588 where the type variables @a1#@\ldots@an#@ and @r#@ can be instantiated by any
589 primitive type, and @StateAndR#@ is the appropriate pairing type from
590 Section~\ref{sect:horrid-pairing-types}. The @CRoutine@
591 isn't a proper Haskell type at all; it just reminds us that @ccall#@ needs to
592 know what C routine to call.
594 This notation is really short for a massive family of @ccall#@ primitives, one
595 for each combination of types. (Of course, the compiler simply remembers the
596 types involved, and generates appropriate code when it finally spits out the C.)
598 Unlike all the other primitive operators, @ccall#@ is not bound to an in-scope
599 identifier. The only way it is possible to generate a @ccall#@ is via the
602 All this applies equally to @casm#@:
604 casm# :: CAsmString -> a1# -> ... -> an# -> State# _RealWorld -> StateAndR# _RealWorld
607 %------------------------------------------------------------
608 \section{Library stuff built with the Really Primitive Stuff}
610 \subsection{The state transformer monad}
612 \subsubsection{Types}
614 A state transformer is a function from a state to a pair of a result and a new
617 type _ST s a = _State s -> (a, _State s)
619 The @_ST@ type is {\em abstract}, so that the programmer cannot see its
620 representation. If he could, he could write bad things like:
623 bad = \s -> ...(f s)...(g s)...
625 Here, @s@ is duplicated, which would be bad news.
627 A state is represented by a primitive state value, of type @State# s@,
628 wrapped up in a @_State@ constructor. The reason for boxing it in this
629 way is so that we can be strict or lazy in the state. (Remember, all
630 primitive types are unboxed, and hence can't be bottom; but types built
631 with @data@ are all boxed.)
633 data _State s = S# (State# s)
636 \subsubsection{The state transformer combinators}
638 Now for the combinators, all of which live inside the @_ST@
639 abstraction. Notice that @returnST@ and @thenST@ are lazy in the
642 returnST :: a -> _ST s a
643 returnST a s = (a, s)
645 thenST :: _ST s a -> (a -> _ST s b) -> _ST s b
646 thenST m k s = let (r,new_s) = m s
650 fixST :: (a -> _ST s a) -> _ST s a
651 fixST k s = let ans = k r s
656 The interesting one is, of course, @_runST@. We can't infer its type!
657 (It has a funny name because it must be wired into the compiler.)
659 -- _runST :: forall a. (forall s. _ST s a) -> a
660 _runST m = case m (S# realWorld#) of
664 \subsubsection{Other useful combinators}
666 There are various other standard combinators, all defined in terms the
667 fundamental combinators above. The @seqST@ combinator is like
668 @thenST@, except that it discards the result of the first state
671 seqST :: _ST s a -> _ST s b -> _ST s b
672 seqST m1 m2 = m1 `thenST` (\_ -> m2)
675 We also have {\em strict} (... in the state...) variants of the
676 then/return combinators (same types as their pals):
678 returnStrictlyST a s@(S# _) = (a, s)
680 thenStrictlyST m k s@(S# _)
681 = case (m s) of { (r, new_s@(S# _)) ->
684 seqStrictlyST m k = ... ditto, for seqST ...
687 The combinator @listST@ takes a list of state transformers, and
688 composes them in sequence, returning a list of their results:
690 listST :: [_ST s a] -> _ST s [a]
691 listST [] = returnST []
692 listST (m:ms) = m `thenST` \ r ->
693 listST ms `thenST` \ rs ->
696 The @mapST@ combinator ``lifts'' a function from a value to state
697 transformers to one which works over a list of values:
699 mapST :: (a -> _ST s b) -> [a] -> _ST s [b]
700 mapST f ms = listST (map f ms)
702 The @mapAndUnzipST@ combinator is similar to @mapST@, except that here the
703 function returns a pair:
705 mapAndUnzipST :: (a -> _ST s (b,c)) -> [a] -> _ST s ([b],[c])
706 mapAndUnzipST f (m:ms)
707 = f m `thenST` \ ( r1, r2) ->
708 mapAndUnzipST f ms `thenST` \ (rs1, rs2) ->
709 returnST (r1:rs1, r2:rs2)
712 \subsubsection{The @PrimIO@ monad}
715 The @PrimIO@ type is defined in as a state transformer which manipulates the
718 type PrimIO a = _ST _RealWorld a -- Transparent
720 The @PrimIO@ type is an ordinary type synonym, transparent to the programmer.
722 The type @_RealWorld@ and value @realWorld#@ do not need to be hidden (although
723 there is no particular point in exposing them). Even having a value of type
724 @realWorld#@ does not compromise safety, since the type @_ST@ is hidden.
726 It is type-correct to use @returnST@ in an I/O context, but it is a
727 bit more efficient to use @returnPrimIO@. The latter is strict in the
728 state, which propagates backwards to all the earlier combinators
729 (provided they are unfolded). Why is it safe for @returnPrimIO@ to be
730 strict in the state? Because every context in which an I/O state
731 transformer is used will certainly evaluate the resulting state; it is
732 the state of the real world!
734 returnPrimIO :: a -> PrimIO a
735 returnPrimIO a s@(S# _) -> (a, s)
737 We provide strict versions of the other combinators too.
739 thenPrimIO m k s = case m s of
742 @fixPrimIO@ has to be lazy, though!
746 The other combinators are just the same as before, but use the strict
747 @thenPrimIO@ and @returnPrimIO@ for efficiency.
749 foldrPrimIO f z [] = z
750 foldrPrimIO f z (m:ms) = foldrPrimIO f z ms `thenPrimIO` \ ms' ->
753 listPrimIO ms = foldrPrimIO (\ a xs -> a `thenPrimIO` \ x -> returnPrimIO (x : xs))
756 mapPrimIO f ms = listPrimIO (map f ms)
758 mapAndUnzipPrimIO f (m:ms)
759 = f m `thenPrimIO` \ ( r1, r2) ->
760 mapAndUnzipPrimIO f ms `thenPrimIO` \ (rs1, rs2) ->
761 returnPrimIO (r1:rs1, r2:rs2)
766 \subsubsection{Types}
769 data Array ix elt = _Array (ix,ix) (Array# elt)
770 data _ByteArray ix = _ByteArray (ix,ix) ByteArray#
772 data _MutableArray s ix elt = _MutableArray (ix,ix) (MutableArray# s elt)
773 data _MutableByteArray s ix = _MutableByteArray (ix,ix) (MutableByteArray# s)
776 \subsubsection{Operations on immutable arrays}
778 Ordinary array indexing is straightforward.
780 (!) :: Ix ix => Array ix elt -> ix -> elt
782 QUESTIONs: should @_ByteArray@s be indexed by Ints or ix? With byte offsets
783 or sized ones? (sized ones [WDP])
785 indexCharArray :: Ix ix => _ByteArray ix -> ix -> Char
786 indexIntArray :: Ix ix => _ByteArray ix -> ix -> Int
787 indexAddrArray :: Ix ix => _ByteArray ix -> ix -> _Addr
788 indexFloatArray :: Ix ix => _ByteArray ix -> ix -> Float
789 indexDoubleArray :: Ix ix => _ByteArray ix -> ix -> Double
791 @Addr@s are indexed straightforwardly by @Int@s. Unlike the primitive
792 operations, though, the offsets assume that the array consists entirely of the
793 type of value being indexed, and so there's an implicit multiplication by
794 the size of that value. To access @Addr@s with mixed values requires
795 you to do a DIY job using the primitives.
797 indexAddrChar :: Addr -> Int -> Char
799 indexStaticCharArray :: Addr -> Int -> Char
800 indexStaticIntArray :: Addr -> Int -> Int
801 indexStaticFloatArray :: Addr -> Int -> Float
802 indexStaticDoubleArray :: Addr -> Int -> Double
803 indexStaticArray :: Addr -> Int -> Addr
806 \subsubsection{Operations on mutable arrays}
808 newArray :: Ix ix => (ix,ix) -> elt -> _ST s (_MutableArray s ix elt)
809 newCharArray :: Ix ix => (ix,ix) -> _ST s (_MutableByteArray s ix)
814 readArray :: Ix ix => _MutableArray s ix elt -> ix -> _ST s elt
815 readCharArray :: Ix ix => _MutableByteArray s ix -> ix -> _ST s Char
820 writeArray :: Ix ix => _MutableArray s ix elt -> ix -> elt -> _ST s ()
821 writeCharArray :: Ix ix => _MutableByteArray s ix -> ix -> Char -> _ST s ()
826 freezeArray :: Ix ix => _MutableArray s ix elt -> _ST s (Array ix elt)
827 freezeCharArray :: Ix ix => _MutableByteArray s ix -> _ST s (_ByteArray ix)
831 We have no need on one-function-per-type for unsafe freezing:
833 unsafeFreezeArray :: Ix ix => _MutableArray s ix elt -> _ST s (Array ix elt)
834 unsafeFreezeByteArray :: Ix ix => _MutableByteArray s ix -> _ST s (_ByteArray ix)
837 Sometimes we want to snaffle the bounds of one of these beasts:
839 boundsOfArray :: Ix ix => _MutableArray s ix elt -> (ix, ix)
840 boundsOfByteArray :: Ix ix => _MutableByteArray s ix -> (ix, ix)
843 Lastly, ``equality'':
845 sameMutableArray :: _MutableArray s ix elt -> _MutableArray s ix elt -> Bool
846 sameMutableByteArray :: _MutableByteArray s ix -> _MutableByteArray s ix -> Bool
850 \subsection{Variables}
852 \subsubsection{Types}
854 Mutable variables are (for now anyway) implemented as arrays. The @MutableVar@ type
855 is opaque, so we can change the implementation later if we want.
857 type MutableVar s a = _MutableArray s Int a
860 \subsubsection{Operations}
862 newVar :: a -> _ST s (MutableVar s a)
863 readVar :: MutableVar s a -> _ST s a
864 writeVar :: MutableVar s a -> a -> _ST s ()
865 sameVar :: MutableVar s a -> MutableVar s a -> Bool
868 \subsection{Stable pointers}
870 Nothing exciting here, just simple boxing up.
872 data _StablePtr a = _StablePtr (StablePtr# a)
874 makeStablePointer :: a -> _StablePtr a
875 freeStablePointer :: _StablePtr a -> PrimIO ()
878 \subsection{Foreign objects}
880 Again, just boxing up.
882 data _ForeignObj = _ForeignObj ForeignObj#
884 makeForeignObj :: _Addr -> _Addr -> PrimIO _ForeignObj
889 Everything in this section goes for @_casm_@ too.
891 {\em ToDo: mention @_ccall_gc_@ and @_casm_gc_@...}
893 The @_ccall_@ construct has the following form:
894 $$@_ccall_@~croutine~a_1~\ldots~a_n$$
895 This whole construct has type $@PrimIO@~res$.
899 The first ``argument'', $croutine$, must be the literal name of a C procedure.
900 It cannot be a Haskell expression which evaluates to a string, etc; it must be
901 simply the name of the procedure.
903 The arguments $a_1, \ldots,a_n$ must be of {\em C-callable} type.
905 The whole construct has type $@PrimIO@~ty$, where $ty$ is a {\em C-returnable} type.
907 A {\em boxed-primitive} type is both C-callable and C-returnable.
908 A boxed primitive type is anything declared by:
912 where @t@ is a primitive type. Note that
913 programmer-defined boxed-primitive types are perfectly OK:
915 data Widget = W# Int#
916 data Screen = S# CHeapPtr#
919 There are other types that can be passed to C (C-callable). This
920 table summarises (including the standard boxed-primitive types):
922 Boxed Type of transferd Corresp. Which is
923 Type Prim. component C type *probably*...
924 ------ --------------- ------ -------------
925 Char Char# StgChar unsigned char
926 Int Int# StgInt long int
927 _Word Word# StgWord unsigned long int
928 _Addr Addr# StgAddr char *
929 Float Float# StgFloat float
930 Double Double# StgDouble double
932 Array Array# StgArray StgPtr
933 _ByteArray ByteArray# StgByteArray StgPtr
934 _MutableArray MutableArray# StgArray StgPtr
935 _MutableByteArray MutableByteArray# StgByteArray StgPtr
937 _State State# nothing!
939 _StablePtr StablePtr# StgStablePtr StgPtr
940 _ForeignObj ForeignObj# StgForeignObj StgPtr
943 All of the above are {\em C-returnable} except:
945 Array, _ByteArray, _MutableArray, _MutableByteArray
948 {\bf ToDo:} I'm pretty wary of @Array@ and @_MutableArray@ being in
949 this list, and not too happy about @_State@ [WDP].
951 {\bf ToDo:} Can code generator pass all the primitive types? Should this be
952 extended to include {\tt Bool\/} (or any enumeration type?)
954 The type checker must be able to figure out just which of the C-callable/returnable
955 types is being used. If it can't, you have to add type signatures. For example,
959 is not good enough, because the compiler can't work out what type @x@ is, nor
960 what type the @_ccall_@ returns. You have to write, say:
962 f :: Int -> PrimIO Float
966 \subsubsection{Implementation}
968 The desugarer unwraps the @_ccall_@ construct by inserting the necessary
969 evaluations etc to unbox the arguments. For example, the body of the definition
970 of @f@ above would become:
972 (\ s -> case x of { I# x# ->
974 case ccall# [Int#,Float#] x# s# of { StateAndFloat# f# new_s# ->
978 Notice that the state, too, is unboxed.
980 The code generator must deal specially with primitive objects which
981 are stored on the heap.
983 ... details omitted ...
986 %More importantly, it must construct a C Heap Pointer heap-object after
987 %a @_ccall_@ which returns a @MallocPtr#@.
990 %--------------------------------------------------------
991 \section{Non-primitive stuff that must be wired into GHC}
996 data _Word = W# Word#
997 data _Addr = A# Addr#
999 data Float = F# Float#
1000 data Double = D# Double#
1001 data Integer = J# Int# Int# ByteArray#
1003 -- and the other boxed-primitive types:
1004 Array, _ByteArray, _MutableArray, _MutableByteArray,
1005 _StablePtr, _ForeignObj
1007 data Bool = False | True
1008 data CMP_TAG# = LT# | EQ# | GT# -- used in derived comparisons
1010 data List a = [] | a : (List a)
1013 data Ratio a = a :% a
1014 type Rational = Ratio Integer
1016 data {Request,Response,etc} -- so we can check the type of "main"
1018 data _Lift a = _Lift a -- used Yukkily as described elsewhere
1020 type String = [Char] -- convenience, only
1023 %------------------------------------------------------------
1024 \section{Programmer interface(s)}
1026 \subsection{The bog-standard interface}
1028 If you rely on the implicit @import Prelude@ that GHC normally does
1029 for you, and if you don't use any weird flags (notably
1030 @-fglasgow-exts@), and if you don't import one of the fairly-magic
1031 @PreludeGla*@ interfaces, then GHC should work {\em exactly} as the
1032 Haskell report says, and the full user namespaces should be available
1035 Exception: until we burn in the new names @_scc_@ and @_ccall_@, the
1036 names @scc@ and @ccall@ are still available.
1038 \subsection{If you mess about with @import Prelude@...}
1040 Innocent renaming and hiding, e.g.,
1042 import Prelude hiding ( fromIntegral ) renaming (map to mop)
1044 should work just fine (even it {\em is} atrocious programming practice).
1046 There are some things you can do that will make GHC crash, e.g.,
1047 hiding a standard class:
1049 import Prelude hiding ( Eq(..) )
1053 \subsection{Turning on Glasgow extensions with @-fglasgow-exts@}
1055 If you turn on @-fglasgow-exts@, then all the primitive types and
1056 operations described herein are available.
1058 It is possible that some name conflicts between your code and the
1059 wired-in things might spring to life (though we doubt it...).
1060 Change your names :-)
1062 \subsection{@import PreludeGlaST@}
1065 type ST s a = _ST s a -- so you don't need -fglasgow-exts...
1068 \subsection{@import PreludeGlaMisc@}