ghc/docs/users_guide/libraries.vsgml

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