ghc/docs/users_guide/libraries.lit

   1 \begin{onlystandalone}
   2 \documentstyle[a4wide,grasp]{article}
   3 \begin{rawlatex}
   4 \renewcommand{\textfraction}{0.1}
   5 \renewcommand{\floatpagefraction}{0.9}
   6 \renewcommand{\dblfloatpagefraction}{0.9}
   7
   8 \sloppy
   9 \renewcommand{\today}{March 1997}
  10 \end{rawlatex}
  11
  12 \begin{document}
  13 \title{The GHC Prelude and Libraries}
  14 \author{Simon L Peyton Jones \and Will Partain}
  15
  16 \maketitle
  17 \begin{rawlatex}
  18 \tableofcontents
  19 \end{rawlatex}
  20 \end{onlystandalone}
  21
  22 \section[ghc-prelude]{The GHC prelude and libraries}
  23
  24 This document describes GHC's prelude and libraries.  The basic story is that of
  25 the Haskell 1.4 Report and Libraries document (which we do not reproduce here),
  26 but this document describes in addition:
  27 \begin{itemize}
  28 \item   GHC's additional non-standard libraries and types, such as
  29         state transformers, packed strings, foreign objects, stable
  30         pointers, and so on.
  31
  32 \item   GHC's primitive types and operations.  The standard Haskell
  33         functions are implemented on top of these, and it is sometimes
  34         useful to use them directly.
  35
  36 \item   The organisation of these libraries into directories.
  37 \item   Short description of programmer interface to the non-standard,
  38         `built-in' libraries provided in addition to the standard
  39         prelude and libraries.
  40 \end{itemize}
  41
  42 In addition to the GHC prelude libraries, GHC comes with a number of
  43 system libraries, which are presented in \ref{syslibs}.
  44
  45 \subsection{Prelude library organisation}
  46
  47 {\em Probably only of interest to implementors..}
  48
  49 The prelude libraries are organised into the following three groups,
  50 each of which is kept in a separate sub-directory of GHC's source
  51 @lib/@ directory:
  52 \begin{description}
  53 \item[@lib/required/@]  These are the libraries {\em required} by the
  54 Haskell definition.  All are defined by the Haskell Report, or by the
  55 Haskell Libraries Report.
  56 They currently comprise:
  57 \begin{itemize}
  58 \item @Prelude@.
  59 \item @List@: more functions on lists.
  60 \item @Char@: more functions on characters.
  61 \item @Maybe@: more functions on @Maybe@ types.
  62 \item @Complex@: interface defining complex number type and functions over it.
  63 \item @Ratio@: functions on rational numbers.
  64 \item @Monad@: functions on monads.
  65 \item @Ix@: the @Ix@ class of indexing operations.
  66 \item @Array@: monolithic arrays.
  67 \item @IO@: additional input/output functions.
  68 \item @Directory@: basic functions for accessing the file system.
  69 \item @System@: basic operating-system interface functions.
  70 \item @Numeric@: operations for reading and showing number values.
  71 \end{itemize}
  72
  73 \item[@lib/glaExts@]  GHC extension libraries, currently comprising:
  74 \begin{itemize}
  75 \item @GlaExts@: collector interface to the various Glasgow
  76 extensions, primitive operations.
  77 \item @PackedString@: functions that manipulate strings packed efficiently, one character per byte.
  78 \item @ST@: the state transformer monad.
  79 \item @Foreign@: types and operations for GHC's foreign-language interface.
  80 \item @ByteArray@: operations over immutable chunks of (heap allocated) bytes.
  81 \item @MutableArray@: operations over mutable arrays.
  82 \item @MutVar@: operations over mutable variables.
  83 \end{itemize}
  84
  85 \item[@lib/concurrent@] GHC extension libraries to support Concurrent Haskell, currently comprising:
  86 \begin{itemize}
  87 \item @Concurrent@: main library.
  88 \item @Parallel@: stuff for multi-processor parallelism.
  89 \item @Channel@
  90 \item @ChannelVar@
  91 \item @Merge@
  92 \item @SampleVar@
  93 \item @Semaphore@
  94 \end{itemize}
  95
  96 \item[@lib/ghc@] These libraries are the pieces on which all the others are built.
  97 They aren't typically imported by Joe Programmer, but there's nothing to stop you
  98 doing so if you want.  In general, the modules prefixed by @Prel@ are pieces that go
  99 towards building @Prelude@.
 100
 101 \begin{itemize}
 102 \item @GHC@: this ``library'' brings into scope all the primitive types and operations, such as
 103 @Int#@, @+#@,  @encodeFloat#@, etc etc.  It is unique in that there is no Haskell
 104 source code for it.  Details in Section \ref{sect:ghc}.
 105
 106 \item @PrelBase@: defines the basic types and classes without which very few Haskell programs can work.
 107 The classes are: @Eq@, @Ord@, @Enum@, @Bounded@, @Num@, @Show@, @Eval@, @Monad@, @MonadZero@, @MonadPlus@.
 108 The types are: list, @Bool@, @Char@, @Ordering@, @String@, @Int@, @Integer@, @Maybe@, @Either@.
 109
 110 \item @PrelTup@: defines tuples and their instances.
 111 \item @PrelList@: defines most of the list operations required by @Prelude@.  (A few are in @PrelBase@,
 112 to avoid gratuitous mutual recursion between modules.)
 113
 114 \item @PrelNum@ defines: the numeric classes beyond @Num@, namely
 115 @Real@, @Integral@, @Fractional@, @Floating@, @RealFrac@, @RealFloat@;
 116 instances for appropriate classes for @Int@ and @Integer@; the types
 117 @Float@, @Double@, and @Ratio@ and their instances.
 118
 119 \item @PrelRead@: the @Read@ class and all its instances.  It's kept
 120 separate because many programs don't use @Read@ at all, so we don't
 121 even want to link in its code. (If the prelude libraries are built by
 122 splitting the object files, this is all a non-issue)
 123
 124 \item @ConcBase@: substrate stuff for Concurrent Haskell.
 125
 126 \item @IOBase@: substrate stuff for the main I/O libraries.
 127 \item @IOHandle@: large blob of code for doing I/O on handles.
 128 \item @PrelIO@: the remaining small pieces to produce the I/O stuff needed by @Prelude@.
 129
 130 \item @STBase@: substrate stuff for @ST@.
 131 \item @ArrBase@: substrate stuff for @Array@.
 132
 133 \item @GHCerr@: error reporting code, called from code that the compiler plants in compiled programs.
 134 \item @GHCmain@: the definition of @mainPrimIO@, which is what {\em really} gets
 135         called by the runtime system.  @mainPrimIO@ in turn calls @main@.
 136 \end{itemize}
 137 \end{description}
 138
 139 The @...Base@ modules generally export representation information that
 140 is hidden from the public interface.  For example the module @STBase@
 141 exports the type @ST@ including its representation, whereas the module
 142 @ST@ exports @ST@ abstractly.
 143
 144 None of these modules are involved in any mutual recursion, with the
 145 sole exception that many modules import @IOBase.error@.
 146
 147 \subsection{The module @GHC@: really primitive stuff}
 148 \label{sect:ghc}
 149
 150 This section defines all the types which are primitive in Glasgow
 151 Haskell, and the operations provided for them.
 152
 153 A primitive type is one which cannot be defined in Haskell, and which
 154 is therefore built into the language and compiler.  Primitive types
 155 are always unboxed; that is, a value of primitive type cannot be
 156 bottom.
 157
 158 Primitive values are often represented by a simple bit-pattern, such as @Int#@,
 159 @Float#@, @Double#@.  But this is not necessarily the case: a primitive value
 160 might be represented by a pointer to a heap-allocated object.  Examples include
 161 @Array#@, the type of primitive arrays.  You might think this odd: doesn't being
 162 heap-allocated mean that it has a box?  No, it does not.  A primitive array is
 163 heap-allocated because it is too big a value to fit in a register, and would be
 164 too expensive to copy around; in a sense, it is accidental that it is represented
 165 by a pointer.  If a pointer represents a primitive value, then it really does
 166 point to that value: no unevaluated thunks, no indirections...nothing can be at
 167 the other end of the pointer than the primitive value.
 168
 169 This section also describes a few non-primitive types, which are needed
 170 to express the result types of some primitive operations.
 171
 172 \subsubsection{Character and numeric types}
 173
 174 There are the following obvious primitive types:
 175 \begin{verbatim}
 176 type Char#
 177 type Int#       -- see also Word# and Addr#, later
 178 type Float#
 179 type Double#
 180 \end{verbatim}
 181 If you really want to know their exact equivalents in C, see
 182 @ghc/includes/StgTypes.lh@ in the GHC source tree.
 183
 184 Literals for these types may be written as follows:
 185 \begin{verbatim}
 186 1#              an Int#
 187 1.2#            a Float#
 188 1.34##          a Double#
 189 'a'#            a Char#; for weird characters, use '\o<octal>'#
 190 "a"#            an Addr# (a `char *')
 191 \end{verbatim}
 192
 193 \subsubsubsection{Comparison operations}
 194 \begin{verbatim}
 195 {gt,ge,eq,ne,lt,le}Char# :: Char# -> Char# -> Bool
 196     -- ditto for Int#, Word#, Float#, Double#, and Addr#
 197 \end{verbatim}
 198
 199 \subsubsubsection{Unboxed-character operations}
 200 \begin{verbatim}
 201 ord# :: Char# -> Int#
 202 chr# :: Int# -> Char#
 203 \end{verbatim}
 204
 205
 206 \subsubsubsection{Unboxed-@Int@ operations}
 207 \begin{verbatim}
 208 {plus,minus,times,quot,div,rem}Int# :: Int# -> Int# -> Int#
 209 negateInt# :: Int# -> Int#
 210 \end{verbatim}
 211
 212 {\bf Note:} No error/overflow checking!
 213
 214 \subsubsubsection{Unboxed-@Double@ and @Float@ operations}
 215 \begin{verbatim}
 216 {plus,minus,times,divide}Double# :: Double# -> Double# -> Double#
 217 negateDouble# :: Double# -> Double#
 218
 219 float2Int#      :: Double# -> Int#   -- just a cast, no checking!
 220 int2Double#     :: Int# -> Double#
 221
 222 expDouble#      :: Double# -> Double#
 223 logDouble#      :: Double# -> Double#
 224 sqrtDouble#     :: Double# -> Double#
 225 sinDouble#      :: Double# -> Double#
 226 cosDouble#      :: Double# -> Double#
 227 tanDouble#      :: Double# -> Double#
 228 asinDouble#     :: Double# -> Double#
 229 acosDouble#     :: Double# -> Double#
 230 atanDouble#     :: Double# -> Double#
 231 sinhDouble#     :: Double# -> Double#
 232 coshDouble#     :: Double# -> Double#
 233 tanhDouble#     :: Double# -> Double#
 234 powerDouble#    :: Double# -> Double# -> Double#
 235 \end{verbatim}
 236
 237 There's an exactly-matching set of unboxed-@Float@ ops; replace
 238 @Double#@ with @Float#@ in the list above.  There are two
 239 coercion functions for @Float#@/@Double#@:
 240 \begin{verbatim}
 241 float2Double#   :: Float# -> Double#
 242 double2Float#   :: Double# -> Float#
 243 \end{verbatim}
 244
 245 The primitive versions of @encodeDouble@/@decodeDouble@:
 246 \begin{verbatim}
 247 encodeDouble#   :: Int# -> Int# -> ByteArray#   -- Integer mantissa
 248                 -> Int#                         -- Int exponent
 249                 -> Double#
 250
 251 decodeDouble#   :: Double# -> PrelNum.ReturnIntAndGMP
 252 \end{verbatim}
 253
 254 (And the same for @Float#@s.)
 255
 256 \subsubsection{Operations on/for @Integers@ (interface to GMP)}
 257 \label{sect:horrid-Integer-pairing-types}
 258
 259 We implement @Integers@ (arbitrary-precision integers) using the GNU
 260 multiple-precision (GMP) package (version 1.3.2).
 261
 262 {\bf Note:} some of this might change when we upgrade to using GMP~2.x.
 263
 264 The data type for @Integer@ must mirror that for @MP_INT@ in @gmp.h@
 265 (see @gmp.info@ in \tr{ghc/includes/runtime/gmp}).  It comes out as:
 266 \begin{verbatim}
 267 data Integer = J# Int# Int# ByteArray#
 268 \end{verbatim}
 269
 270 So, @Integer@ is really just a ``pairing'' type for a particular
 271 collection of primitive types.
 272
 273 The operations in the GMP return other combinations of
 274 GMP-plus-something, so we need ``pairing'' types for those, too:
 275 \begin{verbatim}
 276 data Return2GMPs     = Return2GMPs Int# Int# ByteArray# Int# Int# ByteArray#
 277 data ReturnIntAndGMP = ReturnIntAndGMP Int# Int# Int# ByteArray#
 278
 279 -- ????? something to return a string of bytes (in the heap?)
 280 \end{verbatim}
 281
 282 The primitive ops to support @Integers@ use the ``pieces'' of the
 283 representation, and are as follows:
 284 \begin{verbatim}
 285 negateInteger#  :: Int# -> Int# -> ByteArray# -> Integer
 286
 287 {plus,minus,times}Integer# :: Int# -> Int# -> ByteArray#
 288                            -> Int# -> Int# -> ByteArray#
 289                            -> Integer
 290
 291 cmpInteger# :: Int# -> Int# -> ByteArray#
 292             -> Int# -> Int# -> ByteArray#
 293             -> Int# -- -1 for <; 0 for ==; +1 for >
 294
 295 divModInteger#, quotRemInteger#
 296         :: Int# -> Int# -> ByteArray#
 297         -> Int# -> Int# -> ByteArray#
 298         -> PrelNum.Return2GMPs
 299
 300 integer2Int# :: Int# -> Int# -> ByteArray# -> Int#
 301
 302 int2Integer#  :: Int#  -> Integer -- NB: no error-checking on these two!
 303 word2Integer# :: Word# -> Integer
 304
 305 addr2Integer# :: Addr# -> Integer
 306         -- the Addr# is taken to be a `char *' string
 307         -- to be converted into an Integer.
 308 \end{verbatim}
 309
 310
 311 \subsubsection{Words and addresses}
 312
 313 A @Word#@ is used for bit-twiddling operations.  It is the same size as
 314 an @Int#@, but has no sign nor any arithmetic operations.
 315 \begin{verbatim}
 316 type Word#      -- Same size/etc as Int# but *unsigned*
 317 type Addr#      -- A pointer from outside the "Haskell world" (from C, probably);
 318                 -- described under "arrays"
 319 \end{verbatim}
 320
 321 @Word#@s and @Addr#@s have the usual comparison operations.
 322 Other unboxed-@Word@ ops (bit-twiddling and coercions):
 323 \begin{verbatim}
 324 and#, or# :: Word# -> Word# -> Word#
 325
 326 not# :: Word# -> Word#
 327
 328 shiftL#, shiftRA#, shiftRL# :: Word# -> Int# -> Word#
 329         -- shift left, right arithmetic, right logical
 330
 331 iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
 332         -- same shift ops, but on Int#s
 333
 334 int2Word#       :: Int#  -> Word# -- just a cast, really
 335 word2Int#       :: Word# -> Int#
 336 \end{verbatim}
 337
 338
 339 Unboxed-@Addr@ ops (C casts, really):
 340 \begin{verbatim}
 341 int2Addr#       :: Int#  -> Addr#
 342 addr2Int#       :: Addr# -> Int#
 343 \end{verbatim}
 344
 345 Operations for indexing off of C pointers (@Addr#@s) to snatch values
 346 are listed under ``arrays''.
 347
 348 \subsubsection{Arrays}
 349
 350 The type @Array# elt@ is the type of primitive,
 351 unboxed arrays of values of type @elt@.
 352 \begin{verbatim}
 353 type Array# elt
 354 \end{verbatim}
 355
 356 @Array#@ is more primitive than a Haskell array --- indeed, the
 357 Haskell @Array@ interface is implemented using @Array#@ --- in that an
 358 @Array#@ is indexed only by @Int#@s, starting at zero.  It is also
 359 more primitive by virtue of being unboxed.  That doesn't mean that it
 360 isn't a heap-allocated object --- of course, it is.  Rather, being
 361 unboxed means that it is represented by a pointer to the array itself,
 362 and not to a thunk which will evaluate to the array (or to bottom).
 363 The components of an @Array#@ are themselves boxed.
 364
 365 The type @ByteArray#@ is similar to @Array#@, except that it contains
 366 just a string of (non-pointer) bytes.
 367 \begin{verbatim}
 368 type ByteArray#
 369 \end{verbatim}
 370
 371 Arrays of these types are useful when a Haskell program wishes to
 372 construct a value to pass to a C procedure. It is also possible to
 373 use them to build (say) arrays of unboxed characters for internal use
 374 in a Haskell program.  Given these uses, @ByteArray#@ is deliberately
 375 a bit vague about the type of its components.  Operations are provided
 376 to extract values of type @Char#@, @Int#@, @Float#@, @Double#@, and
 377 @Addr#@ from arbitrary offsets within a @ByteArray#@.  (For type
 378 @Foo#@, the $i$th offset gets you the $i$th @Foo#@, not the @Foo#@ at
 379 byte-position $i$.  Mumble.)  (If you want a @Word#@, grab an @Int#@,
 380 then coerce it.)
 381
 382 Lastly, we have static byte-arrays, of type @Addr#@ [mentioned
 383 previously].  (Remember the duality between arrays and pointers in C.)
 384 Arrays of this types are represented by a pointer to an array in the
 385 world outside Haskell, so this pointer is not followed by the garbage
 386 collector.  In other respects they are just like @ByteArray#@.  They
 387 are only needed in order to pass values from C to Haskell.
 388
 389 \subsubsubsection{Reading and writing.}
 390
 391 Primitive arrays are linear, and indexed starting at zero.
 392
 393 The size and indices of a @ByteArray#@, @Addr#@, and
 394 @MutableByteArray#@ are all in bytes.  It's up to the program to
 395 calculate the correct byte offset from the start of the array.  This
 396 allows a @ByteArray#@ to contain a mixture of values of different
 397 type, which is often needed when preparing data for and unpicking
 398 results from C.  (Umm... not true of indices... WDP 95/09)
 399
 400 {\em Should we provide some @sizeOfDouble#@ constants?}
 401
 402 Out-of-range errors on indexing should be caught by the code which
 403 uses the primitive operation; the primitive operations themselves do
 404 {\em not} check for out-of-range indexes. The intention is that the
 405 primitive ops compile to one machine instruction or thereabouts.
 406
 407 We use the terms ``reading'' and ``writing'' to refer to accessing
 408 {\em mutable} arrays (see Section~\ref{sect:mutable}), and
 409 ``indexing'' to refer to reading a value from an {\em immutable}
 410 array.
 411
 412 If you want to read/write a @Word#@, read an @Int#@ and coerce.
 413
 414 Immutable byte arrays are straightforward to index (all indices in bytes):
 415 \begin{verbatim}
 416 indexCharArray#   :: ByteArray# -> Int# -> Char#
 417 indexIntArray#    :: ByteArray# -> Int# -> Int#
 418 indexAddrArray#   :: ByteArray# -> Int# -> Addr#
 419 indexFloatArray#  :: ByteArray# -> Int# -> Float#
 420 indexDoubleArray# :: ByteArray# -> Int# -> Double#
 421
 422 indexCharOffAddr#   :: Addr# -> Int# -> Char#
 423 indexIntOffAddr#    :: Addr# -> Int# -> Int#
 424 indexFloatOffAddr#  :: Addr# -> Int# -> Float#
 425 indexDoubleOffAddr# :: Addr# -> Int# -> Double#
 426 indexAddrOffAddr#   :: Addr# -> Int# -> Addr#
 427  -- Get an Addr# from an Addr# offset
 428 \end{verbatim}
 429
 430 The last of these, @indexAddrOffAddr#@, extracts an @Addr#@ using an offset
 431 from another @Addr#@, thereby providing the ability to follow a chain of
 432 C pointers.
 433
 434 Something a bit more interesting goes on when indexing arrays of boxed
 435 objects, because the result is simply the boxed object. So presumably
 436 it should be entered --- we never usually return an unevaluated
 437 object!  This is a pain: primitive ops aren't supposed to do
 438 complicated things like enter objects.  The current solution is to
 439 return a lifted value, but I don't like it!
 440 \begin{verbatim}
 441 indexArray#       :: Array# elt -> Int# -> PrelBase.Lift elt  -- Yuk!
 442 \end{verbatim}
 443
 444
 445 \subsubsection{The state type}
 446
 447 The primitive type @State#@ represents the state of a state transformer.
 448 It is parameterised on the desired type of state, which serves to keep
 449 states from distinct threads distinct from one another.  But the {\em only}
 450 effect of this parameterisation is in the type system: all values of type
 451 @State#@ are represented in the same way.  Indeed, they are all
 452 represented by nothing at all!  The code generator ``knows'' to generate no
 453 code, and allocate no registers etc, for primitive states.
 454 \begin{verbatim}
 455 type State# s
 456 \end{verbatim}
 457
 458
 459 The type @GHC.RealWorld@ is truly opaque: there are no values defined
 460 of this type, and no operations over it.  It is ``primitive'' in that
 461 sense---but it is {\em not unboxed!} Its only role in life is to be the type
 462 which distinguishes the @PrimIO@ state transformer (see
 463 Section~\ref{sect:io-spec}).
 464 \begin{verbatim}
 465 data RealWorld
 466 \end{verbatim}
 467
 468 \subsubsubsection{States}
 469
 470 A single, primitive, value of type @State# RealWorld@ is provided.
 471 \begin{verbatim}
 472 realWorld# :: State# GHC.RealWorld
 473 \end{verbatim}
 474
 475 (Note: in the compiler, not a @PrimOp@; just a mucho magic
 476 @Id@. Exported from @GHC@, though).
 477
 478 \subsubsection{State pairing types}
 479 \label{sect:horrid-pairing-types}
 480
 481 This subsection defines some types which, while they aren't quite
 482 primitive because we can define them in Haskell, are very nearly so.
 483 They define constructors which pair a primitive state with a value of
 484 each primitive type.  They are required to express the result type of
 485 the primitive operations in the state monad.
 486 \begin{verbatim}
 487 data StateAndPtr#    s elt = StateAndPtr#    (State# s) elt
 488
 489 data StateAndChar#   s     = StateAndChar#   (State# s) Char#
 490 data StateAndInt#    s     = StateAndInt#    (State# s) Int#
 491 data StateAndWord#   s     = StateAndWord#   (State# s) Word#
 492 data StateAndFloat#  s     = StateAndFloat#  (State# s) Float#
 493 data StateAndDouble# s     = StateAndDouble# (State# s) Double#
 494 data StateAndAddr#   s     = StateAndAddr#   (State# s) Addr#
 495
 496 data StateAndStablePtr# s a = StateAndStablePtr#  (State# s) (StablePtr# a)
 497 data StateAndForeignObj# s  = StateAndForeignObj# (State# s) ForeignObj#
 498 data StateAndSynchVar#  s a = StateAndSynchVar#  (State# s) (SynchVar# a)
 499
 500 data StateAndArray#            s elt = StateAndArray#        (State# s) (Array# elt)
 501 data StateAndMutableArray#     s elt = StateAndMutableArray# (State# s) (MutableArray# s elt)
 502 data StateAndByteArray#        s = StateAndByteArray#        (State# s) ByteArray#
 503 data StateAndMutableByteArray# s = StateAndMutableByteArray# (State# s) (MutableByteArray# s)
 504 \end{verbatim}
 505
 506 Hideous.
 507
 508 \subsubsection{Mutable arrays}
 509 \label{sect:mutable}
 510
 511 Corresponding to @Array#@ and @ByteArray#@, we have the types of
 512 mutable versions of each.  In each case, the representation is a
 513 pointer to a suitable block of (mutable) heap-allocated storage.
 514 \begin{verbatim}
 515 type MutableArray# s elt
 516 type MutableByteArray# s
 517 \end{verbatim}
 518
 519 \subsubsubsection{Allocation.}
 520
 521 Mutable arrays can be allocated. Only pointer-arrays are initialised;
 522 arrays of non-pointers are filled in by ``user code'' rather than by
 523 the array-allocation primitive.  Reason: only the pointer case has to
 524 worry about GC striking with a partly-initialised array.
 525
 526 \begin{verbatim}
 527 newArray#       :: Int# -> elt -> State# s -> StateAndMutableArray# s elt
 528
 529 newCharArray#   :: Int# -> State# s -> StateAndMutableByteArray# s
 530 newIntArray#    :: Int# -> State# s -> StateAndMutableByteArray# s
 531 newAddrArray#   :: Int# -> State# s -> StateAndMutableByteArray# s
 532 newFloatArray#  :: Int# -> State# s -> StateAndMutableByteArray# s
 533 newDoubleArray# :: Int# -> State# s -> StateAndMutableByteArray# s
 534 \end{verbatim}
 535
 536 The size of a @ByteArray#@ is given in bytes.
 537
 538 \subsubsubsection{Reading and writing}
 539
 540 %OLD: Remember, offsets in a @MutableByteArray#@ are in bytes.
 541 \begin{verbatim}
 542 readArray#       :: MutableArray# s elt -> Int# -> State# s -> StateAndPtr#    s elt
 543 readCharArray#   :: MutableByteArray# s -> Int# -> State# s -> StateAndChar#   s
 544 readIntArray#    :: MutableByteArray# s -> Int# -> State# s -> StateAndInt#    s
 545 readAddrArray#   :: MutableByteArray# s -> Int# -> State# s -> StateAndAddr#   s
 546 readFloatArray#  :: MutableByteArray# s -> Int# -> State# s -> StateAndFloat#  s
 547 readDoubleArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndDouble# s
 548
 549 writeArray#       :: MutableArray# s elt -> Int# -> elt     -> State# s -> State# s
 550 writeCharArray#   :: MutableByteArray# s -> Int# -> Char#   -> State# s -> State# s
 551 writeIntArray#    :: MutableByteArray# s -> Int# -> Int#    -> State# s -> State# s
 552 writeAddrArray#   :: MutableByteArray# s -> Int# -> Addr#   -> State# s -> State# s
 553 writeFloatArray#  :: MutableByteArray# s -> Int# -> Float#  -> State# s -> State# s
 554 writeDoubleArray# :: MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
 555 \end{verbatim}
 556
 557
 558 \subsubsubsection{Equality.}
 559
 560 One can take ``equality'' of mutable arrays.  What is compared is the
 561 {\em name} or reference to the mutable array, not its contents.
 562 \begin{verbatim}
 563 sameMutableArray#     :: MutableArray# s elt -> MutableArray# s elt -> Bool
 564 sameMutableByteArray# :: MutableByteArray# s -> MutableByteArray# s -> Bool
 565 \end{verbatim}
 566
 567
 568 \subsubsubsection{Freezing mutable arrays}
 569
 570 Only unsafe-freeze has a primitive.  (Safe freeze is done directly in Haskell
 571 by copying the array and then using @unsafeFreeze@.)
 572 \begin{verbatim}
 573 unsafeFreezeArray#     :: MutableArray# s elt -> State# s -> StateAndArray#     s elt
 574 unsafeFreezeByteArray# :: MutableByteArray# s -> State# s -> StateAndByteArray# s
 575 \end{verbatim}
 576
 577
 578 \subsubsubsection{Stable pointers}
 579
 580 A stable pointer is a name for a Haskell object which can be passed to
 581 the external world.  It is ``stable'' in the sense that the name does
 582 not change when the Haskell garbage collector runs --- in contrast to
 583 the address of the object which may well change.
 584
 585 The stable pointer type is parameterised by the type of the thing
 586 which is named.
 587 \begin{verbatim}
 588 type StablePtr# a
 589 \end{verbatim}
 590
 591 A stable pointer is represented by an index into the (static)
 592 @StablePointerTable@.  The Haskell garbage collector treats the
 593 @StablePointerTable@ as a source of roots for GC.
 594
 595 The @makeStablePointer@ function converts a value into a stable
 596 pointer.  It is part of the @PrimIO@ monad, because we want to be sure
 597 we don't allocate one twice by accident, and then only free one of the
 598 copies.
 599 \begin{verbatim}
 600 makeStablePointer#  :: a -> State# RealWorld -> StateAndStablePtr# RealWorld a
 601 freeStablePointer#  :: StablePtr# a -> State# RealWorld -> State# RealWorld
 602 deRefStablePointer# :: StablePtr# a -> State# RealWorld -> StateAndPtr RealWorld a
 603 \end{verbatim}
 604
 605 There is also a C procedure @FreeStablePtr@ which frees a stable pointer.
 606
 607 %{\em Andy's comment.} {\bf Errors:} The following is not strictly true: the current
 608 %implementation is not as polymorphic as claimed.  The reason for this
 609 %is that the C programmer will have to use a different entry-routine
 610 %for each type of stable pointer.  At present, we only supply a very
 611 %limited number (3) of these routines.  It might be possible to
 612 %increase the range of these routines by providing general purpose
 613 %entry points to apply stable pointers to (stable pointers to)
 614 %arguments and to enter (stable pointers to) boxed primitive values.
 615 %{\em End of Andy's comment.}
 616
 617 %
 618 % Rewritten and updated for MallocPtr++ -- 4/96 SOF
 619 %
 620 \subsubsubsection{Foreign objects}
 621
 622 A @ForeignObj@ is a reference to an object outside the Haskell world
 623 (i.e., from the C world, or a reference to an object on another
 624 machine completely.), where the Haskell world has been told ``Let me
 625 know when you're finished with this ...''.
 626
 627 %OLD:The @ForeignObj@ type is just a special @Addr#@ ({\em not} parameterised).
 628 \begin{verbatim}
 629 type ForeignObj#
 630 \end{verbatim}
 631
 632 A typical use of @ForeignObj#@ is in constructing Haskell bindings
 633 to external libraries. A good example is that of writing a binding to
 634 an image-processing library (which was actually the main motivation
 635 for implementing @ForeignObj#@'s precursor, @MallocPtr#@). The
 636 images manipulated are not stored in the Haskell heap, either because
 637 the library insist on allocating them internally or we (sensibly)
 638 decide to spare the GC from having to heave heavy images around.
 639
 640 \begin{verbatim}
 641 data Image = Image ForeignObj#
 642
 643 instance CCallable Image
 644 \end{verbatim}
 645
 646 The @ForeignObj#@ type is then used to refer to the externally
 647 allocated image, and to acheive some type safety, the Haskell binding
 648 defines the @Image@ data type. So, a value of type @ForeignObj#@ is
 649 used to ``box'' up an external reference into a Haskell heap object
 650 that we can then indirectly reference:
 651
 652 \begin{verbatim}
 653 createImage :: (Int,Int) -> PrimIO Image
 654 \end{verbatim}
 655
 656
 657 So far, this looks just like an @Addr#@ type, but @ForeignObj#@
 658 offers a bit more, namely that we can specify a {\em finalisation
 659 routine} to invoke when the @ForeignObj#@ is discarded by the
 660 GC. The garbage collector invokes the finalisation routine associated
 661 with the @ForeignObj#@, saying `` Thanks, I'm through with this
 662 now..'' For the image-processing library, the finalisation routine could for
 663 the images free up memory allocated for them. The finalisation routine has
 664 currently to be written in C (the finalisation routine can in turn call on
 665 @FreeStablePtr@ to deallocate a stable pointer).
 666
 667 Associating a finalisation routine with an external object is done by
 668 @makeForeignObj#@:
 669
 670 \begin{verbatim}
 671 makeForeignObj# :: Addr# -- foreign reference
 672                 -> Addr# -- pointer to finalisation routine
 673                 -> StateAndForeignObj# RealWorld ForeignObj#
 674 \end{verbatim}
 675
 676 {\bf Note:} the foreign object value and its finaliser are contained
 677 in the primitive value @ForeignObj#@, so there's no danger of an
 678 aggressive optimiser somehow separating the two. (with the result
 679 that the foreign reference would not be freed).
 680
 681 (Implementation: a linked list of all @ForeignObj#@s is maintained to allow the
 682  garbage collector to detect when a @ForeignObj#@ becomes garbage.)
 683
 684 Like @Array@, @ForeignObj#@s are represented by heap objects.
 685
 686 Upon controlled termination of the Haskell program, all @ForeignObjs@
 687 are freed, invoking their respective finalisers before terminating.
 688
 689 %\bf{ToDo:} Decide whether @FreeCHeapPointer@ is allowed to call on a
 690 %stable pointer. (I sincerely hope not since we will still be in the
 691 %GC at this point.)
 692
 693 \subsubsubsection{Synchronizing variables (M-vars)}
 694
 695 Synchronising variables are the primitive type used to implement
 696 Concurrent Haskell's MVars (see the Concurrent Haskell paper for
 697 the operational behaviour of these operations).
 698
 699 \begin{verbatim}
 700 type SynchVar# s elt    -- primitive
 701
 702 newSynchVar#:: State# s -> StateAndSynchVar# s elt
 703 takeMVar#   :: SynchVar# s elt -> State# s -> StateAndPtr# s elt
 704 putMVar#    :: SynchVar# s elt -> State# s -> State# s
 705 \end{verbatim}
 706
 707 %\subsubsubsection{Controlling the garbage collector}
 708
 709 %The C function {\tt PerformGC\/}, allows the C world to force Haskell
 710 %to do a garbage collection. It can only be called while Haskell is
 711 %performing a C Call.
 712
 713 %Note that this function can be used to define a Haskell IO operation
 714 %with the same effect:
 715 %\begin{verbatim}
 716 %>      performGCIO :: PrimIO ()
 717 %>      performGCIO = _ccall_gc_ StgPerformGarbageCollection
 718 %\end{verbatim}
 719
 720 %\bf{ToDo:} Is there any need for abnormal/normal termination to force
 721 %a GC too?  Is there any need for a function that provides finer
 722 %control over GC: argument = amount of space required; result = amount
 723 %of space recovered.
 724 =======
 725 The C function {\tt PerformGC\/}, allows the C world to force Haskell
 726 to do a garbage collection. It can only be called while Haskell is
 727 performing a C Call.
 728
 729 Note that this function can be used to define a Haskell IO operation
 730 with the same effect:
 731 \begin{verbatim}
 732 >       performGCIO :: PrimIO ()
 733 >       performGCIO = _ccall_gc_ PerformGC
 734 \end{verbatim}
 735
 736 {\bf ToDo:} Is there any need for abnormal/normal termination to force
 737 a GC too?  Is there any need for a function that provides finer
 738 control over GC: argument = amount of space required; result = amount
 739 of space recovered.
 740
 741 \subsection{@spark#@ primitive operation (for parallel execution)}
 742
 743 {\em ToDo: say something}  It's used in the unfolding for @par@.
 744
 745 \subsection{The @errorIO#@ primitive operation}
 746
 747 The @errorIO#@ primitive takes an argument much like @PrimIO@.  It
 748 aborts execution of the current program, and continues instead by
 749 performing the given @PrimIO@-like value on the current state of the
 750 world.
 751 \begin{verbatim}
 752 errorIO# :: (State RealWorld -> ((), State RealWorld)) -> a
 753 \end{verbatim}
 754
 755
 756 \subsection{C Calls}
 757
 758 {\bf ToDo:} current implementation has state variable as second
 759 argument not last argument.
 760
 761 The @ccall#@ primitive can't be given an ordinary type, because it has
 762 a variable number of arguments.  The nearest we can get is:
 763 \begin{verbatim}
 764 ccall# :: CRoutine -> a1# -> ... -> an# -> State# RealWorld -> StateAndR# RealWorld
 765 \end{verbatim}
 766
 767 where the type variables @a1#@\ldots@an#@ and @r#@ can be instantiated by any
 768 primitive type, and @StateAndR#@ is the appropriate pairing type from
 769 Section~\ref{sect:horrid-pairing-types}.  The @CRoutine@
 770 isn't a proper Haskell type at all; it just reminds us that @ccall#@ needs to
 771 know what C routine to call.
 772
 773 This notation is really short for a massive family of @ccall#@ primitives, one
 774 for each combination of types.  (Of course, the compiler simply remembers the
 775 types involved, and generates appropriate code when it finally spits out the C.)
 776
 777 Unlike all the other primitive operators, @ccall#@ is not bound to an in-scope
 778 identifier.  The only way it is possible to generate a @ccall#@ is via the
 779 @_ccall_@ construct.
 780
 781 All this applies equally to @casm#@:
 782 \begin{verbatim}
 783 casm#  :: CAsmString -> a1# -> ... -> an# -> State# RealWorld -> StateAndR# RealWorld
 784 \end{verbatim}
 785
 786 %------------------------------------------------------------
 787 \subsection{Library stuff built with the Really Primitive Stuff}
 788
 789 \subsubsection{The state transformer monad}
 790
 791 \subsubsubsection{Types}
 792
 793 A state transformer is a function from a state to a pair of a result
 794 and a new state.
 795 \begin{verbatim}
 796 newtype ST s a = ST (State s -> (a, State s))
 797 \end{verbatim}
 798
 799 The @ST@ type is {\em abstract}, so that the programmer cannot see its
 800 representation.  If he could, he could write bad things like:
 801 \begin{verbatim}
 802 bad :: ST s a
 803 bad = ST $ \ s -> ...(f s)...(g s)...
 804 \end{verbatim}
 805
 806 Here, @s@ is duplicated, which would be bad news.
 807
 808 A state is represented by a primitive state value, of type @State# s@,
 809 wrapped up in a @State@ constructor.  The reason for boxing it in this
 810 way is so that we can be strict or lazy in the state.  (Remember, all
 811 primitive types are unboxed, and hence can't be bottom; but types built
 812 with @data@ are all boxed.)
 813 \begin{verbatim}
 814 data State s = S# (State# s)
 815 \end{verbatim}
 816
 817 \subsubsubsection{The state transformer combinators}
 818
 819 Now for the combinators, all of which live inside the @ST@
 820 abstraction.  Notice that @returnST@ and @thenST@ are now strict
 821 in the state. @ST@ is an instance of the @Monad@ type class.
 822 \begin{verbatim}
 823 returnST :: a -> ST s a
 824 returnST a = ST (\ s@(S# _) -> (a, s)) -- strict in state.
 825
 826 thenST :: ST s a -> (a -> ST s b) -> ST s b
 827 thenST m k =
 828   = ST $ \ s ->
 829     case (m s) of {(r, new_s) ->
 830     case (k r) of { ST k2 ->
 831     (k2 new_s) }}
 832
 833 instance Monad ST where
 834   return = returnST
 835   (>>=)  = thenST
 836
 837 fixST :: (a -> ST s a) -> ST s a
 838 fixST k s = ST $ \ s ->
 839             let (ST k_r)  = k r
 840                 ans       = k_r s
 841                 (r,new_s) = ans
 842             in
 843             ans
 844
 845 unsafeInterleaveST :: ST s a -> ST s a
 846 unsafeInterleaveST (ST m) = ST $ \ s ->
 847     let
 848         (r, new_s) = m s
 849     in
 850     (r, s)
 851 \end{verbatim}
 852
 853 The interesting one is, of course, @runST@.  We can't infer its type!
 854 (It has a funny name because it must be wired into the compiler.)
 855 \begin{verbatim}
 856 -- runST :: forall a. (forall s. ST s a) -> a
 857 runST m = case m (S# realWorld#) of
 858            (r,_) -> r
 859 \end{verbatim}
 860
 861
 862 \subsubsubsection{Other useful combinators}
 863
 864 There are various other standard combinators, all defined in terms the
 865 fundamental combinators above. The @seqST@ combinator is like
 866 @thenST@, except that it discards the result of the first state
 867 transformer:
 868 \begin{verbatim}
 869 seqST :: ST s a -> ST s b -> ST s b
 870 seqST m1 m2 = m1 `thenST` (\_ -> m2)
 871 \end{verbatim}
 872
 873 We also have {\em lazy} (... in the state...) variants of the
 874 then/return combinators (same types as their pals):
 875 \begin{verbatim}
 876 returnLazyST a = ST (\ s -> (a, s))
 877
 878 thenLazyST m k
 879  = ST $ \ s ->
 880    let (r, new_s) = m s
 881    in
 882    k r new_s
 883
 884 seqLazyST m k
 885  = ST $ \ s ->
 886    let (_, new_s) = m s
 887    in
 888    k new_s
 889 \end{verbatim}
 890
 891 The combinator @listST@ is provided for backwards compatibility, its
 892 behavior is captured in Haskell 1.3 (and later) by @Monad.accumulate@:
 893 \begin{verbatim}
 894 listST :: [ST s a] -> ST s [a]
 895 listST ls = accumulate ls
 896 \end{verbatim}
 897
 898 Another function provided for backwards compatibility is @mapST@, it
 899 is just an instance of the more general monad combinator @Monad.mapM@:
 900 \begin{verbatim}
 901 mapST :: (a -> ST s b) -> [a] -> ST s [b]
 902 mapST f ms = mapM f ms
 903 \end{verbatim}
 904
 905 The @mapAndUnzipST@ combinator is similar to @mapST@, except that here the
 906 function returns a pair:
 907 \begin{verbatim}
 908 mapAndUnzipST :: (a -> ST s (b,c)) -> [a] -> ST s ([b],[c])
 909 mapAndUnzipST f ls = mapAndUnzipM f ls
 910 \end{verbatim}
 911
 912
 913 {\bf Note:} all the derived operators over @ST@ are implemented using
 914 the {\em strict} @ST@ instance of @Monad@.
 915
 916 \subsubsection{The @PrimIO@ monad}
 917 \label{sect:io-spec}
 918
 919 The @PrimIO@ type is defined in as a state transformer which manipulates the
 920 @RealWorld@.
 921 \begin{verbatim}
 922 type PrimIO a = ST RealWorld a      -- Transparent
 923 \end{verbatim}
 924
 925 The @PrimIO@ type is an ordinary type synonym, transparent to the programmer.
 926
 927 The type @RealWorld@ and value @realWorld#@ do not need to be hidden (although
 928 there is no particular point in exposing them).  Even having a value of type
 929 @realWorld#@ does not compromise safety, since the type @ST@ is hidden.
 930
 931 It is type-correct to use @returnST@ in an @PrimIO@ context, they're
 932 in effect the same (ditto for the bind combinator):
 933
 934 \begin{verbatim}
 935 returnPrimIO :: a -> PrimIO a
 936 returnPrimIO v = returnST v
 937
 938 thenPrimIO  :: PrimIO a -> (a -> PrimIO b) -> PrimIO b
 939 thenPrimIO m k = thenST m k
 940
 941 seqPrimIO   :: PrimIO a -> PrimIO b -> PrimIO b
 942 seqPrimIO m k = seqST m k
 943 \end{verbatim}
 944
 945 Why is it safe for @returnPrimIO@ to be strict in the state?  Because
 946 every context in which an I/O state transformer is used will certainly
 947 evaluate the resulting state; it is the state of the real world!
 948
 949 @fixPrimIO@ has to be lazy, though!
 950 \begin{verbatim}
 951 fixPrimIO  = fixST
 952 \end{verbatim}
 953
 954 \subsubsubsection{@PrimIO@ combinators}
 955
 956
 957
 958 \begin{verbatim}
 959 unsafePerformPrimIO     :: PrimIO a -> a
 960 unsafeInterleavePrimIO  :: PrimIO a -> PrimIO a
 961
 962 unsafePerformPrimIO     = runST
 963 unsafeInterleavePrimIO  = unsafeInterleaveST
 964
 965 listPrimIO        :: [PrimIO a] -> PrimIO [a]
 966 mapPrimIO         :: (a -> PrimIO b) -> [a] -> PrimIO [b]
 967 mapAndUnzipPrimIO :: (a -> PrimIO (b,c)) -> [a] -> PrimIO ([b],[c])
 968 \end{verbatim}
 969
 970 The function @unsafePerformPrimIO@ is as the name suggests, {\em
 971 unsafe}, placing a burden of proof on the programmer to ensure that
 972 performing the I/O action does not break referential transparency.
 973
 974 \subsubsection{Arrays}
 975
 976 \subsubsubsection{Types}
 977
 978 \begin{verbatim}
 979 data Array      ix elt = Array     (ix,ix) (Array# elt)
 980 data ByteArray ix      = ByteArray (ix,ix) ByteArray#
 981
 982 data MutableArray     s ix elt = MutableArray     (ix,ix) (MutableArray# s elt)
 983 data MutableByteArray s ix     = MutableByteArray (ix,ix) (MutableByteArray# s)
 984 \end{verbatim}
 985
 986
 987 \subsubsubsection{Operations on immutable arrays}
 988
 989 Ordinary array indexing is straightforward.
 990 \begin{verbatim}
 991 (!) :: Ix ix => Array ix elt -> ix -> elt
 992 \end{verbatim}
 993
 994 QUESTIONs: should @ByteArray@s be indexed by Ints or ix?  With byte offsets
 995 or sized ones? (sized ones [WDP])
 996 \begin{verbatim}
 997 indexCharArray   :: Ix ix => ByteArray ix -> ix -> Char
 998 indexIntArray    :: Ix ix => ByteArray ix -> ix -> Int
 999 indexAddrArray   :: Ix ix => ByteArray ix -> ix -> Addr
1000 indexFloatArray  :: Ix ix => ByteArray ix -> ix -> Float
1001 indexDoubleArray :: Ix ix => ByteArray ix -> ix -> Double
1002 \end{verbatim}
1003
1004 @Addr@s are indexed straightforwardly by @Int@s.  Unlike the primitive
1005 operations, though, the offsets assume that the array consists entirely of the
1006 type of value being indexed, and so there's an implicit multiplication by
1007 the size of that value.  To access @Addr@s with mixed values requires
1008 you to do a DIY job using the primitives.
1009 \begin{verbatim}
1010 indexAddrChar :: Addr -> Int -> Char
1011 ...etc...
1012 indexStaticCharArray   :: Addr -> Int -> Char
1013 indexStaticIntArray    :: Addr -> Int -> Int
1014 indexStaticFloatArray  :: Addr -> Int -> Float
1015 indexStaticDoubleArray :: Addr -> Int -> Double
1016 indexStaticArray       :: Addr -> Int -> Addr
1017 \end{verbatim}
1018
1019
1020 \subsubsubsection{Operations on mutable arrays}
1021 \begin{verbatim}
1022 newArray     :: Ix ix => (ix,ix) -> elt -> ST s (MutableArray s ix elt)
1023 newCharArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1024 ...
1025 \end{verbatim}
1026
1027
1028 \begin{verbatim}
1029 readArray   :: Ix ix => MutableArray s ix elt -> ix -> ST s elt
1030 readCharArray   :: Ix ix => MutableByteArray s ix -> ix -> ST s Char
1031 ...
1032 \end{verbatim}
1033
1034 \begin{verbatim}
1035 writeArray  :: Ix ix => MutableArray s ix elt -> ix -> elt -> ST s ()
1036 writeCharArray  :: Ix ix => MutableByteArray s ix -> ix -> Char -> ST s ()
1037 ...
1038 \end{verbatim}
1039
1040
1041 \begin{verbatim}
1042 freezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
1043 freezeCharArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1044 ...
1045 \end{verbatim}
1046
1047
1048 We have no need on one-function-per-type for unsafe freezing:
1049 \begin{verbatim}
1050 unsafeFreezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
1051 unsafeFreezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1052 \end{verbatim}
1053
1054
1055 Sometimes we want to snaffle the bounds of one of these beasts:
1056 \begin{verbatim}
1057 boundsOfArray     :: Ix ix => MutableArray s ix elt -> (ix, ix)
1058 boundsOfByteArray :: Ix ix => MutableByteArray s ix -> (ix, ix)
1059 \end{verbatim}
1060
1061
1062 Lastly, ``equality'':
1063 \begin{verbatim}
1064 sameMutableArray     :: MutableArray s ix elt -> MutableArray s ix elt -> Bool
1065 sameMutableByteArray :: MutableByteArray s ix -> MutableByteArray s ix -> Bool
1066 \end{verbatim}
1067
1068
1069 \subsubsection{Mutable Variables}
1070
1071 \subsubsubsection{Types}
1072
1073 Mutable variables are (for now anyway) implemented as arrays.  The
1074 @MutableVar@ type is opaque, so we can change the implementation later
1075 if we want.
1076
1077 \begin{verbatim}
1078 type MutableVar s a = MutableArray s Int a
1079 \end{verbatim}
1080
1081
1082 \subsubsubsection{Operations}
1083 \begin{verbatim}
1084 newVar   :: a -> ST s (MutableVar s a)
1085 readVar  :: MutableVar s a -> ST s a
1086 writeVar :: MutableVar s a -> a -> ST s ()
1087 sameVar  :: MutableVar s a -> MutableVar s a -> Bool
1088 \end{verbatim}
1089
1090
1091 \subsubsection{Stable pointers}
1092
1093 Nothing exciting here, just simple boxing up.
1094 \begin{verbatim}
1095 data StablePtr a = StablePtr (StablePtr# a)
1096
1097 makeStablePointer :: a -> StablePtr a
1098 freeStablePointer :: StablePtr a -> PrimIO ()
1099 \end{verbatim}
1100
1101 \subsubsection{Foreign objects}
1102
1103 Again, just boxing up.
1104 \begin{verbatim}
1105 data ForeignObj = ForeignObj ForeignObj#
1106
1107 makeForeignObj :: Addr   -- object to be boxed up as a ForeignObj
1108                -> Addr   -- finaliser
1109                -> PrimIO ForeignObj
1110 \end{verbatim}
1111
1112 \subsubsection{C calls}
1113
1114 Everything in this section goes for @_casm_@ too.
1115
1116 {\bf ToDo:} {\em mention @_ccall_gc_@ and @_casm_gc_@...}
1117
1118 The @_ccall_@ construct has the following form:
1119 $$@_ccall_@~croutine~a_1~\ldots~a_n$$
1120 This whole construct has type @PrimIO@~$res$.
1121 The rules are these:
1122 \begin{itemize}
1123 \item
1124 The first ``argument'', $croutine$, must be the literal name of a C procedure.
1125 It cannot be a Haskell expression which evaluates to a string, etc; it must be
1126 simply the name of the procedure.
1127 \item
1128 The arguments $a_1, \ldots,a_n$ must be of {\em C-callable} type.
1129 \item
1130 The whole construct has type @PrimIO@~$ty$, where $ty$ is a {\em C-returnable} type.
1131 \end{itemize}
1132 A {\em boxed-primitive} type is both C-callable and C-returnable.
1133 A boxed primitive type is anything declared by:
1134 \begin{verbatim}
1135 data T = C# t
1136 \end{verbatim}
1137
1138 where @t@ is a primitive type.  Note that
1139 programmer-defined boxed-primitive types are perfectly OK:
1140 \begin{verbatim}
1141 data Widget = W# Int#
1142 data Screen = S# CHeapPtr#
1143 \end{verbatim}
1144
1145
1146 There are other types that can be passed to C (C-callable).  This
1147 table summarises (including the standard boxed-primitive types):
1148 \begin{verbatim}
1149 Boxed             Type of transferd   Corresp.     Which is
1150 Type              Prim. component     C type       *probably*...
1151 ------            ---------------     ------       -------------
1152 Char              Char#               StgChar       unsigned char
1153 Int               Int#                StgInt        long int
1154 Word              Word#               StgWord       unsigned long int
1155 Addr              Addr#               StgAddr       char *
1156 Float             Float#              StgFloat      float
1157 Double            Double#             StgDouble     double
1158
1159 Array             Array#              StgArray      StgPtr
1160 ByteArray         ByteArray#          StgByteArray  StgPtr
1161 MutableArray      MutableArray#       StgArray      StgPtr
1162 MutableByteArray  MutableByteArray#   StgByteArray  StgPtr
1163
1164 State             State#              nothing!
1165
1166 StablePtr         StablePtr#          StgStablePtr  StgPtr
1167 ForeignObj        ForeignObj#         StgForeignObj StgPtr
1168 \end{verbatim}
1169
1170
1171 All of the above are {\em C-returnable} except:
1172 \begin{verbatim}
1173   Array, ByteArray, MutableArray, MutableByteArray, ForeignObj
1174 \end{verbatim}
1175
1176 {\bf ToDo:} I'm pretty wary of @Array@ and @MutableArray@ being in
1177 this list, and not too happy about @State@ [WDP].
1178
1179 {\bf ToDo:} Can code generator pass all the primitive types?  Should this be
1180 extended to include {\tt Bool\/} (or any enumeration type?)
1181
1182 The type checker must be able to figure out just which of the C-callable/returnable
1183 types is being used.  If it can't, you have to add type signatures. For example,
1184 \begin{verbatim}
1185 f x = _ccall_ foo x
1186 \end{verbatim}
1187
1188 is not good enough, because the compiler can't work out what type @x@ is, nor
1189 what type the @_ccall_@ returns.  You have to write, say:
1190 \begin{verbatim}
1191 f :: Int -> PrimIO Float
1192 f x = _ccall_ foo x
1193 \end{verbatim}
1194
1195
1196 \subsubsubsection{Implementation}
1197
1198 The desugarer unwraps the @_ccall_@ construct by inserting the
1199 necessary evaluations etc to unbox the arguments.  For example, the
1200 body of the definition of @f@ above would become:
1201 \begin{verbatim}
1202         (\ s -> case x of { I# x# ->
1203                 case s of { S# s# ->
1204                 case ccall# [Int#,Float#] x# s# of { StateAndFloat# f# new_s# ->
1205                 (F# f#, S# new_s#)
1206                 }}})
1207 \end{verbatim}
1208
1209 Notice that the state, too, is unboxed.
1210
1211 %The code generator must deal specially with primitive objects which
1212 %are stored on the heap.
1213 %
1214 %\begin{verbatim}
1215 %... details omitted ...
1216 %\end{verbatim}
1217
1218 %
1219 %More importantly, it must construct a C Heap Pointer heap-object after
1220 %a @_ccall_@ which returns a @MallocPtr#@.
1221 %
1222
1223 %--------------------------------------------------------
1224 \subsection{Non-primitive stuff that must be wired into GHC}
1225
1226 \begin{verbatim}
1227 data Char    = C# Char#
1228 data Int     = I# Int#
1229 data Word    = W# Word#
1230 data Addr    = A# Addr#
1231
1232 data Float   = F# Float#
1233 data Double  = D# Double#
1234 data Integer = J# Int# Int# ByteArray#
1235
1236 -- and the other boxed-primitive types:
1237     Array, ByteArray, MutableArray, MutableByteArray,
1238     StablePtr, ForeignObj
1239
1240 data Bool     = False | True
1241 data Ordering = LT | EQ | GT  -- used in derived comparisons
1242
1243 data List a = [] | a : (List a)
1244 -- tuples...
1245
1246 data Lift a = Lift a    -- used Yukkily as described elsewhere
1247
1248 type String  = [Char]    -- convenience, only
1249 \end{verbatim}
1250
1251
1252 %------------------------------------------------------------
1253 \subsection{Programmer interface(s)}
1254
1255 \subsubsection{The bog-standard interface}
1256
1257 If you rely on the implicit @import Prelude@ that GHC normally does
1258 for you, and if you don't use any weird flags (notably
1259 @-fglasgow-exts@), and if you don't import the Glasgow extensions
1260 interface, @GlaExts@, then GHC should work {\em exactly} as the
1261 Haskell report says, and the full user namespaces should be available
1262 to you.
1263
1264 \subsubsubsection{If you mess about with @import Prelude@...}
1265
1266 Innocent hiding, e.g.,
1267 \begin{verbatim}
1268 import Prelude hiding ( fromIntegral )
1269 \end{verbatim}
1270
1271 should work just fine.
1272
1273 There are some things you can do that will make GHC crash, e.g.,
1274 hiding a standard class:
1275 \begin{verbatim}
1276 import Prelude hiding ( Eq(..) )
1277 \end{verbatim}
1278
1279 Don't do that.
1280
1281 \subsubsection{Turning on Glasgow extensions with @-fglasgow-exts@}
1282
1283 % Updated to tell the 2.02+ story  -- SOF
1284
1285 If you turn on @-fglasgow-exts@, the compiler will recognise and parse
1286 unboxed values properly. To get at the primitive operations described
1287 herein, import the interface @GlaExts@.
1288
1289 % 1.3+ module system makes this a non-issue.
1290 %%It is possible that some name conflicts between your code and the
1291 %%wired-in things might spring to life (though we doubt it...).
1292 %%Change your names :-)
1293
1294 %************************************************************************
1295 %*                                                                      *
1296 \subsubsection{The @GlaExts@ interface}
1297 \index{GlaExts interface (GHC extensions)}
1298 %*                                                                      *
1299 %************************************************************************
1300
1301 The @GlaExts@ interface is the programmer gateway to most of the
1302 programmer extensions GHC implement. Currently on tap:
1303
1304 \begin{verbatim}
1305   -- PrimIO monad (state transformer, no exceptions).
1306 type PrimIO a = ST RealWorld a
1307   -- instances of: Monad
1308 data RealWorld   -- abstract State value
1309
1310 thenPrimIO       :: PrimIO a -> (a -> PrimIO b) -> PrimIO b
1311 returnPrimIO     :: a -> PrimIO a
1312 seqPrimIO        :: PrimIO a -> PrimIO b -> PrimIO b
1313
1314 fixPrimIO        :: (a -> PrimIO a) -> PrimIO a
1315 unsafePerformPrimIO    :: PrimIO a -> a
1316 unsafeInterleavePrimIO :: PrimIO a -> PrimIO a
1317
1318 -- backwards compatibility
1319 listPrimIO        :: [PrimIO a] -> PrimIO [a]
1320 mapPrimIO         :: (a -> PrimIO b) -> [a] -> PrimIO [b]
1321 mapAndUnzipPrimIO :: (a -> PrimIO (b,c)) -> [a] -> PrimIO ([b],[c])
1322
1323 -- Combining ST and PrimIO monads with IO
1324         stToIO,       -- :: ST RealWorld a -> IO a
1325         primIOToIO,   -- :: PrimIO a       -> IO a
1326         ioToST,       -- :: IO a -> ST RealWorld a
1327         ioToPrimIO,   -- :: IO a -> PrimIO       a
1328         thenIO_Prim,  -- :: PrimIO a -> (a -> IO b) -> IO b
1329         seqIO_Prim,   -- :: PrimIO a -> IO b -> IO b
1330
1331 -- the representation of some basic types:
1332 data Char    = C# Char#
1333 data Int     = I# Int#
1334 data Addr    = A# Addr#
1335 data Word    = W# Word#
1336 data Float   = F# Float#
1337 data Double  = D# Double#
1338 data Integer = J# Int# Int# ByteArray#
1339
1340 -- misc
1341 trace :: String -> a -> a
1342
1343 -- re-exported interfaces:
1344 module ByteArray
1345 module MutableArray
1346 module GHC  -- all primops and primitive types.
1347 \end{verbatim}
1348
1349
1350 %************************************************************************
1351 %*                                                                      *
1352 \subsubsection{The @MutVar@ interface}
1353 \index{MutVar interface (GHC extensions)}
1354 %*                                                                      *
1355 %************************************************************************
1356
1357 @MutVar@ defines an interface to mutable variables, defining type and
1358 IO operations:
1359
1360 \begin{verbatim}
1361 data  MutVar   -- abstract
1362
1363 newVar       :: a -> IO (MutVar a)
1364 readVar      :: MutVar a -> IO a
1365 writeVar     :: MutVar a -> a -> IO ()
1366 sameVar      :: MutVar a -> MutVar a -> Bool
1367 \end{verbatim}
1368
1369
1370 %************************************************************************
1371 %*                                                                      *
1372 \subsubsection{The @MutableArray@ interface}
1373 \index{MutableArray interface (GHC extensions)}
1374 %*                                                                      *
1375 %************************************************************************
1376
1377 The @MutableArray@ interface defines a general set of operations over
1378 mutable arrays (@MutableArray@) and mutable chunks of memory
1379 (@MutableByteArray@):
1380
1381 \begin{verbatim}
1382 data MutableArray s ix elt -- abstract
1383 data MutableByteArray s ix -- abstract
1384                            -- instance of : CCallable
1385 -- Creators:
1386 newArray           :: Ix ix => (ix,ix) -> elt -> ST s (MutableArray s ix elt)
1387 newCharArray       :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1388 newAddrArray       :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1389 newIntArray        :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1390 newFloatArray      :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1391 newDoubleArray     :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1392
1393 boundsOfArray      :: Ix ix => MutableArray s ix elt -> (ix, ix)
1394 boundsOfByteArray  :: Ix ix => MutableByteArray s ix -> (ix, ix)
1395
1396
1397 readArray          :: Ix ix => MutableArray s ix elt -> ix -> ST s elt
1398
1399 readCharArray      :: Ix ix => MutableByteArray s ix -> ix -> ST s Char
1400 readIntArray       :: Ix ix => MutableByteArray s ix -> ix -> ST s Int
1401 readAddrArray      :: Ix ix => MutableByteArray s ix -> ix -> ST s Addr
1402 readFloatArray     :: Ix ix => MutableByteArray s ix -> ix -> ST s Float
1403 readDoubleArray    :: Ix ix => MutableByteArray s ix -> ix -> ST s Double
1404
1405 writeArray         :: Ix ix => MutableArray s ix elt -> ix -> elt -> ST s ()
1406 writeCharArray     :: Ix ix => MutableByteArray s ix -> ix -> Char -> ST s ()
1407 writeIntArray      :: Ix ix => MutableByteArray s ix -> ix -> Int  -> ST s ()
1408 writeAddrArray     :: Ix ix => MutableByteArray s ix -> ix -> Addr -> ST s ()
1409 writeFloatArray    :: Ix ix => MutableByteArray s ix -> ix -> Float -> ST s ()
1410 writeDoubleArray   :: Ix ix => MutableByteArray s ix -> ix -> Double -> ST s ()
1411
1412 freezeArray        :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
1413 freezeCharArray    :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1414 freezeIntArray     :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1415 freezeAddrArray    :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1416 freezeFloatArray   :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1417 freezeDoubleArray  :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1418
1419 unsafeFreezeArray     :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
1420 unsafeFreezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1421 thawArray             :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt)
1422 \end{verbatim}
1423
1424
1425 %************************************************************************
1426 %*                                                                      *
1427 \subsubsection{The @ByteArray@ interface}
1428 \index{ByteArray interface (GHC extensions)}
1429 %*                                                                      *
1430 %************************************************************************
1431
1432 @ByteArray@s are chunks of immutable Haskell heap:
1433
1434 \begin{verbatim}
1435 data ByteArray ix -- abstract
1436                   -- instance of: CCallable
1437
1438 indexCharArray     :: Ix ix => ByteArray ix -> ix -> Char
1439 indexIntArray      :: Ix ix => ByteArray ix -> ix -> Int
1440 indexAddrArray     :: Ix ix => ByteArray ix -> ix -> Addr
1441 indexFloatArray    :: Ix ix => ByteArray ix -> ix -> Float
1442 indexDoubleArray   :: Ix ix => ByteArray ix -> ix -> Double
1443
1444 indexCharOffAddr   :: Addr -> Int -> Char
1445 indexIntOffAddr    :: Addr -> Int -> Int
1446 indexAddrOffAddr   :: Addr -> Int -> Addr
1447 indexFloatOffAddr  :: Addr -> Int -> Float
1448 indexDoubleOffAddr :: Addr -> Int -> Double
1449
1450 \end{verbatim}
1451
1452 %************************************************************************
1453 %*                                                                      *
1454 \subsubsection{The @Foreign@ interface}
1455 \index{Foreign interface (GHC extensions)}
1456 %*                                                                      *
1457 %************************************************************************
1458
1459 The @Foreign@ interface define and export operations over @ForeignObj@
1460 and @StablePtr@s:
1461
1462 \begin{verbatim}
1463 -- semi-magic classes for pack/unpacking ccall arguments.
1464 class CCallable a
1465  {- Instances defined for :
1466       Char Char# Int Int# Float Float#
1467       Double Double# Addr Addr# Word Word#
1468       (MutableByteArray s ix) (MutableByteArray# s)
1469       (ByteArray ix) ByteArray#
1470       ForeignObj ForeignObj#
1471       (StablePtr a)
1472       (StablePtr# a)
1473       [Char]
1474  -}
1475 class CReturnable a
1476  {- Instances defined for :
1477       Char Int Float Double Addr Word
1478       (StablePtr a)
1479  -}
1480
1481 data ForeignObj = ForeignObj ForeignObj#
1482    -- instances of : CCallable Eq
1483
1484 eqForeignObj    :: ForeignObj  -> ForeignObj -> Bool
1485 makeForeignObj  :: Addr        -> Addr       -> PrimIO ForeignObj
1486 writeForeignObj :: ForeignObj  -> Addr       -> PrimIO ()
1487
1488 {- derived op - attaching a free() finaliser to a malloc() allocated reference. -}
1489 makeMallocPtr   :: Addr        -> PrimIO ForeignObj
1490
1491 data StablePtr a = StablePtr (StablePtr# a)
1492   -- instances of : CCallable
1493
1494 makeStablePtr  :: a -> PrimIO (StablePtr a)
1495 deRefStablePtr :: StablePtr a -> PrimIO a
1496 freeStablePtr  :: StablePtr a -> PrimIO ()
1497 performGC      :: PrimIO ()
1498 \end{verbatim}
1499
1500 \begin{onlystandalone}
1501 \end{document}
1502 \end{onlystandalone}
1503