ghc/docs/users_guide/libraries.sgml

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