ghc/docs/libraries/libs.sgml

   1 <!doctype linuxdoc system>
   2
   3 <!-- ToDo:
   4   o Add indexing support (to linuxdoc)
   5   o Fix citations in html
   6   -->
   7
   8 <article>
   9
  10 <title>The Hugs-GHC Extension Libraries
  11 <author>Alastair Reid <tt/reid-alastair@cs.yale.edu/
  12         Simon Marlow <tt/simonm@dcs.gla.ac.uk/
  13 <date>v0.8, 28 January 1998
  14 <abstract>
  15 Hugs and GHC provide a common set of libraries to aid portability.
  16 This document specifies the interfaces to these libraries and documents
  17 known differences.  We hope that these modules will be adopted for inclusion
  18 as Standard Haskell Libraries sometime soon.
  19 </abstract>
  20
  21 <toc>
  22
  23 <sect> <idx/Naming conventions/
  24 <label id="sec:Naming conventions">
  25 <p>
  26
  27 The set of interfaces specified in this document try to adhere to the
  28 following naming conventions:
  29
  30 <itemize>
  31 <item>
  32 Actions that create a new values have the prefix <tt/new/ followed by
  33 the name of the type of object they're creating, e.g., <tt/newIORef/,
  34 <tt/newChan/ etc.
  35 <item>
  36 Operations that read a value from a mutable object are prefixed with
  37 <tt/read/, and operations that update the contents have the prefix
  38 <tt/write/, e.g., <tt/readChan/, <tt/readIOArray/.
  39
  40 Notes:
  41 <itemize>
  42 <item>
  43 This differs from the convention used to name the operations for
  44 reading and writing to a file <tt/Handle/, where <tt/get/ and <tt/put/
  45 are used instead.
  46 <item>
  47 Operations provided by various concurrency abstractions, e.g., <tt/MVar/,
  48 <tt/CVar/ , also deviate from this naming scheme. This is perhaps
  49 defensible, since the read and write operations have additional
  50 behaviour, e.g., <tt/takeMVar/ tries to read the current value
  51 of an <tt/MVar/, locking it if it succeeds.
  52 </itemize>
  53 <item>
  54 Conversions operators have the form <tt/AToB/ where <tt/A/ and <tt/B/
  55 are the types we're converting between.
  56 <item>
  57 Operations that lazily read values from a mutable object/handle, have
  58 the form <tt/getXContents/, e.g., <tt/Channel.getChanContents/ and
  59 <tt/IO.hGetContents/. (OK, so the latter isn't called
  60 <tt/getHandleContents/, but you hopefully get the picture.)
  61 </itemize>
  62
  63 <sect> <idx/LazyST/ <p>
  64
  65 This library provides support for both <em/lazy/ and <em/strict/ state
  66 threads, as described in the PLDI '94 paper by John Launchbury and
  67 Simon Peyton Jones <cite id="LazyStateThreads">.  In addition to the
  68 monad <tt/ST/, it also provides mutable variables <tt/STRef/ and
  69 mutable arrays <tt/STArray/.  As the name suggests, the monad <tt/ST/
  70 instance is <em/lazy/.
  71 =======
  72 <sect> <idx/ST/
  73 <label id="sec:ST">
  74 <p>
  75
  76 This library provides support for <em/strict/ state threads, as
  77 described in the PLDI '94 paper by John Launchbury and Simon Peyton
  78 Jones <cite id="LazyStateThreads">.  In addition to the monad <tt/ST/,
  79 it also provides mutable variables <tt/STRef/ and mutable arrays
  80 <tt/STArray/.
  81
  82 <tscreen><verb>
  83 module ST( module ST, module Monad ) where
  84 import Monad
  85
  86 data ST s a        -- abstract type
  87 runST              :: forall a. (forall s. ST s a) -> a
  88 fixST              :: (a -> ST s a) -> ST s a
  89 unsafeInterleaveST :: ST s a -> ST s a
  90 instance Functor (ST s)
  91 instance Monad   (ST s)
  92
  93 data STRef s a     -- mutable variables in state thread s
  94                    -- containing values of type a.
  95 newSTRef           :: a -> ST s (STRef s a)
  96 readSTRef          :: STRef s a -> ST s a
  97 writeSTRef         :: STRef s a -> a -> ST s ()
  98 instance Eq (STRef s a)
  99
 100 data STArray s ix elt -- mutable arrays in state thread s
 101                       -- indexed by values of type ix
 102                       -- containing values of type a.
 103 newSTArray          :: Ix ix => (ix,ix) -> elt -> ST s (STArray s ix elt)
 104 boundsSTArray       :: Ix ix => STArray s ix elt -> (ix, ix)
 105 readSTArray         :: Ix ix => STArray s ix elt -> ix -> ST s elt
 106 writeSTArray        :: Ix ix => STArray s ix elt -> ix -> elt -> ST s ()
 107 thawSTArray         :: Ix ix => Array ix elt -> ST s (STArray s ix elt)
 108 freezeSTArray       :: Ix ix => STArray s ix elt -> ST s (Array ix elt)
 109 unsafeFreezeSTArray :: Ix ix => STArray s ix elt -> ST s (Array ix elt)
 110 instance Eq (STArray s ix elt)
 111 </verb></tscreen>
 112
 113 Notes:
 114 <itemize>
 115
 116 <item>
 117 GHC also supports ByteArrays --- these aren't supported by Hugs yet.
 118
 119 <item>
 120 The operations <tt/freezeSTArray/ and <tt/thawSTArray/ convert mutable
 121 arrays to and from immutable arrays.  Semantically, they are identical
 122 to copying the array and they are usually implemented that way.  The
 123 operation <tt/unsafeFreezeSTArray/ is a faster version of
 124 <tt/freezeSTArray/ which omits the copying step.  It's a safe substitute for
 125 <tt/freezeSTArray/ if you don't modify the mutable array after freezing it.
 126
 127 <item>
 128 In the current version of Hugs, the <tt/<idx/runST// operation,
 129 used to specify encapsulation, is implemented as a language construct,
 130 and <tt/runST/ is treated as a keyword.  We plan to change this to match
 131 GHC soon.
 132
 133 <!--
 134   <item>
 135      Note that it is possible to install Hugs 1.4 without support for lazy
 136      state threads, and hence the primitives described here may not be
 137      available in all implementations.  Also, in contrast with the
 138      implementation of lazy state threads in previous releases of Hugs and
 139      Gofer, there is no direct relationship between the
 140      <tt/<idx/ST monad// and the <tt/<idx/IO monad//.
 141   -->
 142
 143 <item>
 144 Hugs provides <tt/thenLazyST/ and <tt/thenStrictST/ so that you can
 145 import <tt/LazyST/ (say) and still use the strict instance in those
 146 places where it matters.  GHC implements LazyST and ST using different
 147 types, so this isn't possible.
 148 </item>
 149
 150 </itemize>
 151
 152 <sect> <idx/LazyST/
 153 <label id="sec:LazyST">
 154 <p>
 155
 156 This library is identical to <tt/ST/ except that the <tt/ST/ monad
 157 instance is <em/lazy/.  The lazy ST monad tends to be more prone to
 158 space leaks than the strict version, so most programmers will use the
 159 former unless laziness is explicitly required.  <tt/LazyST/ provides
 160 two additional operations:
 161
 162 <tscreen> <verb>
 163 lazyToStrictST :: LazyST.ST s a -> ST.ST s a
 164 strictToLazyST :: ST.ST s a -> LazyST.ST s a
 165 </verb> </tscreen>
 166
 167 These are used to convert between lazy and strict state threads.  The
 168 semantics with respect to laziness are as you would expect: the strict
 169 state thread passed to <tt/strictToLazyST/ is not performed until the
 170 result of the lazy state thread it returns is demanded.
 171
 172 <sect> <idx/IOExts/
 173 <label id="sec:IOExts">
 174 <p>
 175
 176 This library provides the following extensions to the IO monad:
 177 <itemize>
 178 <item>
 179 The operations <tt/fixIO/, <tt/unsafePerformIO/ and <tt/unsafeInterleaveIO/
 180 described in <cite id="ImperativeFP">
 181
 182 <item>
 183 References (aka mutable variables) and mutable arrays (but no form of
 184 mutable byte arrays)
 185
 186 <item>
 187 <tt/openFileEx/ extends the standard <tr/openFile/ action with support
 188 for opening binary files.
 189
 190 <item>
 191 <tt/performGC/ triggers an immediate garbage collection
 192
 193 <item>
 194 When called, <tt/trace/ prints the string in its first argument, and then
 195 returns the second argument as its result.  The <tt/trace/ function is not
 196 referentially transparent, and should only be used for debugging, or for
 197 monitoring execution.
 198
 199 <!--
 200   You should also be warned that, unless you understand some of the
 201   details about the way that Haskell programs are executed, results
 202   obtained using <tt/trace/ can be rather confusing.  For example, the
 203   messages may not appear in the order that you expect.  Even ignoring the
 204   output that they produce, adding calls to <tt/trace/ can change the
 205   semantics of your program.  Consider this a warning!
 206   -->
 207
 208 <item>
 209 <tt/unsafePtrEq/ compares two values for pointer equality without
 210 evaluating them.  The results are not referentially transparent and
 211 may vary significantly from one compiler to another or in the face of
 212 semantics-preserving program changes.  However, pointer equality is useful
 213 in creating a number of referentially transparent constructs such as this
 214 simplified memoisation function:
 215
 216 <tscreen><verb>
 217 > cache :: (a -> b) -> (a -> b)
 218 > cache f = \x -> unsafePerformIO (check x)
 219 >  where
 220 >   ref = unsafePerformIO (newIORef (error "cache", error "cache"))
 221 >   check x = readIORef ref >>= \ (x',a) ->
 222 >              if x `unsafePtrEq` x' then
 223 >                return a
 224 >              else
 225 >                let a = f x in
 226 >                writeIORef ref (x, a) >>
 227 >                return a
 228 </verb></tscreen>
 229
 230
 231 </itemize>
 232
 233 <tscreen><verb>
 234 module IOExts where
 235
 236 fixIO               :: (a -> IO a) -> IO a
 237 unsafePerformIO     :: IO a -> a
 238 unsafeInterleaveIO  :: IO a -> IO a
 239
 240 data IORef a        -- mutable variables containing values of type a
 241 newIORef            :: a -> IO (IORef a)
 242 readIORef           :: IORef a -> IO a
 243 writeIORef          :: IORef a -> a -> IO ()
 244 instance Eq (IORef a)
 245
 246 data IOArray ix elt -- mutable arrays indexed by values of type ix
 247                     -- containing values of type a.
 248 newIOArray          :: Ix ix => (ix,ix) -> elt -> IO (IOArray ix elt)
 249 boundsIOArray       :: Ix ix => IOArray ix elt -> (ix, ix)
 250 readIOArray         :: Ix ix => IOArray ix elt -> ix -> IO elt
 251 writeIOArray        :: Ix ix => IOArray ix elt -> ix -> elt -> IO ()
 252 freezeIOArray       :: Ix ix => IOArray ix elt -> IO (Array ix elt)
 253 instance Eq (IOArray ix elt)
 254
 255 openFileEx          :: FilePath -> IOModeEx -> IO Handle
 256 data IOModeEx = BinaryMode IO.IOMode | TextMode IO.IOMode
 257 instance Eq IOModeEx
 258 instance Read IOModeEx
 259 instance Show IOModeEx
 260
 261 performGC           :: IO ()
 262 trace               :: String -> a -> a
 263 unsafePtrEq         :: a -> a -> Bool
 264 </verb></tscreen>
 265
 266 <!--
 267   <sect> <idx/GlaExts/ <p>
 268
 269   This library provides a convenient bundle of most of the extensions
 270   available in GHC and Hugs.  This module is generally more stable than
 271   the other modules of non-standard extensions so you might choose to
 272   import them from here rather than going straight to the horses mouth.
 273
 274   <tscreen><verb>
 275   module GlaExts( module GlaExts, module IOExts, module ST, module Addr ) where
 276   import IOExts
 277   import ST
 278   import Addr
 279   trace              :: String -> a -> a
 280   performGC          :: IO ()
 281   </verb></tscreen>
 282
 283   The GHC version also provides the types <tt/PrimIO/, <tt/RealWorld/,
 284   <tt/ByteArray/, <tt/Lift/ and operations on these types. It also
 285   provides the unboxed views of the types
 286   <tt/Int/,
 287   <tt/Addr/,
 288   <tt/Word/,
 289   <tt/Float/,
 290   <tt/Double/,
 291   <tt/Integer/ and
 292   <tt/Char/
 293   and a number of ``primitive operations'' (<tt/+&num/,
 294   <tt/plusFloat&num/, etc.).
 295
 296   -->
 297
 298 <sect> <idx/Bits/
 299 <label id="sec:Bits">
 300 <p>
 301
 302 This library defines bitwise operations for signed and unsigned ints.
 303
 304 <tscreen><verb>
 305 module Bits where
 306 infixl 8 `shift`, `rotate`
 307 infixl 7 .&.
 308 infixl 6 `xor`
 309 infixl 5 .|.
 310
 311 class Bits a where
 312   (.&.), (.|.), xor :: a -> a -> a
 313   complement        :: a -> a
 314   shift             :: a -> Int -> a
 315   rotate            :: a -> Int -> a
 316   bit               :: Int -> a
 317   setBit            :: a -> Int -> a
 318   clearBit          :: a -> Int -> a
 319   complementBit     :: a -> Int -> a
 320   testBit           :: a -> Int -> Bool
 321   bitSize           :: a -> Int
 322   isSigned          :: a -> Bool
 323
 324 shiftL, shiftR   :: Bits a => a -> Int -> a
 325 rotateL, rotateR :: Bits a => a -> Int -> a
 326 shiftL  a i = shift  a i
 327 shiftR  a i = shift  a (-i)
 328 rotateL a i = rotate a i
 329 rotateR a i = rotate a (-i)
 330 </verb></tscreen>
 331
 332 Notes:
 333 <itemize>
 334 <item>
 335   <tt/bitSize/ and <tt/isSigned/ are like <tt/floatRadix/ and <tt/floatDigits/
 336   -- they return parameters of the <em/type/ of their argument rather than
 337   of the particular argument they are applied to.  <tt/bitSize/ returns
 338   the number of bits in the type (or <tt/Nothing/ for unbounded types); and
 339   <tt/isSigned/ returns whether the type is signed or not.
 340 <item>
 341   <tt/shift/ performs sign extension on signed number types.
 342   That is, right shifts fill the top bits with 1 if the number is negative
 343   and with 0 otherwise.
 344 <item>
 345   Bits are numbered from 0 with bit 0 being the least significant bit.
 346 <item>
 347   <tt/shift x i/ and <tt/rotate x i/ shift to the left if <tt/i/ is
 348   positive and to the right otherwise.
 349 <!--
 350   <item>
 351     <tt/rotate/ is well defined only if bitSize returns a number.
 352     (Maybe we should impose a Bounded constraint on it?)
 353   -->
 354 <item>
 355   <tt/bit i/ is the value with the i'th bit set.
 356 </itemize>
 357
 358 <sect> <idx/Word/
 359 <label id="sec:Word">
 360 <p>
 361
 362 This library provides unsigned integers of various sizes.
 363 The types supported are as follows:
 364
 365 <tabular ca="ll">
 366 type    | number of bits @
 367 <!-- <hline>  -->
 368 Word8    | 8  @
 369 Word16   | 16 @
 370 Word32   | 32 @
 371 Word64   | 64 @
 372 <!-- <hline>  -->
 373 </tabular>
 374
 375 For each type <it/W/ above, we provide the following functions and
 376 instances.  The type <it/I/ refers to the signed integer type of the
 377 same size.
 378
 379 <tscreen><verb>
 380 data W            -- Unsigned Ints
 381 instance Eq       W
 382 instance Ord      W
 383 instance Show     W
 384 instance Read     W
 385 instance Bounded  W
 386 instance Num      W
 387 instance Real     W
 388 instance Integral W
 389 instance Enum     W
 390 instance Ix       W
 391 instance Bits     W
 392 </verb></tscreen>
 393 Plus
 394 <tscreen><verb>
 395 word8ToWord32  :: Word8  -> Word32
 396 word32ToWord8  :: Word32 -> Word8
 397 word16ToWord32 :: Word16 -> Word32
 398 word32ToWord16 :: Word32 -> Word16
 399
 400 word8ToInt     :: Word8  -> Int
 401 intToWord8     :: Int    -> Word8
 402 word16ToInt    :: Word16 -> Int
 403 intToWord16    :: Int    -> Word16
 404 word32ToInt    :: Word32 -> Int
 405 intToWord32    :: Int    -> Word32
 406 </verb></tscreen>
 407
 408 Notes:
 409 <itemize>
 410 <item>
 411   All arithmetic is performed modulo 2^n
 412
 413   One non-obvious consequequence of this is that <tt/negate/
 414   should <em/not/ raise an error on negative arguments.
 415
 416 <item>
 417 The coercion <tt/wToI/ converts an unsigned n-bit value to the
 418 signed n-bit value with the same representation.  For example,
 419 <tt/word8ToInt8 0xff = -1/.
 420 Likewise, <tt/iToW/ converts signed n-bit values to the
 421 corresponding unsigned n-bit value.
 422
 423 <item>
 424 ToDo: complete the set of coercion functions.
 425
 426 <item>
 427 Use <tt/Prelude.fromIntegral :: (Integral a, Num b) => a -> b/ to
 428 coerce between different sizes or to preserve sign when converting
 429 between values of the same size.
 430
 431 <item>
 432 It would be very natural to add a type a type <tt/Natural/ providing
 433 an unbounded size unsigned integer --- just as <tt/Integer/ provides
 434 unbounded size signed integers.  We do not do that yet since there is
 435 no demand for it.  Doing so would require <tt/Bits.bitSize/ to return
 436 <tt/Maybe Int/.
 437
 438 <item>
 439 The <tt/Enum/ instances stop when they reach their upper or lower
 440 bound --- they don't overflow the way the <tt/Int/ and <tt/Float/
 441 instances do.
 442
 443 <item>
 444 It would be useful to provide a function (or a family of functions?)
 445 which coerced between any two Word types (without going through
 446 Integer).
 447
 448 </itemize>
 449
 450 Hugs only provides <tt/Eq/, <tt/Ord/, <tt/Read/ and <tt/Show/
 451 instances for <tt/Word64/ at the moment.
 452
 453 <sect> <idx/Int/
 454 <label id="sec:Int">
 455 <p>
 456
 457 This library provides signed integers of various sizes.  The types
 458 supported are as follows:
 459
 460 <tabular ca="ll">
 461 type    | number of bits @
 462 <!-- <hline>  -->
 463 Int8    | 8  @
 464 Int16   | 16 @
 465 Int32   | 32 @
 466 Int64   | 64 @
 467 <!-- <hline>  -->
 468 </tabular>
 469
 470 For each type <it/I/ above, we provide the following instances.
 471
 472 <tscreen><verb>
 473 data I            -- Signed Ints
 474 iToInt            :: I -> Int  -- not provided for Int64
 475 intToi            :: Int -> I  -- not provided for Int64
 476 instance Eq       I
 477 instance Ord      I
 478 instance Show     I
 479 instance Read     I
 480 instance Bounded  I
 481 instance Num      I
 482 instance Real     I
 483 instance Integral I
 484 instance Enum     I
 485 instance Ix       I
 486 instance Bits     I
 487 </verb></tscreen>
 488 Plus
 489 <tscreen><verb>
 490 int8ToInt  :: Int8  -> Int
 491 intToInt8  :: Int   -> Int8
 492 int16ToInt :: Int16 -> Int
 493 intToInt16 :: Int   -> Int16
 494 int32ToInt :: Int32 -> Int
 495 intToInt32 :: Int   -> Int32
 496 </verb></tscreen>
 497
 498 <itemize>
 499 <item>
 500 Hugs does not provide <tt/Int64/ at the moment.
 501
 502 <item>
 503 ToDo: complete the set of coercion functions.
 504
 505 </itemize>
 506
 507 <sect> <idx/Addr/
 508 <label id="sec:Addr">
 509 <p>
 510
 511 This library provides machine addresses and is primarily intended for
 512 use in creating foreign function interfaces using GreenCard.
 513
 514 <tscreen><verb>
 515 module Addr where
 516 data Addr  -- Address type
 517 instance Eq Addr
 518
 519 nullAddr           :: Addr
 520 plusAddr           :: Addr -> Int -> Addr
 521
 522 -- read value out of _immutable_ memory
 523 indexCharOffAddr   :: Addr -> Int -> Char
 524 indexIntOffAddr    :: Addr -> Int -> Int     -- should we drop this?
 525 indexAddrOffAddr   :: Addr -> Int -> Addr
 526 indexFloatOffAddr  :: Addr -> Int -> Float
 527 indexDoubleOffAddr :: Addr -> Int -> Double
 528 indexWord8OffAddr  :: Addr -> Int -> Word8
 529 indexWord16OffAddr :: Addr -> Int -> Word16
 530 indexWord32OffAddr :: Addr -> Int -> Word32
 531 indexWord64OffAddr :: Addr -> Int -> Word64
 532 indexInt8OffAddr   :: Addr -> Int -> Int8
 533 indexInt16OffAddr  :: Addr -> Int -> Int16
 534 indexInt32OffAddr  :: Addr -> Int -> Int32
 535 indexInt64OffAddr  :: Addr -> Int -> Int64
 536
 537 -- read value out of mutable memory
 538 readCharOffAddr    :: Addr -> Int -> IO Char
 539 readIntOffAddr     :: Addr -> Int -> IO Int  -- should we drop this?
 540 readAddrOffAddr    :: Addr -> Int -> IO Addr
 541 readFloatOffAddr   :: Addr -> Int -> IO Float
 542 readDoubleOffAddr  :: Addr -> Int -> IO Double
 543 readWord8OffAddr   :: Addr -> Int -> IO Word8
 544 readWord16OffAddr  :: Addr -> Int -> IO Word16
 545 readWord32OffAddr  :: Addr -> Int -> IO Word32
 546 readWord64OffAddr  :: Addr -> Int -> IO Word64
 547 readInt8OffAddr    :: Addr -> Int -> IO Int8
 548 readInt16OffAddr   :: Addr -> Int -> IO Int16
 549 readInt32OffAddr   :: Addr -> Int -> IO Int32
 550 readInt64OffAddr   :: Addr -> Int -> IO Int64
 551
 552 -- write value into mutable memory
 553 writeCharOffAddr   :: Addr -> Int -> Char   -> IO ()
 554 writeIntOffAddr    :: Addr -> Int -> Int    -> IO ()  -- should we drop this?
 555 writeAddrOffAddr   :: Addr -> Int -> Addr   -> IO ()
 556 writeFloatOffAddr  :: Addr -> Int -> Float  -> IO ()
 557 writeDoubleOffAddr :: Addr -> Int -> Double -> IO ()
 558 writeWord8OffAddr  :: Addr -> Int -> Word8  -> IO ()
 559 writeWord16OffAddr :: Addr -> Int -> Word16 -> IO ()
 560 writeWord32OffAddr :: Addr -> Int -> Word32 -> IO ()
 561 writeWord64OffAddr :: Addr -> Int -> Word64 -> IO ()
 562 writeInt8OffAddr   :: Addr -> Int -> Int8   -> IO ()
 563 writeInt16OffAddr  :: Addr -> Int -> Int16  -> IO ()
 564 writeInt32OffAddr  :: Addr -> Int -> Int32  -> IO ()
 565 writeInt64OffAddr  :: Addr -> Int -> Int64  -> IO ()
 566 </verb></tscreen>
 567
 568 Hugs provides <tt/Addr/ and <tt/nullAddr/ but does not provide any of
 569 the index, read or write functions.  They can be implemented using
 570 GreenCard if required.
 571
 572 <sect> <idx/NumExts/
 573 <label id="sec:NumExts">
 574 <p>
 575
 576 The <tt/NumExts/ interface collect together various numeric
 577 operations that have proven to be commonly useful
 578
 579 <tscreen> <verb>
 580 -- Going between Doubles and Floats:
 581 doubleToFloat :: Double -> Float
 582 floatToDouble :: Float  -> Double
 583
 584 showHex       :: Integral a => a -> ShowS
 585 showOct       :: Integral a => a -> ShowS
 586 </verb> </tscreen>
 587
 588 Notes:
 589 <itemize>
 590 <item>
 591     If <tt/doubleToFloat/ is applied to a <tt/Double/ that is within
 592     the representable range for <tt/Float/, the result may be the next
 593     higher or lower representable <tt/Float/ value. If the <tt/Double/
 594     is out of range, the result is undefined.
 595 <item>
 596     No loss of precision occurs in the other direction with
 597     <tt/floatToDouble/, the floating value remains unchanged.
 598 <item>
 599     <tt/showOct/ and <tt/showHex/ will prefix <tt/0o/ and <tt/0x/
 600     respectively. Like <tt/Numeric.showInt/, these show functions
 601     work on positive numbers only.
 602 </itemize>
 603
 604 <sect> <idx/Foreign/
 605 <label id="sec:Foreign">
 606 <p>
 607
 608 This module is provided by GHC but not by Hugs.
 609 GreenCard for Hugs provides the <tt/ForeignObj/ type.
 610
 611 <sect> <idx/Concurrent/
 612 <label id="sec:Concurrent">
 613 <p>
 614
 615 This library provides the Concurrent Haskell extensions
 616 <cite id="concurrentHaskell:popl96">.
 617
 618 We are grateful to the Glasgow Haskell Project for allowing us to
 619 redistribute their implementation of this module.
 620
 621 <tscreen><verb>
 622 module Concurrent where
 623
 624 data ThreadId    -- thread identifiers
 625 instance Eq  ThreadId
 626 instance Ord ThreadId
 627
 628 forkIO           :: IO () -> IO ThreadId
 629 killThread       :: ThreadId -> IO ()
 630
 631 data MVar a      -- Synchronisation variables
 632 newEmptyMVar     :: IO (MVar a)
 633 newMVar          :: a -> IO (MVar a)
 634 takeMVar         :: MVar a -> IO a
 635 putMVar          :: MVar a -> a -> IO ()
 636 swapMVar         :: MVar a -> a -> IO a
 637 readMVar         :: MVar a -> IO a
 638 instance Eq (MVar a)
 639
 640 data Chan a      -- channels
 641 newChan          :: IO (Chan a)
 642 writeChan        :: Chan a -> a -> IO ()
 643 readChan         :: Chan a -> IO a
 644 dupChan          :: Chan a -> IO (Chan a)
 645 unReadChan       :: Chan a -> a -> IO ()
 646 getChanContents  :: Chan a -> IO [a]
 647 writeList2Chan   :: Chan a -> [a] -> IO ()
 648
 649 data CVar a       -- one element channels
 650 newCVar          :: IO (CVar a)
 651 putCVar          :: CVar a -> a -> IO ()
 652 getCVar          :: CVar a -> IO a
 653
 654 data QSem        -- General/quantity semaphores
 655 newQSem          :: Int  -> IO QSem
 656 waitQSem         :: QSem -> IO ()
 657 signalQSem       :: QSem -> IO ()
 658
 659 data QSemN       -- General/quantity semaphores
 660 newQSemN         :: Int   -> IO QSemN
 661 waitQSemN        :: QSemN -> Int -> IO ()
 662 signalQSemN      :: QSemN -> Int -> IO ()
 663
 664 type SampleVar a -- Sample variables
 665 newEmptySampleVar:: IO (SampleVar a)
 666 newSampleVar     :: a -> IO (SampleVar a)
 667 emptySampleVar   :: SampleVar a -> IO ()
 668 readSampleVar    :: SampleVar a -> IO a
 669 writeSampleVar   :: SampleVar a -> a -> IO ()
 670 </verb></tscreen>
 671
 672 Notes:
 673 <itemize>
 674
 675 <item>
 676   GHC uses preemptive multitasking:
 677   Context switches can occur at any time, except if you call a C
 678   function (like \verb"getchar") that blocks waiting for input.
 679
 680   Hugs uses cooperative multitasking:
 681   Context switches only occur when you use one of the primitives
 682   defined in this module.  This means that programs such as:
 683
 684 <tscreen><verb>
 685 main = forkIO (write 'a') >> write 'b'
 686  where write c = putChar c >> write c
 687 </verb></tscreen>
 688
 689   will print either <tt/aaaaaaaaaaaaaa.../ or <tt/bbbbbbbbbbbb.../,
 690   instead of some random interleaving of <tt/a/s and <tt/b/s.
 691
 692   In practice, cooperative multitasking is sufficient for writing
 693   simple graphical user interfaces.
 694
 695 <item>
 696 Hugs does not provide the functions <tt/mergeIO/ or <tt/nmergeIO/ since these
 697 require preemptive multitasking.
 698
 699 <item>
 700 Thread identities and <tt/killThread/ has not been implemented yet on
 701 either system. The plan is that <tt/killThread/ will raise an IO
 702 exception in the killed thread which it can catch --- perhaps allowing -->
 703 --it to kill its children before exiting.
 704
 705 <item>
 706 The <tt/Ord/ instance for <tt/ThreadId/s provides an arbitrary total ordering
 707 which might be used to build an ordered binary tree, say.
 708
 709 </itemize>
 710
 711 <sect> <idx/Pretty/
 712 <label id="sec:Pretty">
 713 <p>
 714
 715 This library contains Simon Peyton Jones' implementation of John
 716 Hughes's pretty printer combinators.
 717
 718 <tscreen><verb>
 719 module Pretty where
 720 infixl 6 <>
 721 infixl 6 <+>
 722 infixl 5 $$, $+$
 723 data Doc  -- the Document datatype
 724
 725 -- The primitive Doc values
 726 empty                     :: Doc
 727 text                      :: String   -> Doc
 728 char                      :: Char     -> Doc
 729 int                       :: Int      -> Doc
 730 integer                   :: Integer  -> Doc
 731 float                     :: Float    -> Doc
 732 double                    :: Double   -> Doc
 733 rational                  :: Rational -> Doc
 734 semi, comma, colon, space, equals              :: Doc
 735 lparen, rparen, lbrack, rbrack, lbrace, rbrace :: Doc
 736 parens, brackets, braces  :: Doc -> Doc
 737 quotes, doubleQuotes      :: Doc -> Doc
 738
 739 -- Combining Doc values
 740 (<>)   :: Doc -> Doc -> Doc     -- Beside
 741 hcat   :: [Doc] -> Doc          -- List version of <>
 742 (<+>)  :: Doc -> Doc -> Doc     -- Beside, separated by space
 743 hsep   :: [Doc] -> Doc          -- List version of <+>
 744 ($$)   :: Doc -> Doc -> Doc     -- Above; if there is no
 745                                   -- overlap it "dovetails" the two
 746 vcat   :: [Doc] -> Doc          -- List version of $$
 747 cat    :: [Doc] -> Doc          -- Either hcat or vcat
 748 sep    :: [Doc] -> Doc          -- Either hsep or vcat
 749 fcat   :: [Doc] -> Doc          -- ``Paragraph fill'' version of cat
 750 fsep   :: [Doc] -> Doc          -- ``Paragraph fill'' version of sep
 751 nest   :: Int -> Doc -> Doc     -- Nested
 752 hang   :: Doc -> Int -> Doc -> Doc
 753 punctuate :: Doc -> [Doc] -> [Doc]
 754 -- punctuate p [d1, ... dn] = [d1 <> p, d2 <> p, ... dn-1 <> p, dn]
 755
 756 -- Displaying Doc values
 757 instance Show Doc
 758 render     :: Doc -> String             -- Uses default style
 759 renderStyle  :: Style -> Doc -> String
 760 data Style = Style { lineLength     :: Int,   -- In chars
 761                        ribbonsPerLine :: Float, -- Ratio of ribbon length
 762                                                 -- to line length
 763                        mode :: Mode
 764                }
 765 data Mode = PageMode            -- Normal
 766             | ZigZagMode          -- With zig-zag cuts
 767             | LeftMode            -- No indentation, infinitely long lines
 768             | OneLineMode         -- All on one line
 769 </verb></tscreen>
 770
 771 <biblio files="refs" style="abbrv">
 772
 773
 774 </article>
 775