ghc/docs/users_guide/libraries.vsgml

   1 %
   2 % $Id: libraries.vsgml,v 1.6 1999/08/17 15:39:38 simonpj 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 = S# Int#              -- small integers
 122              | J# Int# ByteArray#   -- large integers
 123
 124 module GHC  -- all primops and primitive types.
 125 </verb></tscreen>
 126
 127 <sect1>The module @PrelGHC@: really primitive stuff
 128 <label id="ghc-libs-ghc">
 129 <p>
 130 <nidx>PrelGHC module</nidx>
 131
 132 This module defines all the types which are primitive in Glasgow
 133 Haskell, and the operations provided for them.
 134
 135 A primitive type is one which cannot be defined in Haskell, and which
 136 is therefore built into the language and compiler.  Primitive types
 137 are always unlifted; that is, a value of primitive type cannot be
 138 bottom.  We use the convention that primitive types, values, and
 139 operations have a @#@ suffix.
 140
 141 Primitive values are often represented by a simple bit-pattern, such
 142 as @Int#@, @Float#@, @Double#@.  But this is not necessarily the case:
 143 a primitive value might be represented by a pointer to a
 144 heap-allocated object.  Examples include @Array#@, the type of
 145 primitive arrays.  A primitive array is heap-allocated because it is
 146 too big a value to fit in a register, and would be too expensive to
 147 copy around; in a sense, it is accidental that it is represented by a
 148 pointer.  If a pointer represents a primitive value, then it really
 149 does point to that value: no unevaluated thunks, no
 150 indirections...nothing can be at the other end of the pointer than the
 151 primitive value.
 152
 153 <sect2>Unboxed Tuples
 154 <label id="unboxed-tuples">
 155 <p>
 156
 157 Unboxed tuples aren't really exported by @PrelGHC@, they're available
 158 by default with @-fglasgow-exts@.  An unboxed tuple looks like this:
 159
 160 <tscreen><verb>
 161 (# e_1, ..., e_n #)
 162 </verb></tscreen>
 163
 164 where @e_1..e_n@ are expressions of any type (primitive or
 165 non-primitive).  The type of an unboxed tuple looks the same.
 166
 167 Unboxed tuples are used for functions that need to return multiple
 168 values, but they avoid the heap allocation normally associated with
 169 using fully-fledged tuples.  When an unboxed tuple is returned, the
 170 components are put directly into registers or on the stack; the
 171 unboxed tuple itself does not have a composite representation.  Many
 172 of the primitive operations listed in this section return unboxed
 173 tuples.
 174
 175 There are some pretty stringent restrictions on the use of unboxed tuples:
 176
 177 <itemize>
 178
 179 <item> Unboxed tuple types are subject to the same restrictions as
 180 other unboxed types; i.e. they may not be stored in polymorphic data
 181 structures or passed to polymorphic functions.
 182
 183 <item> Unboxed tuples may only be constructed as the direct result of
 184 a function, and may only be deconstructed with a @case@ expression.
 185 eg. the following are valid:
 186
 187 <tscreen><verb>
 188 f x y = (# x+1, y-1 #)
 189 g x = case f x x of { (# a, b #) -> a + b }
 190 </verb></tscreen>
 191
 192 but the following are invalid:
 193
 194 <tscreen><verb>
 195 f x y = g (# x, y #)
 196 g (# x, y #) = x + y
 197 </verb></tscreen>
 198
 199 <item> No variable can have an unboxed tuple type.  This is illegal:
 200
 201 <tscreen><verb>
 202 f :: (# Int, Int #) -> (# Int, Int #)
 203 f x = x
 204 </verb></tscreen>
 205
 206 because @x@ has an unboxed tuple type.
 207
 208 </itemize>
 209
 210 Note: we may relax some of these restrictions in the future.
 211
 212 The @IO@ and @ST@ monads use unboxed tuples to avoid unnecessary
 213 allocation during sequences of operations.
 214
 215 <sect2>Character and numeric types
 216 <p>
 217 <nidx>character types, primitive</nidx>
 218 <nidx>numeric types, primitive</nidx>
 219 <nidx>integer types, primitive</nidx>
 220 <nidx>floating point types, primitive</nidx>
 221
 222 There are the following obvious primitive types:
 223
 224 <tscreen><verb>
 225 type Char#
 226 type Int#       -- see also Word# and Addr#, later
 227 type Float#
 228 type Double#
 229 </verb></tscreen>
 230 <ncdx>Char#</ncdx>
 231 <ncdx>Int#</ncdx>
 232 <ncdx>Float#</ncdx>
 233 <ncdx>Double#</ncdx>
 234
 235 If you really want to know their exact equivalents in C, see
 236 @ghc/includes/StgTypes.h@ in the GHC source tree.
 237
 238 Literals for these types may be written as follows:
 239
 240 <tscreen><verb>
 241 1#              an Int#
 242 1.2#            a Float#
 243 1.34##          a Double#
 244 'a'#            a Char#; for weird characters, use '\o<octal>'#
 245 "a"#            an Addr# (a `char *')
 246 </verb></tscreen>
 247 <nidx>literals, primitive</nidx>
 248 <nidx>constants, primitive</nidx>
 249 <nidx>numbers, primitive</nidx>
 250
 251 <sect2> Comparison operations
 252 <p>
 253 <nidx>comparisons, primitive</nidx>
 254 <nidx>operators, comparison</nidx>
 255
 256 <tscreen><verb>
 257 {>,>=,==,/=,<,<=}# :: Int# -> Int# -> Bool
 258
 259 {gt,ge,eq,ne,lt,le}Char# :: Char# -> Char# -> Bool
 260     -- ditto for Word# and Addr#
 261 </verb></tscreen>
 262 <ncdx>>#</ncdx>
 263 <ncdx>>=#</ncdx>
 264 <ncdx>==#</ncdx>
 265 <ncdx>/=#</ncdx>
 266 <ncdx><#</ncdx>
 267 <ncdx><=#</ncdx>
 268 <ncdx>gt{Char,Word,Addr}#</ncdx>
 269 <ncdx>ge{Char,Word,Addr}#</ncdx>
 270 <ncdx>eq{Char,Word,Addr}#</ncdx>
 271 <ncdx>ne{Char,Word,Addr}#</ncdx>
 272 <ncdx>lt{Char,Word,Addr}#</ncdx>
 273 <ncdx>le{Char,Word,Addr}#</ncdx>
 274
 275 <sect2> Primitive-character operations
 276 <p>
 277 <nidx>characters, primitive operations</nidx>
 278 <nidx>operators, primitive character</nidx>
 279
 280 <tscreen><verb>
 281 ord# :: Char# -> Int#
 282 chr# :: Int# -> Char#
 283 </verb></tscreen>
 284 <ncdx>ord#</ncdx>
 285 <ncdx>chr#</ncdx>
 286
 287
 288 <sect2> Primitive-@Int@ operations
 289 <p>
 290 <nidx>integers, primitive operations</nidx>
 291 <nidx>operators, primitive integer</nidx>
 292
 293 <tscreen><verb>
 294 {+,-,*,quotInt,remInt}# :: Int# -> Int# -> Int#
 295 negateInt# :: Int# -> Int#
 296
 297 iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
 298         -- shift left, right arithmetic, right logical
 299 </verb></tscreen>
 300 <ncdx>+#</ncdx>
 301 <ncdx>-#</ncdx>
 302 <ncdx>*#</ncdx>
 303 <ncdx>quotInt#</ncdx>
 304 <ncdx>remInt#</ncdx>
 305 <ncdx>iShiftL#</ncdx>
 306 <ncdx>iShiftRA#</ncdx>
 307 <ncdx>iShiftRL#</ncdx>
 308 <nidx>shift operations, integer</nidx>
 309
 310 <bf>Note:</bf> No error/overflow checking!
 311
 312 <sect2> Primitive-@Double@ and @Float@ operations
 313 <p>
 314 <nidx>floating point numbers, primitive</nidx>
 315 <nidx>operators, primitive floating point</nidx>
 316
 317 <tscreen><verb>
 318 {+,-,*,/}##         :: Double# -> Double# -> Double#
 319 {<,<=,==,/=,>=,>}## :: Double# -> Double# -> Bool
 320 negateDouble#       :: Double# -> Double#
 321 double2Int#         :: Double# -> Int#
 322 int2Double#         :: Int#    -> Double#
 323
 324 {plus,minux,times,divide}Float# :: Float# -> Float# -> Float#
 325 {gt,ge,eq,ne,lt,le}Float# :: Float# -> Float# -> Bool
 326 negateFloat#        :: Float# -> Float#
 327 float2Int#          :: Float# -> Int#
 328 int2Float#          :: Int#   -> Float#
 329 </verb></tscreen>
 330
 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>>##</ncdx>
 341 <ncdx>negateDouble#</ncdx>
 342 <ncdx>double2Int#</ncdx>
 343 <ncdx>int2Double#</ncdx>
 344
 345 <ncdx>plusFloat#</ncdx>
 346 <ncdx>minusFloat#</ncdx>
 347 <ncdx>timesFloat#</ncdx>
 348 <ncdx>divideFloat#</ncdx>
 349 <ncdx>gtFloat#</ncdx>
 350 <ncdx>geFloat#</ncdx>
 351 <ncdx>eqFloat#</ncdx>
 352 <ncdx>neFloat#</ncdx>
 353 <ncdx>ltFloat#</ncdx>
 354 <ncdx>leFloat#</ncdx>
 355 <ncdx>negateFloat#</ncdx>
 356 <ncdx>float2Int#</ncdx>
 357 <ncdx>int2Float#</ncdx>
 358
 359 And a full complement of trigonometric functions:
 360
 361 <tscreen> <verb>
 362 expDouble#      :: Double# -> Double#
 363 logDouble#      :: Double# -> Double#
 364 sqrtDouble#     :: Double# -> Double#
 365 sinDouble#      :: Double# -> Double#
 366 cosDouble#      :: Double# -> Double#
 367 tanDouble#      :: Double# -> Double#
 368 asinDouble#     :: Double# -> Double#
 369 acosDouble#     :: Double# -> Double#
 370 atanDouble#     :: Double# -> Double#
 371 sinhDouble#     :: Double# -> Double#
 372 coshDouble#     :: Double# -> Double#
 373 tanhDouble#     :: Double# -> Double#
 374 powerDouble#    :: Double# -> Double# -> Double#
 375 </verb></tscreen>
 376 <nidx>trigonometric functions, primitive</nidx>
 377
 378 similarly for @Float#@.
 379
 380 There are two coercion functions for @Float#@/@Double#@:
 381
 382 <tscreen><verb>
 383 float2Double#   :: Float# -> Double#
 384 double2Float#   :: Double# -> Float#
 385 </verb></tscreen>
 386 <ncdx>float2Double#</ncdx>
 387 <ncdx>double2Float#</ncdx>
 388
 389 The primitive versions of @encodeDouble@/@decodeDouble@:
 390
 391 <tscreen><verb>
 392 encodeDouble#   :: Int# -> Int# -> ByteArray#   -- Integer mantissa
 393                 -> Int#                         -- Int exponent
 394                 -> Double#
 395
 396 decodeDouble#   :: Double# -> PrelNum.ReturnIntAndGMP
 397 </verb></tscreen>
 398 <ncdx>encodeDouble#</ncdx>
 399 <ncdx>decodeDouble#</ncdx>
 400
 401 (And the same for @Float#@s.)
 402
 403 <sect2>Operations on/for @Integers@ (interface to GMP)
 404 <label id="integer-operations">
 405 <p>
 406 <nidx>arbitrary precision integers</nidx>
 407 <nidx>Integer, operations on</nidx>
 408
 409 We implement @Integers@ (arbitrary-precision integers) using the GNU
 410 multiple-precision (GMP) package (version 2.0.2).
 411
 412 The data type for @Integer@ is either a small integer,
 413 represented by an @Int@, or a large integer represented
 414 using the pieces requird by GMP's @MP_INT@ in @gmp.h@
 415 (see @gmp.info@ in @ghc/includes/runtime/gmp@).  It comes out as:
 416
 417 <tscreen><verb>
 418 data Integer = S# Int#             -- small integers
 419              | J# Int# ByteArray#  -- large integers
 420 </verb></tscreen>
 421 <nidx>Integer type</nidx>
 422 The primitive ops to support large @Integers@ use the ``pieces'' of the
 423 representation, and are as follows:
 424
 425 <tscreen><verb>
 426 negateInteger#  :: Int# -> ByteArray# -> Integer
 427
 428 {plus,minus,times}Integer# :: Int# -> ByteArray#
 429                            -> Int# -> ByteArray#
 430                            -> Integer
 431
 432 cmpInteger# :: Int# -> ByteArray#
 433             -> Int# -> ByteArray#
 434             -> Int# -- -1 for <; 0 for ==; +1 for >
 435
 436 divModInteger#, quotRemInteger#
 437         :: Int# -> ByteArray#
 438         -> Int# -> ByteArray#
 439         -> PrelNum.Return2GMPs
 440
 441 integer2Int# :: 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@ (see library documentation) provides a more
 870 programmer-friendly interface to foreign objects.
 871
 872 <sect2>Synchronizing variables (M-vars)
 873 <p>
 874 <nidx>synchronising variables (M-vars)</nidx>
 875 <nidx>M-Vars</nidx>
 876
 877 Synchronising variables are the primitive type used to implement
 878 Concurrent Haskell's MVars (see the Concurrent Haskell paper for
 879 the operational behaviour of these operations).
 880
 881 <tscreen><verb>
 882 type MVar# s elt        -- primitive
 883
 884 newMVar#    :: State# s -> (# State# s, MVar# s elt #)
 885 takeMVar#   :: SynchVar# s elt -> State# s -> (# State# s, elt #)
 886 putMVar#    :: SynchVar# s elt -> State# s -> State# s
 887 </verb></tscreen>
 888 <ncdx>SynchVar#</ncdx>
 889 <ncdx>newSynchVar#</ncdx>
 890 <ncdx>takeMVar</ncdx>
 891 <ncdx>putMVar</ncdx>