ghc/docs/users_guide/libraries.vsgml

   1 %
   2 % $Id: libraries.vsgml,v 1.3 1998/12/02 13:20:40 simonm Exp $
   3 %
   4 % GHC Prelude and Libraries.
   5 %
   6
   7 <sect>The GHC prelude and libraries
   8 <label id="ghc-prelude">
   9 <p>
  10
  11 This document describes GHC's prelude and libraries.  The basic story is that of
  12 the Haskell 1.4 Report and Libraries document (which we do not reproduce here),
  13 but this document describes in addition:
  14
  15 <itemize>
  16
  17 <item>  GHC's additional non-standard libraries and types, such as
  18         state transformers, packed strings, foreign objects, stable
  19         pointers, and so on.
  20
  21 <item>  GHC's primitive types and operations.  The standard Haskell
  22         functions are implemented on top of these, and it is sometimes
  23         useful to use them directly.
  24
  25 <item>  The organisation of these libraries into directories.
  26
  27 <item> Short description of programmer interface to the non-standard
  28        libraries provided in addition to the standard prelude.
  29 </itemize>
  30
  31 A number of the libraries that provide access to GHC's language
  32 extensions are shared by Hugs, and are described in the <htmlurl
  33 name="GHC/Hugs Extension Libraries" url="libs.html"> document.
  34
  35 <sect1>Prelude extensions
  36 <label id="ghc-prelude-exts">
  37 <p>
  38
  39 GHC's prelude contains the following non-standard extensions:
  40
  41 <descrip>
  42
  43 <tag>@fromInt@ method in class @Num@:</tag> It's there.  Converts from
  44 an @Int@ to the type.
  45
  46 <tag>@toInt@ method in class @Integral@:</tag> Converts from Integral
  47 type to an @Int@.
  48
  49 </descrip>
  50
  51 GHC also internally uses a number of modules that begin with the
  52 string @Prel@<nidx>Prel module prefix</nidx>: for this reason, we
  53 don't recommend that you use any module names beginning with @Prel@ in
  54 your own programs.  The @Prel@ modules are always available: in fact,
  55 you can get access to several extensions this way (for some you might
  56 need to give the @-fglasgow-exts@<nidx>-fglasgow-exts option</nidx>
  57 flag).
  58
  59 <sect1>The module @PrelGHC@: really primitive stuff
  60 <label id="ghc-libs-ghc">
  61 <p>
  62 <nidx>PrelGHC module</nidx>
  63
  64 This module defines all the types which are primitive in Glasgow
  65 Haskell, and the operations provided for them.
  66
  67 A primitive type is one which cannot be defined in Haskell, and which
  68 is therefore built into the language and compiler.  Primitive types
  69 are always unlifted; that is, a value of primitive type cannot be
  70 bottom.  We use the convention that primitive types, values, and
  71 operations have a @#@ suffix.
  72
  73 Primitive values are often represented by a simple bit-pattern, such
  74 as @Int#@, @Float#@, @Double#@.  But this is not necessarily the case:
  75 a primitive value might be represented by a pointer to a
  76 heap-allocated object.  Examples include @Array#@, the type of
  77 primitive arrays.  A primitive array is heap-allocated because it is
  78 too big a value to fit in a register, and would be too expensive to
  79 copy around; in a sense, it is accidental that it is represented by a
  80 pointer.  If a pointer represents a primitive value, then it really
  81 does point to that value: no unevaluated thunks, no
  82 indirections...nothing can be at the other end of the pointer than the
  83 primitive value.
  84
  85 <sect2>Unboxed Tuples
  86 <label id="unboxed-tuples">
  87 <p>
  88
  89 Unboxed tuples aren't really exported by @PrelGHC@, they're available
  90 by default with @-fglasgow-exts@.  An unboxed tuple looks like this:
  91
  92 <tscreen><verb>
  93 (# e_1, ..., e_n #)
  94 </verb></tscreen>
  95
  96 where @e_1..e_n@ are expressions of any type (primitive or
  97 non-primitive).  The type of an unboxed tuple looks the same.
  98
  99 Unboxed tuples are used for functions that need to return multiple
 100 values, but they avoid the heap allocation normally associated with
 101 using fully-fledged tuples.  When an unboxed tuple is returned, the
 102 components are put directly into registers or on the stack; the
 103 unboxed tuple itself does not have a composite representation.  Many
 104 of the primitive operations listed in this section return unboxed
 105 tuples.
 106
 107 There are some pretty stringent restrictions on the use of unboxed tuples:
 108
 109 <itemize>
 110
 111 <item> Unboxed tuple types are subject to the same restrictions as
 112 other unboxed types; i.e. they may not be stored in polymorphic data
 113 structures or passed to polymorphic functions.
 114
 115 <item> Unboxed tuples may only be constructed as the direct result of
 116 a function, and may only be deconstructed with a @case@ expression.
 117 eg. the following are valid:
 118
 119 <tscreen><verb>
 120 f x y = (# x+1, y-1 #)
 121 g x = case f x x of { (# a, b #) -> a + b }
 122 </verb></tscreen>
 123
 124 but the following are invalid:
 125
 126 <tscreen><verb>
 127 f x y = g (# x, y #)
 128 g (# x, y #) = x + y
 129 </verb></tscreen>
 130
 131 <item> No variable can have an unboxed tuple type.  This is illegal:
 132
 133 <tscreen><verb>
 134 f :: (# Int, Int #) -> (# Int, Int #)
 135 f x = x
 136 </verb></tscreen>
 137
 138 because @x@ has an unboxed tuple type.
 139
 140 </itemize>
 141
 142 Note: we may relax some of these restrictions in the future.
 143
 144 The @IO@ and @ST@ monads use unboxed tuples to avoid unnecessary
 145 allocation during sequences of operations.
 146
 147 <sect2>Character and numeric types
 148 <p>
 149 <nidx>character types, primitive</nidx>
 150 <nidx>numeric types, primitive</nidx>
 151 <nidx>integer types, primitive</nidx>
 152 <nidx>floating point types, primitive</nidx>
 153
 154 There are the following obvious primitive types:
 155
 156 <tscreen><verb>
 157 type Char#
 158 type Int#       -- see also Word# and Addr#, later
 159 type Float#
 160 type Double#
 161 </verb></tscreen>
 162 <ncdx>Char#</ncdx>
 163 <ncdx>Int#</ncdx>
 164 <ncdx>Float#</ncdx>
 165 <ncdx>Double#</ncdx>
 166
 167 If you really want to know their exact equivalents in C, see
 168 @ghc/includes/StgTypes.h@ in the GHC source tree.
 169
 170 Literals for these types may be written as follows:
 171
 172 <tscreen><verb>
 173 1#              an Int#
 174 1.2#            a Float#
 175 1.34##          a Double#
 176 'a'#            a Char#; for weird characters, use '\o<octal>'#
 177 "a"#            an Addr# (a `char *')
 178 </verb></tscreen>
 179 <nidx>literals, primitive</nidx>
 180 <nidx>constants, primitive</nidx>
 181 <nidx>numbers, primitive</nidx>
 182
 183 <sect2> Comparison operations
 184 <p>
 185 <nidx>comparisons, primitive</nidx>
 186 <nidx>operators, comparison</nidx>
 187
 188 <tscreen><verb>
 189 {>,>=,==,/=,<,<=}# :: Int# -> Int# -> Bool
 190
 191 {gt,ge,eq,ne,lt,le}Char# :: Char# -> Char# -> Bool
 192     -- ditto for Word# and Addr#
 193 </verb></tscreen>
 194 <ncdx>>#</ncdx>
 195 <ncdx>>=#</ncdx>
 196 <ncdx>==#</ncdx>
 197 <ncdx>/=#</ncdx>
 198 <ncdx><#</ncdx>
 199 <ncdx><=#</ncdx>
 200 <ncdx>gt{Char,Word,Addr}#</ncdx>
 201 <ncdx>ge{Char,Word,Addr}#</ncdx>
 202 <ncdx>eq{Char,Word,Addr}#</ncdx>
 203 <ncdx>ne{Char,Word,Addr}#</ncdx>
 204 <ncdx>lt{Char,Word,Addr}#</ncdx>
 205 <ncdx>le{Char,Word,Addr}#</ncdx>
 206
 207 <sect2> Primitive-character operations
 208 <p>
 209 <nidx>characters, primitive operations</nidx>
 210 <nidx>operators, primitive character</nidx>
 211
 212 <tscreen><verb>
 213 ord# :: Char# -> Int#
 214 chr# :: Int# -> Char#
 215 </verb></tscreen>
 216 <ncdx>ord#</ncdx>
 217 <ncdx>chr#</ncdx>
 218
 219
 220 <sect2> Primitive-@Int@ operations
 221 <p>
 222 <nidx>integers, primitive operations</nidx>
 223 <nidx>operators, primitive integer</nidx>
 224
 225 <tscreen><verb>
 226 {+,-,*,quotInt,remInt}# :: Int# -> Int# -> Int#
 227 negateInt# :: Int# -> Int#
 228
 229 iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
 230         -- shift left, right arithmetic, right logical
 231 </verb></tscreen>
 232 <ncdx>+#</ncdx>
 233 <ncdx>-#</ncdx>
 234 <ncdx>*#</ncdx>
 235 <ncdx>quotInt#</ncdx>
 236 <ncdx>remInt#</ncdx>
 237 <ncdx>iShiftL#</ncdx>
 238 <ncdx>iShiftRA#</ncdx>
 239 <ncdx>iShiftRL#</ncdx>
 240 <nidx>shift operations, integer</nidx>
 241
 242 <bf>Note:</bf> No error/overflow checking!
 243
 244 <sect2> Primitive-@Double@ and @Float@ operations
 245 <p>
 246 <nidx>floating point numbers, primitive</nidx>
 247 <nidx>operators, primitive floating point</nidx>
 248
 249 <tscreen><verb>
 250 {+,-,*,/}##         :: Double# -> Double# -> Double#
 251 {<,<=,==,/=,>=,>}## :: Double# -> Double# -> Bool
 252 negateDouble#       :: Double# -> Double#
 253 double2Int#         :: Double# -> Int#
 254 int2Double#         :: Int#    -> Double#
 255
 256 {plus,minux,times,divide}Float# :: Float# -> Float# -> Float#
 257 {gt,ge,eq,ne,lt,le}Float# :: Float# -> Float# -> Bool
 258 negateFloat#        :: Float# -> Float#
 259 float2Int#          :: Float# -> Int#
 260 int2Float#          :: Int#   -> Float#
 261 </verb></tscreen>
 262
 263 <ncdx>+##</ncdx>
 264 <ncdx>-##</ncdx>
 265 <ncdx>*##</ncdx>
 266 <ncdx>/##</ncdx>
 267 <ncdx><##</ncdx>
 268 <ncdx><=##</ncdx>
 269 <ncdx>==##</ncdx>
 270 <ncdx>=/##</ncdx>
 271 <ncdx>>=##</ncdx>
 272 <ncdx>>##</ncdx>
 273 <ncdx>negateDouble#</ncdx>
 274 <ncdx>double2Int#</ncdx>
 275 <ncdx>int2Double#</ncdx>
 276
 277 <ncdx>plusFloat#</ncdx>
 278 <ncdx>minusFloat#</ncdx>
 279 <ncdx>timesFloat#</ncdx>
 280 <ncdx>divideFloat#</ncdx>
 281 <ncdx>gtFloat#</ncdx>
 282 <ncdx>geFloat#</ncdx>
 283 <ncdx>eqFloat#</ncdx>
 284 <ncdx>neFloat#</ncdx>
 285 <ncdx>ltFloat#</ncdx>
 286 <ncdx>leFloat#</ncdx>
 287 <ncdx>negateFloat#</ncdx>
 288 <ncdx>float2Int#</ncdx>
 289 <ncdx>int2Float#</ncdx>
 290
 291 And a full complement of trigonometric functions:
 292
 293 <tscreen> <verb>
 294 expDouble#      :: Double# -> Double#
 295 logDouble#      :: Double# -> Double#
 296 sqrtDouble#     :: Double# -> Double#
 297 sinDouble#      :: Double# -> Double#
 298 cosDouble#      :: Double# -> Double#
 299 tanDouble#      :: Double# -> Double#
 300 asinDouble#     :: Double# -> Double#
 301 acosDouble#     :: Double# -> Double#
 302 atanDouble#     :: Double# -> Double#
 303 sinhDouble#     :: Double# -> Double#
 304 coshDouble#     :: Double# -> Double#
 305 tanhDouble#     :: Double# -> Double#
 306 powerDouble#    :: Double# -> Double# -> Double#
 307 </verb></tscreen>
 308 <nidx>trigonometric functions, primitive</nidx>
 309
 310 similarly for @Float#@.
 311
 312 There are two coercion functions for @Float#@/@Double#@:
 313
 314 <tscreen><verb>
 315 float2Double#   :: Float# -> Double#
 316 double2Float#   :: Double# -> Float#
 317 </verb></tscreen>
 318 <ncdx>float2Double#</ncdx>
 319 <ncdx>double2Float#</ncdx>
 320
 321 The primitive versions of @encodeDouble@/@decodeDouble@:
 322
 323 <tscreen><verb>
 324 encodeDouble#   :: Int# -> Int# -> ByteArray#   -- Integer mantissa
 325                 -> Int#                         -- Int exponent
 326                 -> Double#
 327
 328 decodeDouble#   :: Double# -> PrelNum.ReturnIntAndGMP
 329 </verb></tscreen>
 330 <ncdx>encodeDouble#</ncdx>
 331 <ncdx>decodeDouble#</ncdx>
 332
 333 (And the same for @Float#@s.)
 334
 335 <sect2>Operations on/for @Integers@ (interface to GMP)
 336 <label id="integer-operations">
 337 <p>
 338 <nidx>arbitrary precision integers</nidx>
 339 <nidx>Integer, operations on</nidx>
 340
 341 We implement @Integers@ (arbitrary-precision integers) using the GNU
 342 multiple-precision (GMP) package (version 2.0.2).
 343
 344 The data type for @Integer@ must mirror that for @MP_INT@ in @gmp.h@
 345 (see @gmp.info@ in @ghc/includes/runtime/gmp@).  It comes out as:
 346
 347 <tscreen><verb>
 348 data Integer = J# Int# Int# ByteArray#
 349 </verb></tscreen>
 350 <nidx>Integer type</nidx>
 351
 352 So, @Integer@ is really just a ``pairing'' type for a particular
 353 collection of primitive types.
 354
 355 The primitive ops to support @Integers@ use the ``pieces'' of the
 356 representation, and are as follows:
 357
 358 <tscreen><verb>
 359 negateInteger#  :: Int# -> Int# -> ByteArray# -> Integer
 360
 361 {plus,minus,times}Integer# :: Int# -> Int# -> ByteArray#
 362                            -> Int# -> Int# -> ByteArray#
 363                            -> Integer
 364
 365 cmpInteger# :: Int# -> Int# -> ByteArray#
 366             -> Int# -> Int# -> ByteArray#
 367             -> Int# -- -1 for <; 0 for ==; +1 for >
 368
 369 divModInteger#, quotRemInteger#
 370         :: Int# -> Int# -> ByteArray#
 371         -> Int# -> Int# -> ByteArray#
 372         -> PrelNum.Return2GMPs
 373
 374 integer2Int# :: Int# -> Int# -> ByteArray# -> Int#
 375
 376 int2Integer#  :: Int#  -> Integer -- NB: no error-checking on these two!
 377 word2Integer# :: Word# -> Integer
 378
 379 addr2Integer# :: Addr# -> Integer
 380         -- the Addr# is taken to be a `char *' string
 381         -- to be converted into an Integer.
 382 </verb></tscreen>
 383 <ncdx>negateInteger#</ncdx>
 384 <ncdx>plusInteger#</ncdx>
 385 <ncdx>minusInteger#</ncdx>
 386 <ncdx>timesInteger#</ncdx>
 387 <ncdx>cmpInteger#</ncdx>
 388 <ncdx>divModInteger#</ncdx>
 389 <ncdx>quotRemInteger#</ncdx>
 390 <ncdx>integer2Int#</ncdx>
 391 <ncdx>int2Integer#</ncdx>
 392 <ncdx>word2Integer#</ncdx>
 393 <ncdx>addr2Integer#</ncdx>
 394
 395 <sect2>Words and addresses
 396 <p>
 397 <nidx>word, primitive type</nidx>
 398 <nidx>address, primitive type</nidx>
 399 <nidx>unsigned integer, primitive type</nidx>
 400 <nidx>pointer, primitive type</nidx>
 401
 402 A @Word#@ is used for bit-twiddling operations.  It is the same size as
 403 an @Int#@, but has no sign nor any arithmetic operations.
 404 <tscreen><verb>
 405 type Word#      -- Same size/etc as Int# but *unsigned*
 406 type Addr#      -- A pointer from outside the "Haskell world" (from C, probably);
 407                 -- described under "arrays"
 408
 409 </verb></tscreen>
 410 <ncdx>Word#</ncdx>
 411 <ncdx>Addr#</ncdx>
 412
 413 @Word#@s and @Addr#@s have the usual comparison operations.
 414 Other unboxed-@Word@ ops (bit-twiddling and coercions):
 415
 416 <tscreen><verb>
 417 and#, or#, xor# :: Word# -> Word# -> Word#
 418         -- standard bit ops.
 419
 420 quotWord#, remWord# :: Word# -> Word# -> Word#
 421         -- word (i.e. unsigned) versions are different from int
 422         -- versions, so we have to provide these explicitly.
 423
 424 not# :: Word# -> Word#
 425
 426 shiftL#, shiftRA#, shiftRL# :: Word# -> Int# -> Word#
 427         -- shift left, right arithmetic, right logical
 428
 429 int2Word#       :: Int#  -> Word# -- just a cast, really
 430 word2Int#       :: Word# -> Int#
 431 </verb></tscreen>
 432 <nidx>bit operations, Word and Addr</nidx>
 433 <ncdx>and#</ncdx>
 434 <ncdx>or#</ncdx>
 435 <ncdx>xor#</ncdx>
 436 <ncdx>not#</ncdx>
 437 <ncdx>quotWord#</ncdx>
 438 <ncdx>remWord#</ncdx>
 439 <ncdx>shiftL#</ncdx>
 440 <ncdx>shiftRA#</ncdx>
 441 <ncdx>shiftRL#</ncdx>
 442 <ncdx>int2Word#</ncdx>
 443 <ncdx>word2Int#</ncdx>
 444
 445 Unboxed-@Addr@ ops (C casts, really):
 446 <tscreen><verb>
 447 int2Addr#       :: Int#  -> Addr#
 448 addr2Int#       :: Addr# -> Int#
 449 </verb></tscreen>
 450 <ncdx>int2Addr#</ncdx>
 451 <ncdx>addr2Int#</ncdx>
 452
 453 The casts between @Int#@, @Word#@ and @Addr#@ correspond to null
 454 operations at the machine level, but are required to keep the Haskell
 455 type checker happy.
 456
 457 Operations for indexing off of C pointers (@Addr#@s) to snatch values
 458 are listed under ``arrays''.
 459
 460 <sect2>Arrays
 461 <p>
 462 <nidx>arrays, primitive</nidx>
 463
 464 The type @Array# elt@ is the type of primitive, unpointed arrays of
 465 values of type @elt@.
 466
 467 <tscreen><verb>
 468 type Array# elt
 469 </verb></tscreen>
 470 <ncdx>Array#</ncdx>
 471
 472 @Array#@ is more primitive than a Haskell array --- indeed, the
 473 Haskell @Array@ interface is implemented using @Array#@ --- in that an
 474 @Array#@ is indexed only by @Int#@s, starting at zero.  It is also
 475 more primitive by virtue of being unboxed.  That doesn't mean that it
 476 isn't a heap-allocated object - of course, it is.  Rather, being
 477 unboxed means that it is represented by a pointer to the array itself,
 478 and not to a thunk which will evaluate to the array (or to bottom).
 479 The components of an @Array#@ are themselves boxed.
 480
 481 The type @ByteArray#@ is similar to @Array#@, except that it contains
 482 just a string of (non-pointer) bytes.
 483
 484 <tscreen><verb>
 485 type ByteArray#
 486 </verb></tscreen>
 487 <ncdx>ByteArray#</ncdx>
 488
 489 Arrays of these types are useful when a Haskell program wishes to
 490 construct a value to pass to a C procedure. It is also possible to
 491 use them to build (say) arrays of unboxed characters for internal use
 492 in a Haskell program.  Given these uses, @ByteArray#@ is deliberately
 493 a bit vague about the type of its components.  Operations are provided
 494 to extract values of type @Char#@, @Int#@, @Float#@, @Double#@, and
 495 @Addr#@ from arbitrary offsets within a @ByteArray#@.  (For type
 496 @Foo#@, the $i$th offset gets you the $i$th @Foo#@, not the @Foo#@ at
 497 byte-position $i$.  Mumble.)  (If you want a @Word#@, grab an @Int#@,
 498 then coerce it.)
 499
 500 Lastly, we have static byte-arrays, of type @Addr#@ [mentioned
 501 previously].  (Remember the duality between arrays and pointers in C.)
 502 Arrays of this types are represented by a pointer to an array in the
 503 world outside Haskell, so this pointer is not followed by the garbage
 504 collector.  In other respects they are just like @ByteArray#@.  They
 505 are only needed in order to pass values from C to Haskell.
 506
 507 <sect2>Reading and writing
 508 <p>
 509
 510 Primitive arrays are linear, and indexed starting at zero.
 511
 512 The size and indices of a @ByteArray#@, @Addr#@, and
 513 @MutableByteArray#@ are all in bytes.  It's up to the program to
 514 calculate the correct byte offset from the start of the array.  This
 515 allows a @ByteArray#@ to contain a mixture of values of different
 516 type, which is often needed when preparing data for and unpicking
 517 results from C.  (Umm... not true of indices... WDP 95/09)
 518
 519 <em>Should we provide some @sizeOfDouble#@ constants?</em>
 520
 521 Out-of-range errors on indexing should be caught by the code which
 522 uses the primitive operation; the primitive operations themselves do
 523 <em>not</em> check for out-of-range indexes. The intention is that the
 524 primitive ops compile to one machine instruction or thereabouts.
 525
 526 We use the terms ``reading'' and ``writing'' to refer to accessing
 527 <em>mutable</em> arrays (see Section~<ref name="Mutable arrays" id="sect:mutable">), and
 528 ``indexing'' to refer to reading a value from an <em>immutable</em>
 529 array.
 530
 531 Immutable byte arrays are straightforward to index (all indices in bytes):
 532 <tscreen><verb>
 533 indexCharArray#   :: ByteArray# -> Int# -> Char#
 534 indexIntArray#    :: ByteArray# -> Int# -> Int#
 535 indexAddrArray#   :: ByteArray# -> Int# -> Addr#
 536 indexFloatArray#  :: ByteArray# -> Int# -> Float#
 537 indexDoubleArray# :: ByteArray# -> Int# -> Double#
 538
 539 indexCharOffAddr#   :: Addr# -> Int# -> Char#
 540 indexIntOffAddr#    :: Addr# -> Int# -> Int#
 541 indexFloatOffAddr#  :: Addr# -> Int# -> Float#
 542 indexDoubleOffAddr# :: Addr# -> Int# -> Double#
 543 indexAddrOffAddr#   :: Addr# -> Int# -> Addr#
 544  -- Get an Addr# from an Addr# offset
 545 </verb></tscreen>
 546 <ncdx>indexCharArray#</ncdx>
 547 <ncdx>indexIntArray#</ncdx>
 548 <ncdx>indexAddrArray#</ncdx>
 549 <ncdx>indexFloatArray#</ncdx>
 550 <ncdx>indexDoubleArray#</ncdx>
 551 <ncdx>indexCharOffAddr#</ncdx>
 552 <ncdx>indexIntOffAddr#</ncdx>
 553 <ncdx>indexFloatOffAddr#</ncdx>
 554 <ncdx>indexDoubleOffAddr#</ncdx>
 555 <ncdx>indexAddrOffAddr#</ncdx>
 556
 557 The last of these, @indexAddrOffAddr#@, extracts an @Addr#@ using an offset
 558 from another @Addr#@, thereby providing the ability to follow a chain of
 559 C pointers.
 560
 561 Something a bit more interesting goes on when indexing arrays of boxed
 562 objects, because the result is simply the boxed object. So presumably
 563 it should be entered --- we never usually return an unevaluated
 564 object!  This is a pain: primitive ops aren't supposed to do
 565 complicated things like enter objects.  The current solution is to
 566 return a single element unboxed tuple (see Section <ref name="Unboxed
 567 Tuples" id="unboxed-tuples">).
 568
 569 <tscreen><verb>
 570 indexArray#       :: Array# elt -> Int# -> (# elt #)
 571 </verb></tscreen>
 572 <ncdx>indexArray#</ncdx>
 573
 574
 575 <sect2>The state type
 576 <p>
 577 <ncdx>state, primitive type</ncdx>
 578 <ncdx>State#</ncdx>
 579
 580 The primitive type @State#@ represents the state of a state
 581 transformer.  It is parameterised on the desired type of state, which
 582 serves to keep states from distinct threads distinct from one another.
 583 But the <em>only</em> effect of this parameterisation is in the type
 584 system: all values of type @State#@ are represented in the same way.
 585 Indeed, they are all represented by nothing at all!  The code
 586 generator ``knows'' to generate no code, and allocate no registers
 587 etc, for primitive states.
 588
 589 <tscreen><verb>
 590 type State# s
 591 </verb></tscreen>
 592
 593 The type @GHC.RealWorld@ is truly opaque: there are no values defined
 594 of this type, and no operations over it.  It is ``primitive'' in that
 595 sense - but it is <em>not unlifted!</em> Its only role in life is to be
 596 the type which distinguishes the @IO@ state transformer.
 597
 598 <tscreen><verb>
 599 data RealWorld
 600 </verb></tscreen>
 601
 602 <sect2>State of the world
 603 <p>
 604
 605 A single, primitive, value of type @State# RealWorld@ is provided.
 606
 607 <tscreen><verb>
 608 realWorld# :: State# RealWorld
 609 </verb></tscreen>
 610 <nidx>realWorld# state object</nidx>
 611
 612 (Note: in the compiler, not a @PrimOp@; just a mucho magic
 613 @Id@. Exported from @GHC@, though).
 614
 615 <sect2>Mutable arrays
 616 <p>
 617 <label id="sect:mutable">
 618 <nidx>mutable arrays</nidx>
 619 <nidx>arrays, mutable</nidx>
 620
 621 Corresponding to @Array#@ and @ByteArray#@, we have the types of
 622 mutable versions of each.  In each case, the representation is a
 623 pointer to a suitable block of (mutable) heap-allocated storage.
 624
 625 <tscreen><verb>
 626 type MutableArray# s elt
 627 type MutableByteArray# s
 628 </verb></tscreen>
 629 <ncdx>MutableArray#</ncdx>
 630 <ncdx>MutableByteArray#</ncdx>
 631
 632 <sect3>Allocation
 633 <p>
 634 <nidx>mutable arrays, allocation</nidx>
 635 <nidx>arrays, allocation</nidx>
 636 <nidx>allocation, of mutable arrays</nidx>
 637
 638 Mutable arrays can be allocated. Only pointer-arrays are initialised;
 639 arrays of non-pointers are filled in by ``user code'' rather than by
 640 the array-allocation primitive.  Reason: only the pointer case has to
 641 worry about GC striking with a partly-initialised array.
 642
 643 <tscreen><verb>
 644 newArray#       :: Int# -> elt -> State# s -> (# State# s, MutableArray# s elt #)
 645
 646 newCharArray#   :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
 647 newIntArray#    :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
 648 newAddrArray#   :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
 649 newFloatArray#  :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
 650 newDoubleArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
 651 </verb></tscreen>
 652 <ncdx>newArray#</ncdx>
 653 <ncdx>newCharArray#</ncdx>
 654 <ncdx>newIntArray#</ncdx>
 655 <ncdx>newAddrArray#</ncdx>
 656 <ncdx>newFloatArray#</ncdx>
 657 <ncdx>newDoubleArray#</ncdx>
 658
 659 The size of a @ByteArray#@ is given in bytes.
 660
 661 <sect3>Reading and writing
 662 <p>
 663 <nidx>arrays, reading and writing</nidx>
 664
 665 <tscreen><verb>
 666 readArray#       :: MutableArray# s elt -> Int# -> State# s -> (# State# s, elt #)
 667 readCharArray#   :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
 668 readIntArray#    :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
 669 readAddrArray#   :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
 670 readFloatArray#  :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
 671 readDoubleArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
 672
 673 writeArray#       :: MutableArray# s elt -> Int# -> elt     -> State# s -> State# s
 674 writeCharArray#   :: MutableByteArray# s -> Int# -> Char#   -> State# s -> State# s
 675 writeIntArray#    :: MutableByteArray# s -> Int# -> Int#    -> State# s -> State# s
 676 writeAddrArray#   :: MutableByteArray# s -> Int# -> Addr#   -> State# s -> State# s
 677 writeFloatArray#  :: MutableByteArray# s -> Int# -> Float#  -> State# s -> State# s
 678 writeDoubleArray# :: MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
 679 </verb></tscreen>
 680 <ncdx>readArray#</ncdx>
 681 <ncdx>readCharArray#</ncdx>
 682 <ncdx>readIntArray#</ncdx>
 683 <ncdx>readAddrArray#</ncdx>
 684 <ncdx>readFloatArray#</ncdx>
 685 <ncdx>readDoubleArray#</ncdx>
 686 <ncdx>writeArray#</ncdx>
 687 <ncdx>writeCharArray#</ncdx>
 688 <ncdx>writeIntArray#</ncdx>
 689 <ncdx>writeAddrArray#</ncdx>
 690 <ncdx>writeFloatArray#</ncdx>
 691 <ncdx>writeDoubleArray#</ncdx>
 692
 693
 694 <sect3>Equality
 695 <p>
 696 <nidx>arrays, testing for equality</nidx>
 697
 698 One can take ``equality'' of mutable arrays.  What is compared is the
 699 <em>name</em> or reference to the mutable array, not its contents.
 700
 701 <tscreen><verb>
 702 sameMutableArray#     :: MutableArray# s elt -> MutableArray# s elt -> Bool
 703 sameMutableByteArray# :: MutableByteArray# s -> MutableByteArray# s -> Bool
 704 </verb></tscreen>
 705 <ncdx>sameMutableArray#</ncdx>
 706 <ncdx>sameMutableByteArray#</ncdx>
 707
 708 <sect3>Freezing mutable arrays
 709 <p>
 710 <nidx>arrays, freezing mutable</nidx>
 711 <nidx>freezing mutable arrays</nidx>
 712 <nidx>mutable arrays, freezing</nidx>
 713
 714 Only unsafe-freeze has a primitive.  (Safe freeze is done directly in Haskell
 715 by copying the array and then using @unsafeFreeze@.)
 716
 717 <tscreen><verb>
 718 unsafeFreezeArray#     :: MutableArray# s elt -> State# s -> (# State# s, Array# s elt #)
 719 unsafeFreezeByteArray# :: MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
 720 </verb></tscreen>
 721 <ncdx>unsafeFreezeArray#</ncdx>
 722 <ncdx>unsafeFreezeByteArray#</ncdx>
 723
 724 <sect2>Stable pointers
 725 <p>
 726 <nidx>stable pointers</nidx>
 727 <nidx>pointers, stable</nidx>
 728
 729 A stable pointer is a name for a Haskell object which can be passed to
 730 the external world.  It is ``stable'' in the sense that the name does
 731 not change when the Haskell garbage collector runs --- in contrast to
 732 the address of the object which may well change.
 733
 734 The stable pointer type is parameterised by the type of the thing
 735 which is named.
 736
 737 <tscreen><verb>
 738 type StablePtr# a
 739 </verb></tscreen>
 740 <ncdx>StablePtr#</ncdx>
 741
 742 A stable pointer is represented by an index into the (static)
 743 @StablePointerTable@.  The Haskell garbage collector treats the
 744 @StablePointerTable@ as a source of roots for GC.
 745
 746 The @makeStablePointer@ function converts a value into a stable
 747 pointer.  It is part of the @IO@ monad, because we want to be sure
 748 we don't allocate one twice by accident, and then only free one of the
 749 copies.
 750
 751 <tscreen><verb>
 752 makeStablePointer#  :: a -> State# RealWorld -> (# State# RealWord, StablePtr# a #)
 753 freeStablePointer#  :: StablePtr# a -> State# RealWorld -> State# RealWorld
 754 deRefStablePointer# :: StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
 755 </verb></tscreen>
 756 <ncdx>makeStablePointer#</ncdx>
 757 <ncdx>freeStablePointer#</ncdx>
 758 <ncdx>deRefStablePointer#</ncdx>
 759
 760 There is also a C procedure @FreeStablePtr@ which frees a stable pointer.
 761
 762 %<em>Andy's comment.</em> {\bf Errors:} The following is not strictly true: the current
 763 %implementation is not as polymorphic as claimed.  The reason for this
 764 %is that the C programmer will have to use a different entry-routine
 765 %for each type of stable pointer.  At present, we only supply a very
 766 %limited number (3) of these routines.  It might be possible to
 767 %increase the range of these routines by providing general purpose
 768 %entry points to apply stable pointers to (stable pointers to)
 769 %arguments and to enter (stable pointers to) boxed primitive values.
 770 %<em>End of Andy's comment.</em>
 771
 772 <sect2>Foreign objects
 773 <p>
 774 <nidx>Foreign objects</nidx>
 775
 776 A @ForeignObj#@ is a reference to an object outside the Haskell world
 777 (i.e., from the C world, or a reference to an object on another
 778 machine completely.), where the Haskell world has been told ``Let me
 779 know when you're finished with this ...''.
 780
 781 <tscreen><verb>
 782 type ForeignObj#
 783 </verb></tscreen>
 784 <ncdx>ForeignObj#</ncdx>
 785
 786 GHC provides two primitives on @ForeignObj#@:
 787
 788 <tscreen><verb>
 789 makeForeignObj#
 790         :: Addr# -- foreign reference
 791         -> Addr# -- pointer to finalisation routine
 792         -> (# State# RealWorld, ForeignObj# )
 793 writeForeignObj
 794         :: ForeignObj#        -- foreign object
 795         -> Addr#              -- datum
 796         -> State# RealWorld
 797         -> State# RealWorld
 798 </verb></tscreen>
 799 <ncdx>makeForeignObj#</ncdx>
 800 <ncdx>writeForeignObj#</ncdx>
 801
 802 The module @Foreign@ (Section <ref name="Foreign objects"
 803 id="sec:foreign-obj">) provides a more programmer-friendly interface
 804 to foreign objects.
 805
 806 <sect2>Synchronizing variables (M-vars)
 807 <p>
 808 <nidx>synchronising variables (M-vars)</nidx>
 809 <nidx>M-Vars</nidx>
 810
 811 Synchronising variables are the primitive type used to implement
 812 Concurrent Haskell's MVars (see the Concurrent Haskell paper for
 813 the operational behaviour of these operations).
 814
 815 <tscreen><verb>
 816 type MVar# s elt        -- primitive
 817
 818 newMVar#    :: State# s -> (# State# s, MVar# s elt #)
 819 takeMVar#   :: SynchVar# s elt -> State# s -> (# State# s, elt #)
 820 putMVar#    :: SynchVar# s elt -> State# s -> State# s
 821 </verb></tscreen>
 822 <ncdx>SynchVar#</ncdx>
 823 <ncdx>newSynchVar#</ncdx>
 824 <ncdx>takeMVar</ncdx>
 825 <ncdx>putMVar</ncdx>
 826
 827 <sect1>GHC/Hugs Extension Libraries
 828 <p>
 829
 830 The extension libraries provided by both GHC and Hugs are described in
 831 the <htmlurl name="GHC/Hugs Extension Libraries" url="libs.html">
 832 document.
 833
 834 <sect1>GHC-only Extension Libraries
 835 <p>
 836 <nidx>libraries, ghc-only</nidx>
 837 <nidx>extension libraries, ghc-only</nidx>
 838
 839 If you rely on the implicit @import Prelude@ that GHC normally does
 840 for you, and if you don't use any weird flags (notably
 841 @-fglasgow-exts@), and if you don't import the Glasgow extensions
 842 interface, @GlaExts@, then GHC should work <em>exactly</em> as the
 843 Haskell report says (modulo a few minor issues, see Section <ref
 844 id="vs-Haskell-defn" name="Language Non-compliance">).
 845
 846 If you turn on @-fglasgow-exts@, the compiler will recognise and parse
 847 unboxed values properly, and provide access to the various interfaces
 848 libraries described here.
 849
 850 <sect2>The @GlaExts@ interface
 851 <p>
 852 <nidx>GlaExts interface (GHC extensions)</nidx>
 853
 854 The @GlaExts@ interface provides access to extensions that only GHC
 855 implements.  These currently are: unboxed types, including the
 856 representations of the primitive types (Int, Float, etc.), and the
 857 GHC primitive operations (@+#@, @==#@, etc.).
 858
 859 This module used to provide access to all the Glasgow extensions, but
 860 these have since been moved into separate libraries for compatibility
 861 with Hugs (version 2.09: in fact, you can still get at this stuff via
 862 @GlaExts@ for compatibility, but this facility will likely be removed
 863 in the future).
 864
 865 <tscreen><verb>
 866 -- the representation of some basic types:
 867 data Char    = C# Char#
 868 data Int     = I# Int#
 869 data Addr    = A# Addr#
 870 data Word    = W# Word#
 871 data Float   = F# Float#
 872 data Double  = D# Double#
 873 data Integer = J# Int# Int# ByteArray#
 874
 875 module GHC  -- all primops and primitive types.
 876 </verb></tscreen>
 877
 878 <sect2>The @MutableArray@ interface
 879 <label id="sec:mutable-array">
 880 <p>
 881 <nidx>MutableArray interface (GHC extensions)</nidx>
 882
 883 The @MutableArray@ interface defines a general set of operations over
 884 mutable arrays (@MutableArray@) and mutable chunks of memory
 885 (@MutableByteArray@):
 886
 887 <tscreen><verb>
 888 data MutableArray s ix elt -- abstract
 889 data MutableByteArray s ix -- abstract
 890                            -- instance of : CCallable
 891 -- Creators:
 892 newArray           :: Ix ix => (ix,ix) -> elt -> ST s (MutableArray s ix elt)
 893 newCharArray       :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
 894 newAddrArray       :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
 895 newIntArray        :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
 896 newFloatArray      :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
 897 newDoubleArray     :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
 898
 899 boundsOfArray      :: Ix ix => MutableArray s ix elt -> (ix, ix)
 900 boundsOfByteArray  :: Ix ix => MutableByteArray s ix -> (ix, ix)
 901
 902
 903 readArray          :: Ix ix => MutableArray s ix elt -> ix -> ST s elt
 904
 905 readCharArray      :: Ix ix => MutableByteArray s ix -> ix -> ST s Char
 906 readIntArray       :: Ix ix => MutableByteArray s ix -> ix -> ST s Int
 907 readAddrArray      :: Ix ix => MutableByteArray s ix -> ix -> ST s Addr
 908 readFloatArray     :: Ix ix => MutableByteArray s ix -> ix -> ST s Float
 909 readDoubleArray    :: Ix ix => MutableByteArray s ix -> ix -> ST s Double
 910
 911 writeArray         :: Ix ix => MutableArray s ix elt -> ix -> elt -> ST s ()
 912 writeCharArray     :: Ix ix => MutableByteArray s ix -> ix -> Char -> ST s ()
 913 writeIntArray      :: Ix ix => MutableByteArray s ix -> ix -> Int  -> ST s ()
 914 writeAddrArray     :: Ix ix => MutableByteArray s ix -> ix -> Addr -> ST s ()
 915 writeFloatArray    :: Ix ix => MutableByteArray s ix -> ix -> Float -> ST s ()
 916 writeDoubleArray   :: Ix ix => MutableByteArray s ix -> ix -> Double -> ST s ()
 917
 918 freezeArray        :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
 919 freezeCharArray    :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
 920 freezeIntArray     :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
 921 freezeAddrArray    :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
 922 freezeFloatArray   :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
 923 freezeDoubleArray  :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
 924
 925 unsafeFreezeArray     :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
 926 unsafeFreezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
 927 thawArray             :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt)
 928 </verb></tscreen>
 929
 930 <nidx>newArray</nidx>
 931 <nidx>newCharArray</nidx>
 932 <nidx>newAddrArray</nidx>
 933 <nidx>newIntArray</nidx>
 934 <nidx>newFloatArray</nidx>
 935 <nidx>newDoubleArray</nidx>
 936 <nidx>boundsOfArray</nidx>
 937 <nidx>boundsOfByteArray</nidx>
 938 <nidx>readArray</nidx>
 939 <nidx>readCharArray</nidx>
 940 <nidx>readIntArray</nidx>
 941 <nidx>readAddrArray</nidx>
 942 <nidx>readFloatArray</nidx>
 943 <nidx>readDoubleArray</nidx>
 944 <nidx>writeArray</nidx>
 945 <nidx>writeCharArray</nidx>
 946 <nidx>writeIntArray</nidx>
 947 <nidx>writeAddrArray</nidx>
 948 <nidx>writeFloatArray</nidx>
 949 <nidx>writeDoubleArray</nidx>
 950 <nidx>freezeArray</nidx>
 951 <nidx>freezeCharArray</nidx>
 952 <nidx>freezeIntArray</nidx>
 953 <nidx>freezeAddrArray</nidx>
 954 <nidx>freezeFloatArray</nidx>
 955 <nidx>freezeDoubleArray</nidx>
 956 <nidx>unsafeFreezeArray</nidx>
 957 <nidx>unsafeFreezeByteArray</nidx>
 958 <nidx>thawArray</nidx>
 959
 960 <sect2>The @ByteArray@ interface
 961 <label id="sec:byte-array">
 962 <p>
 963 <nidx>ByteArray interface (GHC extensions)</nidx>
 964
 965 @ByteArray@s are chunks of immutable Haskell heap:
 966
 967 <tscreen><verb>
 968 data ByteArray ix -- abstract
 969                   -- instance of: CCallable
 970
 971 indexCharArray     :: Ix ix => ByteArray ix -> ix -> Char
 972 indexIntArray      :: Ix ix => ByteArray ix -> ix -> Int
 973 indexAddrArray     :: Ix ix => ByteArray ix -> ix -> Addr
 974 indexFloatArray    :: Ix ix => ByteArray ix -> ix -> Float
 975 indexDoubleArray   :: Ix ix => ByteArray ix -> ix -> Double
 976
 977 indexCharOffAddr   :: Addr -> Int -> Char
 978 indexIntOffAddr    :: Addr -> Int -> Int
 979 indexAddrOffAddr   :: Addr -> Int -> Addr
 980 indexFloatOffAddr  :: Addr -> Int -> Float
 981 indexDoubleOffAddr :: Addr -> Int -> Double
 982 </verb></tscreen>
 983
 984 <sect2>Stable pointers
 985 <p>
 986
 987 Nothing exciting here, just simple boxing up.
 988 <tscreen><verb>
 989 data StablePtr a = StablePtr (StablePtr# a)
 990
 991 makeStablePointer :: a -> StablePtr a
 992 freeStablePointer :: StablePtr a -> IO ()
 993 </verb></tscreen>
 994
 995 <sect2>Foreign objects
 996 <label id="sec:foreign-obj">
 997 <p>
 998 <nidx>Foreign objects</nidx>
 999
1000 This module provides the @ForeignObj@ type and wrappers around the
1001 primitive operations on foreign objects.
1002
1003 <tscreen><verb>
1004 data ForeignObj = ForeignObj ForeignObj#
1005
1006 makeForeignObj
1007         :: Addr   -- object to be boxed up as a ForeignObj
1008         -> Addr   -- finaliser
1009         -> IO ForeignObj
1010
1011 writeForeignObj
1012         :: ForeignObj   -- previously created foreign object
1013         -> Addr         -- new value
1014         -> IO ()
1015
1016 </verb></tscreen>
1017 <ncdx>ForeignObj</ncdx>
1018 <ncdx>makeForeignObj</ncdx>
1019 <ncdx>writeForeignObj</ncdx>
1020
1021 A typical use of @ForeignObj@ is in constructing Haskell bindings
1022 to external libraries. A good example is that of writing a binding to
1023 an image-processing library (which was actually the main motivation
1024 for implementing @ForeignObj@'s precursor, @MallocPtr#@). The
1025 images manipulated are not stored in the Haskell heap, either because
1026 the library insist on allocating them internally or we (sensibly)
1027 decide to spare the GC from having to heave heavy images around.
1028
1029 <tscreen><verb>
1030 data Image = Image ForeignObj
1031 </verb></tscreen>
1032
1033 The @ForeignObj@ type is then used to refer to the externally
1034 allocated image, and to acheive some type safety, the Haskell binding
1035 defines the @Image@ data type. So, a value of type @ForeignObj@ is
1036 used to ``box'' up an external reference into a Haskell heap object
1037 that we can then indirectly reference:
1038
1039 <tscreen><verb>
1040 createImage :: (Int,Int) -> IO Image
1041 </verb></tscreen>
1042
1043 So far, this looks just like an @Addr@ type, but @ForeignObj@ offers a
1044 bit more, namely that we can specify a <em>finalisation routine</em> to
1045 invoke when the @ForeignObj@ is discarded by the GC. The garbage
1046 collector invokes the finalisation routine associated with the
1047 @ForeignObj@, saying `` Thanks, I'm through with this now..'' For the
1048 image-processing library, the finalisation routine could for the
1049 images free up memory allocated for them. The finalisation routine has
1050 currently to be written in C (the finalisation routine can in turn
1051 call on @FreeStablePtr@ to deallocate a stable pointer).
1052
1053 Associating a finalisation routine with an external object is done by
1054 calling @makeForeignObj@.  {\bf Note:} the foreign object value and
1055 its finaliser are contained in the @ForeignObj@, so there's no danger
1056 of an aggressive optimiser somehow separating the two (with the result
1057 that the foreign reference would not be freed).
1058
1059 (Implementation: a linked list of all @ForeignObj#@s is maintained to
1060  allow the garbage collector to detect when a @ForeignObj#@ becomes
1061  garbage.)
1062
1063 Like @Array@, @ForeignObj#@s are represented by heap objects.
1064
1065 Upon controlled termination of the Haskell program, all @ForeignObjs@
1066 are freed, invoking their respective finalisers before terminating.
1067
1068 <sect2>The @CCall@ module
1069 <p>
1070
1071 The @CCall@ module defines the classes @CCallable@ and @CReturnable@,
1072 along with instances for the primitive types (@Int@, @Int#@, @Float@,
1073 @Float#@ etc.)  GHC knows to import this module if you use @_ccall_@,
1074 but if you need to define your own instances of these classes, you
1075 will need to import @CCall@ explicitly.
1076
1077 More information on how to use @_ccall_@ can be found in Section
1078 <ref name="Calling~C directly from Haskell" id="glasgow-ccalls">.
1079