ghc/docs/users_guide/libraries.vsgml

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