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/performGC/ triggers an immediate garbage collection
 188
 189 <item>
 190 When called, <tt/trace/ prints the string in its first argument, and then
 191 returns the second argument as its result.  The <tt/trace/ function is not
 192 referentially transparent, and should only be used for debugging, or for
 193 monitoring execution.
 194
 195 <!--
 196   You should also be warned that, unless you understand some of the
 197   details about the way that Haskell programs are executed, results
 198   obtained using <tt/trace/ can be rather confusing.  For example, the
 199   messages may not appear in the order that you expect.  Even ignoring the
 200   output that they produce, adding calls to <tt/trace/ can change the
 201   semantics of your program.  Consider this a warning!
 202   -->
 203
 204 <item>
 205 <tt/unsafePtrEq/ compares two values for pointer equality without
 206 evaluating them.  The results are not referentially transparent and
 207 may vary significantly from one compiler to another or in the face of
 208 semantics-preserving program changes.  However, pointer equality is useful
 209 in creating a number of referentially transparent constructs such as this
 210 simplified memoisation function:
 211
 212 <tscreen><verb>
 213 > cache :: (a -> b) -> (a -> b)
 214 > cache f = \x -> unsafePerformIO (check x)
 215 >  where
 216 >   ref = unsafePerformIO (newIORef (error "cache", error "cache"))
 217 >   check x = readIORef ref >>= \ (x',a) ->
 218 >              if x `unsafePtrEq` x' then
 219 >                return a
 220 >              else
 221 >                let a = f x in
 222 >                writeIORef ref (x, a) >>
 223 >                return a
 224 </verb></tscreen>
 225
 226
 227 </itemize>
 228
 229 <tscreen><verb>
 230 module IOExts where
 231
 232 fixIO               :: (a -> IO a) -> IO a
 233 unsafePerformIO     :: IO a -> a
 234 unsafeInterleaveIO  :: IO a -> IO a
 235
 236 data IORef a        -- mutable variables containing values of type a
 237 newIORef            :: a -> IO (IORef a)
 238 readIORef           :: IORef a -> IO a
 239 writeIORef          :: IORef a -> a -> IO ()
 240 instance Eq (IORef a)
 241
 242 data IOArray ix elt -- mutable arrays indexed by values of type ix
 243                     -- containing values of type a.
 244 newIOArray          :: Ix ix => (ix,ix) -> elt -> IO (IOArray ix elt)
 245 boundsIOArray       :: Ix ix => IOArray ix elt -> (ix, ix)
 246 readIOArray         :: Ix ix => IOArray ix elt -> ix -> IO elt
 247 writeIOArray        :: Ix ix => IOArray ix elt -> ix -> elt -> IO ()
 248 freezeIOArray       :: Ix ix => IOArray ix elt -> IO (Array ix elt)
 249 instance Eq (IOArray ix elt)
 250
 251 performGC           :: IO ()
 252 trace               :: String -> a -> a
 253 unsafePtrEq         :: a -> a -> Bool
 254 </verb></tscreen>
 255
 256 <!--
 257   <sect> <idx/GlaExts/ <p>
 258
 259   This library provides a convenient bundle of most of the extensions
 260   available in GHC and Hugs.  This module is generally more stable than
 261   the other modules of non-standard extensions so you might choose to
 262   import them from here rather than going straight to the horses mouth.
 263
 264   <tscreen><verb>
 265   module GlaExts( module GlaExts, module IOExts, module ST, module Addr ) where
 266   import IOExts
 267   import ST
 268   import Addr
 269   trace              :: String -> a -> a
 270   performGC          :: IO ()
 271   </verb></tscreen>
 272
 273   The GHC version also provides the types <tt/PrimIO/, <tt/RealWorld/,
 274   <tt/ByteArray/, <tt/Lift/ and operations on these types. It also
 275   provides the unboxed views of the types
 276   <tt/Int/,
 277   <tt/Addr/,
 278   <tt/Word/,
 279   <tt/Float/,
 280   <tt/Double/,
 281   <tt/Integer/ and
 282   <tt/Char/
 283   and a number of ``primitive operations'' (<tt/+&num/,
 284   <tt/plusFloat&num/, etc.).
 285
 286   -->
 287
 288 <sect> <idx/Bits/
 289 <label id="sec:Bits">
 290 <p>
 291
 292 This library defines bitwise operations for signed and unsigned ints.
 293
 294 <tscreen><verb>
 295 module Bits where
 296 infixl 8 `shift`, `rotate`
 297 infixl 7 .&.
 298 infixl 6 `xor`
 299 infixl 5 .|.
 300
 301 class Bits a where
 302   (.&.), (.|.), xor :: a -> a -> a
 303   complement        :: a -> a
 304   shift             :: a -> Int -> a
 305   rotate            :: a -> Int -> a
 306   bit               :: Int -> a
 307   setBit            :: a -> Int -> a
 308   clearBit          :: a -> Int -> a
 309   complementBit     :: a -> Int -> a
 310   testBit           :: a -> Int -> Bool
 311   bitSize           :: a -> Int
 312   isSigned          :: a -> Bool
 313
 314 shiftL, shiftR   :: Bits a => a -> Int -> a
 315 rotateL, rotateR :: Bits a => a -> Int -> a
 316 shiftL  a i = shift  a i
 317 shiftR  a i = shift  a (-i)
 318 rotateL a i = rotate a i
 319 rotateR a i = rotate a (-i)
 320 </verb></tscreen>
 321
 322 Notes:
 323 <itemize>
 324 <item>
 325   <tt/bitSize/ and <tt/isSigned/ are like <tt/floatRadix/ and <tt/floatDigits/
 326   -- they return parameters of the <em/type/ of their argument rather than
 327   of the particular argument they are applied to.  <tt/bitSize/ returns
 328   the number of bits in the type (or <tt/Nothing/ for unbounded types); and
 329   <tt/isSigned/ returns whether the type is signed or not.
 330 <item>
 331   <tt/shift/ performs sign extension on signed number types.
 332   That is, right shifts fill the top bits with 1 if the number is negative
 333   and with 0 otherwise.
 334 <item>
 335   Bits are numbered from 0 with bit 0 being the least significant bit.
 336 <item>
 337   <tt/shift x i/ and <tt/rotate x i/ shift to the left if <tt/i/ is
 338   positive and to the right otherwise.
 339 <!--
 340   <item>
 341     <tt/rotate/ is well defined only if bitSize returns a number.
 342     (Maybe we should impose a Bounded constraint on it?)
 343   -->
 344 <item>
 345   <tt/bit i/ is the value with the i'th bit set.
 346 </itemize>
 347
 348 <sect> <idx/Word/
 349 <label id="sec:Word">
 350 <p>
 351
 352 This library provides unsigned integers of various sizes.
 353 The types supported are as follows:
 354
 355 <tabular ca="ll">
 356 type    | number of bits @
 357 <!-- <hline>  -->
 358 Word8    | 8  @
 359 Word16   | 16 @
 360 Word32   | 32 @
 361 Word64   | 64 @
 362 <!-- <hline>  -->
 363 </tabular>
 364
 365 For each type <it/W/ above, we provide the following functions and
 366 instances.  The type <it/I/ refers to the signed integer type of the
 367 same size.
 368
 369 <tscreen><verb>
 370 data W            -- Unsigned Ints
 371 instance Eq       W
 372 instance Ord      W
 373 instance Show     W
 374 instance Read     W
 375 instance Bounded  W
 376 instance Num      W
 377 instance Real     W
 378 instance Integral W
 379 instance Enum     W
 380 instance Ix       W
 381 instance Bits     W
 382 </verb></tscreen>
 383 Plus
 384 <tscreen><verb>
 385 word8ToWord32  :: Word8  -> Word32
 386 word32ToWord8  :: Word32 -> Word8
 387 word16ToWord32 :: Word16 -> Word32
 388 word32ToWord16 :: Word32 -> Word16
 389
 390 word8ToInt     :: Word8  -> Int
 391 intToWord8     :: Int    -> Word8
 392 word16ToInt    :: Word16 -> Int
 393 intToWord16    :: Int    -> Word16
 394 word32ToInt    :: Word32 -> Int
 395 intToWord32    :: Int    -> Word32
 396 </verb></tscreen>
 397
 398 Notes:
 399 <itemize>
 400 <item>
 401   All arithmetic is performed modulo 2^n
 402
 403   One non-obvious consequequence of this is that <tt/negate/
 404   should <em/not/ raise an error on negative arguments.
 405
 406 <item>
 407 The coercion <tt/wToI/ converts an unsigned n-bit value to the
 408 signed n-bit value with the same representation.  For example,
 409 <tt/word8ToInt8 0xff = -1/.
 410 Likewise, <tt/iToW/ converts signed n-bit values to the
 411 corresponding unsigned n-bit value.
 412
 413 <item>
 414 ToDo: complete the set of coercion functions.
 415
 416 <item>
 417 Use <tt/Prelude.fromIntegral :: (Integral a, Num b) => a -> b/ to
 418 coerce between different sizes or to preserve sign when converting
 419 between values of the same size.
 420
 421 <item>
 422 It would be very natural to add a type a type <tt/Natural/ providing
 423 an unbounded size unsigned integer --- just as <tt/Integer/ provides
 424 unbounded size signed integers.  We do not do that yet since there is
 425 no demand for it.  Doing so would require <tt/Bits.bitSize/ to return
 426 <tt/Maybe Int/.
 427
 428 <item>
 429 The <tt/Enum/ instances stop when they reach their upper or lower
 430 bound --- they don't overflow the way the <tt/Int/ and <tt/Float/
 431 instances do.
 432
 433 <item>
 434 It would be useful to provide a function (or a family of functions?)
 435 which coerced between any two Word types (without going through
 436 Integer).
 437
 438 </itemize>
 439
 440 Hugs only provides <tt/Eq/, <tt/Ord/, <tt/Read/ and <tt/Show/
 441 instances for <tt/Word64/ at the moment.
 442
 443 <sect> <idx/Int/
 444 <label id="sec:Int">
 445 <p>
 446
 447 This library provides signed integers of various sizes.  The types
 448 supported are as follows:
 449
 450 <tabular ca="ll">
 451 type    | number of bits @
 452 <!-- <hline>  -->
 453 Int8    | 8  @
 454 Int16   | 16 @
 455 Int32   | 32 @
 456 Int64   | 64 @
 457 <!-- <hline>  -->
 458 </tabular>
 459
 460 For each type <it/I/ above, we provide the following instances.
 461
 462 <tscreen><verb>
 463 data I            -- Signed Ints
 464 iToInt            :: I -> Int  -- not provided for Int64
 465 intToi            :: Int -> I  -- not provided for Int64
 466 instance Eq       I
 467 instance Ord      I
 468 instance Show     I
 469 instance Read     I
 470 instance Bounded  I
 471 instance Num      I
 472 instance Real     I
 473 instance Integral I
 474 instance Enum     I
 475 instance Ix       I
 476 instance Bits     I
 477 </verb></tscreen>
 478 Plus
 479 <tscreen><verb>
 480 int8ToInt  :: Int8  -> Int
 481 intToInt8  :: Int   -> Int8
 482 int16ToInt :: Int16 -> Int
 483 intToInt16 :: Int   -> Int16
 484 int32ToInt :: Int32 -> Int
 485 intToInt32 :: Int   -> Int32
 486 </verb></tscreen>
 487
 488 <itemize>
 489 <item>
 490 Hugs does not provide <tt/Int64/ at the moment.
 491
 492 <item>
 493 ToDo: complete the set of coercion functions.
 494
 495 </itemize>
 496
 497 <sect> <idx/Addr/
 498 <label id="sec:Addr">
 499 <p>
 500
 501 This library provides machine addresses and is primarily intended for
 502 use in creating foreign function interfaces using GreenCard.
 503
 504 <tscreen><verb>
 505 module Addr where
 506 data Addr  -- Address type
 507 instance Eq Addr
 508
 509 nullAddr           :: Addr
 510 plusAddr           :: Addr -> Int -> Addr
 511
 512 -- read value out of _immutable_ memory
 513 indexCharOffAddr   :: Addr -> Int -> Char
 514 indexIntOffAddr    :: Addr -> Int -> Int     -- should we drop this?
 515 indexAddrOffAddr   :: Addr -> Int -> Addr
 516 indexFloatOffAddr  :: Addr -> Int -> Float
 517 indexDoubleOffAddr :: Addr -> Int -> Double
 518 indexWord8OffAddr  :: Addr -> Int -> Word8
 519 indexWord16OffAddr :: Addr -> Int -> Word16
 520 indexWord32OffAddr :: Addr -> Int -> Word32
 521 indexWord64OffAddr :: Addr -> Int -> Word64
 522 indexInt8OffAddr   :: Addr -> Int -> Int8
 523 indexInt16OffAddr  :: Addr -> Int -> Int16
 524 indexInt32OffAddr  :: Addr -> Int -> Int32
 525 indexInt64OffAddr  :: Addr -> Int -> Int64
 526
 527 -- read value out of mutable memory
 528 readCharOffAddr    :: Addr -> Int -> IO Char
 529 readIntOffAddr     :: Addr -> Int -> IO Int  -- should we drop this?
 530 readAddrOffAddr    :: Addr -> Int -> IO Addr
 531 readFloatOffAddr   :: Addr -> Int -> IO Float
 532 readDoubleOffAddr  :: Addr -> Int -> IO Double
 533 readWord8OffAddr   :: Addr -> Int -> IO Word8
 534 readWord16OffAddr  :: Addr -> Int -> IO Word16
 535 readWord32OffAddr  :: Addr -> Int -> IO Word32
 536 readWord64OffAddr  :: Addr -> Int -> IO Word64
 537 readInt8OffAddr    :: Addr -> Int -> IO Int8
 538 readInt16OffAddr   :: Addr -> Int -> IO Int16
 539 readInt32OffAddr   :: Addr -> Int -> IO Int32
 540 readInt64OffAddr   :: Addr -> Int -> IO Int64
 541
 542 -- write value into mutable memory
 543 writeCharOffAddr   :: Addr -> Int -> Char   -> IO ()
 544 writeIntOffAddr    :: Addr -> Int -> Int    -> IO ()  -- should we drop this?
 545 writeAddrOffAddr   :: Addr -> Int -> Addr   -> IO ()
 546 writeFloatOffAddr  :: Addr -> Int -> Float  -> IO ()
 547 writeDoubleOffAddr :: Addr -> Int -> Double -> IO ()
 548 writeWord8OffAddr  :: Addr -> Int -> Word8  -> IO ()
 549 writeWord16OffAddr :: Addr -> Int -> Word16 -> IO ()
 550 writeWord32OffAddr :: Addr -> Int -> Word32 -> IO ()
 551 writeWord64OffAddr :: Addr -> Int -> Word64 -> IO ()
 552 writeInt8OffAddr   :: Addr -> Int -> Int8   -> IO ()
 553 writeInt16OffAddr  :: Addr -> Int -> Int16  -> IO ()
 554 writeInt32OffAddr  :: Addr -> Int -> Int32  -> IO ()
 555 writeInt64OffAddr  :: Addr -> Int -> Int64  -> IO ()
 556 </verb></tscreen>
 557
 558 Hugs provides <tt/Addr/ and <tt/nullAddr/ but does not provide any of
 559 the index, read or write functions.  They can be implemented using
 560 GreenCard if required.
 561
 562 <sect> <idx/NumExts/
 563 <label id="sec:NumExts">
 564 <p>
 565
 566 The <tt/NumExts/ interface collect together various numeric
 567 operations that have proven to be commonly useful
 568
 569 <tscreen> <verb>
 570 -- Going between Doubles and Floats:
 571 doubleToFloat :: Double -> Float
 572 floatToDouble :: Float  -> Double
 573
 574 showHex       :: Integral a => a -> ShowS
 575 showOct       :: Integral a => a -> ShowS
 576 </verb> </tscreen>
 577
 578 Notes:
 579 <itemize>
 580 <item>
 581     If <tt/doubleToFloat/ is applied to a <tt/Double/ that is within
 582     the representable range for <tt/Float/, the result may be the next
 583     higher or lower representable <tt/Float/ value. If the <tt/Double/
 584     is out of range, the result is undefined.
 585 <item>
 586     No loss of precision occurs in the other direction with
 587     <tt/floatToDouble/, the floating value remains unchanged.
 588 <item>
 589     <tt/showOct/ and <tt/showHex/ will prefix <tt/0o/ and <tt/0x/
 590     respectively. Like <tt/Numeric.showInt/, these show functions
 591     work on positive numbers only.
 592 </itemize>
 593
 594 <sect> <idx/Foreign/
 595 <label id="sec:Foreign">
 596 <p>
 597
 598 This module is provided by GHC but not by Hugs.
 599 GreenCard for Hugs provides the <tt/ForeignObj/ type.
 600
 601 <sect> <idx/Concurrent/
 602 <label id="sec:Concurrent">
 603 <p>
 604
 605 This library provides the Concurrent Haskell extensions
 606 <cite id="concurrentHaskell:popl96">.
 607
 608 We are grateful to the Glasgow Haskell Project for allowing us to
 609 redistribute their implementation of this module.
 610
 611 <tscreen><verb>
 612 module Concurrent where
 613
 614 data ThreadId    -- thread identifiers
 615 instance Eq  ThreadId
 616 instance Ord ThreadId
 617
 618 forkIO           :: IO () -> IO ThreadId
 619 killThread       :: ThreadId -> IO ()
 620
 621 data MVar a      -- Synchronisation variables
 622 newEmptyMVar     :: IO (MVar a)
 623 newMVar          :: a -> IO (MVar a)
 624 takeMVar         :: MVar a -> IO a
 625 putMVar          :: MVar a -> a -> IO ()
 626 swapMVar         :: MVar a -> a -> IO a
 627 readMVar         :: MVar a -> IO a
 628 instance Eq (MVar a)
 629
 630 data Chan a      -- channels
 631 newChan          :: IO (Chan a)
 632 writeChan        :: Chan a -> a -> IO ()
 633 readChan         :: Chan a -> IO a
 634 dupChan          :: Chan a -> IO (Chan a)
 635 unReadChan       :: Chan a -> a -> IO ()
 636 getChanContents  :: Chan a -> IO [a]
 637 writeList2Chan   :: Chan a -> [a] -> IO ()
 638
 639 data CVar a       -- one element channels
 640 newCVar          :: IO (CVar a)
 641 putCVar          :: CVar a -> a -> IO ()
 642 getCVar          :: CVar a -> IO a
 643
 644 data QSem        -- General/quantity semaphores
 645 newQSem          :: Int  -> IO QSem
 646 waitQSem         :: QSem -> IO ()
 647 signalQSem       :: QSem -> IO ()
 648
 649 data QSemN       -- General/quantity semaphores
 650 newQSemN         :: Int   -> IO QSemN
 651 waitQSemN        :: QSemN -> Int -> IO ()
 652 signalQSemN      :: QSemN -> Int -> IO ()
 653
 654 type SampleVar a -- Sample variables
 655 newEmptySampleVar:: IO (SampleVar a)
 656 newSampleVar     :: a -> IO (SampleVar a)
 657 emptySampleVar   :: SampleVar a -> IO ()
 658 readSampleVar    :: SampleVar a -> IO a
 659 writeSampleVar   :: SampleVar a -> a -> IO ()
 660 </verb></tscreen>
 661
 662 Notes:
 663 <itemize>
 664
 665 <item>
 666   GHC uses preemptive multitasking:
 667   Context switches can occur at any time, except if you call a C
 668   function (like \verb"getchar") that blocks waiting for input.
 669
 670   Hugs uses cooperative multitasking:
 671   Context switches only occur when you use one of the primitives
 672   defined in this module.  This means that programs such as:
 673
 674 <tscreen><verb>
 675 main = forkIO (write 'a') >> write 'b'
 676  where write c = putChar c >> write c
 677 </verb></tscreen>
 678
 679   will print either <tt/aaaaaaaaaaaaaa.../ or <tt/bbbbbbbbbbbb.../,
 680   instead of some random interleaving of <tt/a/s and <tt/b/s.
 681
 682   In practice, cooperative multitasking is sufficient for writing
 683   simple graphical user interfaces.
 684
 685 <item>
 686 Hugs does not provide the functions <tt/mergeIO/ or <tt/nmergeIO/ since these
 687 require preemptive multitasking.
 688
 689 <item>
 690 Thread identities and <tt/killThread/ has not been implemented yet on
 691 either system. The plan is that <tt/killThread/ will raise an IO
 692 exception in the killed thread which it can catch --- perhaps allowing -->
 693 --it to kill its children before exiting.
 694
 695 <item>
 696 The <tt/Ord/ instance for <tt/ThreadId/s provides an arbitrary total ordering
 697 which might be used to build an ordered binary tree, say.
 698
 699 </itemize>
 700
 701 <sect> <idx/Pretty/
 702 <label id="sec:Pretty">
 703 <p>
 704
 705 This library contains Simon Peyton Jones' implementation of John
 706 Hughes's pretty printer combinators.
 707
 708 <tscreen><verb>
 709 module Pretty where
 710 infixl 6 <>
 711 infixl 6 <+>
 712 infixl 5 $$, $+$
 713 data Doc  -- the Document datatype
 714
 715 -- The primitive Doc values
 716 empty                     :: Doc
 717 text                      :: String   -> Doc
 718 char                      :: Char     -> Doc
 719 int                       :: Int      -> Doc
 720 integer                   :: Integer  -> Doc
 721 float                     :: Float    -> Doc
 722 double                    :: Double   -> Doc
 723 rational                  :: Rational -> Doc
 724 semi, comma, colon, space, equals              :: Doc
 725 lparen, rparen, lbrack, rbrack, lbrace, rbrace :: Doc
 726 parens, brackets, braces  :: Doc -> Doc
 727 quotes, doubleQuotes      :: Doc -> Doc
 728
 729 -- Combining Doc values
 730 (<>)   :: Doc -> Doc -> Doc     -- Beside
 731 hcat   :: [Doc] -> Doc          -- List version of <>
 732 (<+>)  :: Doc -> Doc -> Doc     -- Beside, separated by space
 733 hsep   :: [Doc] -> Doc          -- List version of <+>
 734 ($$)   :: Doc -> Doc -> Doc     -- Above; if there is no
 735                                   -- overlap it "dovetails" the two
 736 vcat   :: [Doc] -> Doc          -- List version of $$
 737 cat    :: [Doc] -> Doc          -- Either hcat or vcat
 738 sep    :: [Doc] -> Doc          -- Either hsep or vcat
 739 fcat   :: [Doc] -> Doc          -- ``Paragraph fill'' version of cat
 740 fsep   :: [Doc] -> Doc          -- ``Paragraph fill'' version of sep
 741 nest   :: Int -> Doc -> Doc     -- Nested
 742 hang   :: Doc -> Int -> Doc -> Doc
 743 punctuate :: Doc -> [Doc] -> [Doc]
 744 -- punctuate p [d1, ... dn] = [d1 <> p, d2 <> p, ... dn-1 <> p, dn]
 745
 746 -- Displaying Doc values
 747 instance Show Doc
 748 render     :: Doc -> String             -- Uses default style
 749 renderStyle  :: Style -> Doc -> String
 750 data Style = Style { lineLength     :: Int,   -- In chars
 751                        ribbonsPerLine :: Float, -- Ratio of ribbon length
 752                                                 -- to line length
 753                        mode :: Mode
 754                }
 755 data Mode = PageMode            -- Normal
 756             | ZigZagMode          -- With zig-zag cuts
 757             | LeftMode            -- No indentation, infinitely long lines
 758             | OneLineMode         -- All on one line
 759 </verb></tscreen>
 760
 761 <biblio files="refs" style="abbrv">
 762
 763
 764 </article>
 765