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.
 332   That is, right shifts fill the top bits with 1 if the  number is negative
 333   and with 0 otherwise.
 334   (Since unsigned types are always positive, the top bit is always filled with
 335   0.)
 336 <item>
 337   Bits are numbered from 0 with bit 0 being the least significant bit.
 338 <item>
 339   <tt/shift x i/ and <tt/rotate x i/ shift to the left if <tt/i/ is
 340   positive and to the right otherwise.
 341 <!--
 342   <item>
 343     <tt/rotate/ is well defined only if bitSize returns a number.
 344     (Maybe we should impose a Bounded constraint on it?)
 345   -->
 346 <item>
 347   <tt/bit i/ is the value with the i'th bit set.
 348 </itemize>
 349
 350 <sect> <idx/Word/
 351 <label id="sec:Word">
 352 <p>
 353
 354 This library provides unsigned integers of various sizes.
 355 The types supported are as follows:
 356
 357 <tabular ca="ll">
 358 type    | number of bits @
 359 <!-- <hline>  -->
 360 Word8    | 8  @
 361 Word16   | 16 @
 362 Word32   | 32 @
 363 Word64   | 64 @
 364 <!-- <hline>  -->
 365 </tabular>
 366
 367 For each type <it/W/ above, we provide the following functions and
 368 instances.  The type <it/I/ refers to the signed integer type of the
 369 same size.
 370
 371 <tscreen><verb>
 372 data W            -- Unsigned Ints
 373 instance Eq       W
 374 instance Ord      W
 375 instance Show     W
 376 instance Read     W
 377 instance Bounded  W
 378 instance Num      W
 379 instance Real     W
 380 instance Integral W
 381 instance Enum     W
 382 instance Ix       W
 383 instance Bits     W
 384 </verb></tscreen>
 385 Plus
 386 <tscreen><verb>
 387 word8ToWord32  :: Word8  -> Word32
 388 word32ToWord8  :: Word32 -> Word8
 389 word16ToWord32 :: Word16 -> Word32
 390 word32ToWord16 :: Word32 -> Word16
 391
 392 word8ToInt     :: Word8  -> Int
 393 intToWord8     :: Int    -> Word8
 394 word16ToInt    :: Word16 -> Int
 395 intToWord16    :: Int    -> Word16
 396 word32ToInt    :: Word32 -> Int
 397 intToWord32    :: Int    -> Word32
 398 </verb></tscreen>
 399
 400 Notes:
 401 <itemize>
 402 <item>
 403   All arithmetic is performed modulo 2^n
 404
 405   One non-obvious consequequence of this is that <tt/negate/
 406   should <em/not/ raise an error on negative arguments.
 407
 408 <item>
 409 The coercion <tt/wToI/ converts an unsigned n-bit value to the
 410 signed n-bit value with the same representation.  For example,
 411 <tt/word8ToInt8 0xff = -1/.
 412 Likewise, <tt/iToW/ converts signed n-bit values to the
 413 corresponding unsigned n-bit value.
 414
 415 <item>
 416 ToDo: complete the set of coercion functions.
 417
 418 <item>
 419 Use <tt/Prelude.fromIntegral :: (Integral a, Num b) => a -> b/ to
 420 coerce between different sizes or to preserve sign when converting
 421 between values of the same size.
 422
 423 <item>
 424 It would be very natural to add a type a type <tt/Natural/ providing
 425 an unbounded size unsigned integer --- just as <tt/Integer/ provides
 426 unbounded size signed integers.  We do not do that yet since there is
 427 no demand for it.  Doing so would require <tt/Bits.bitSize/ to return
 428 <tt/Maybe Int/.
 429
 430 <item>
 431 The <tt/Enum/ instances stop when they reach their upper or lower
 432 bound --- they don't overflow the way the <tt/Int/ and <tt/Float/
 433 instances do.
 434
 435 <item>
 436 It would be useful to provide a function (or a family of functions?)
 437 which coerced between any two Word types (without going through
 438 Integer).
 439
 440 </itemize>
 441
 442 Hugs only provides <tt/Eq/, <tt/Ord/, <tt/Read/ and <tt/Show/
 443 instances for <tt/Word64/ at the moment.
 444
 445 <sect> <idx/Int/
 446 <label id="sec:Int">
 447 <p>
 448
 449 This library provides signed integers of various sizes.  The types
 450 supported are as follows:
 451
 452 <tabular ca="ll">
 453 type    | number of bits @
 454 <!-- <hline>  -->
 455 Int8    | 8  @
 456 Int16   | 16 @
 457 Int32   | 32 @
 458 Int64   | 64 @
 459 <!-- <hline>  -->
 460 </tabular>
 461
 462 For each type <it/I/ above, we provide the following instances.
 463
 464 <tscreen><verb>
 465 data I            -- Signed Ints
 466 iToInt            :: I -> Int  -- not provided for Int64
 467 intToi            :: Int -> I  -- not provided for Int64
 468 instance Eq       I
 469 instance Ord      I
 470 instance Show     I
 471 instance Read     I
 472 instance Bounded  I
 473 instance Num      I
 474 instance Real     I
 475 instance Integral I
 476 instance Enum     I
 477 instance Ix       I
 478 instance Bits     I
 479 </verb></tscreen>
 480 Plus
 481 <tscreen><verb>
 482 int8ToInt  :: Int8  -> Int
 483 intToInt8  :: Int   -> Int8
 484 int16ToInt :: Int16 -> Int
 485 intToInt16 :: Int   -> Int16
 486 int32ToInt :: Int32 -> Int
 487 intToInt32 :: Int   -> Int32
 488 </verb></tscreen>
 489
 490 <itemize>
 491 <item>
 492 Hugs does not provide <tt/Int64/ at the moment.
 493
 494 <item>
 495 ToDo: complete the set of coercion functions.
 496
 497 </itemize>
 498
 499 <sect> <idx/Addr/
 500 <label id="sec:Addr">
 501 <p>
 502
 503 This library provides machine addresses and is primarily intended for
 504 use in creating foreign function interfaces using GreenCard.
 505
 506 <tscreen><verb>
 507 module Addr where
 508 data Addr  -- Address type
 509 instance Eq Addr
 510
 511 nullAddr           :: Addr
 512 plusAddr           :: Addr -> Int -> Addr
 513
 514 -- read value out of _immutable_ memory
 515 indexCharOffAddr   :: Addr -> Int -> Char
 516 indexIntOffAddr    :: Addr -> Int -> Int     -- should we drop this?
 517 indexAddrOffAddr   :: Addr -> Int -> Addr
 518 indexFloatOffAddr  :: Addr -> Int -> Float
 519 indexDoubleOffAddr :: Addr -> Int -> Double
 520 indexWord8OffAddr  :: Addr -> Int -> Word8
 521 indexWord16OffAddr :: Addr -> Int -> Word16
 522 indexWord32OffAddr :: Addr -> Int -> Word32
 523 indexWord64OffAddr :: Addr -> Int -> Word64
 524 indexInt8OffAddr   :: Addr -> Int -> Int8
 525 indexInt16OffAddr  :: Addr -> Int -> Int16
 526 indexInt32OffAddr  :: Addr -> Int -> Int32
 527 indexInt64OffAddr  :: Addr -> Int -> Int64
 528
 529 -- read value out of mutable memory
 530 readCharOffAddr    :: Addr -> Int -> IO Char
 531 readIntOffAddr     :: Addr -> Int -> IO Int  -- should we drop this?
 532 readAddrOffAddr    :: Addr -> Int -> IO Addr
 533 readFloatOffAddr   :: Addr -> Int -> IO Float
 534 readDoubleOffAddr  :: Addr -> Int -> IO Double
 535 readWord8OffAddr   :: Addr -> Int -> IO Word8
 536 readWord16OffAddr  :: Addr -> Int -> IO Word16
 537 readWord32OffAddr  :: Addr -> Int -> IO Word32
 538 readWord64OffAddr  :: Addr -> Int -> IO Word64
 539 readInt8OffAddr    :: Addr -> Int -> IO Int8
 540 readInt16OffAddr   :: Addr -> Int -> IO Int16
 541 readInt32OffAddr   :: Addr -> Int -> IO Int32
 542 readInt64OffAddr   :: Addr -> Int -> IO Int64
 543
 544 -- write value into mutable memory
 545 writeCharOffAddr   :: Addr -> Int -> Char   -> IO ()
 546 writeIntOffAddr    :: Addr -> Int -> Int    -> IO ()  -- should we drop this?
 547 writeAddrOffAddr   :: Addr -> Int -> Addr   -> IO ()
 548 writeFloatOffAddr  :: Addr -> Int -> Float  -> IO ()
 549 writeDoubleOffAddr :: Addr -> Int -> Double -> IO ()
 550 writeWord8OffAddr  :: Addr -> Int -> Word8  -> IO ()
 551 writeWord16OffAddr :: Addr -> Int -> Word16 -> IO ()
 552 writeWord32OffAddr :: Addr -> Int -> Word32 -> IO ()
 553 writeWord64OffAddr :: Addr -> Int -> Word64 -> IO ()
 554 writeInt8OffAddr   :: Addr -> Int -> Int8   -> IO ()
 555 writeInt16OffAddr  :: Addr -> Int -> Int16  -> IO ()
 556 writeInt32OffAddr  :: Addr -> Int -> Int32  -> IO ()
 557 writeInt64OffAddr  :: Addr -> Int -> Int64  -> IO ()
 558 </verb></tscreen>
 559
 560 Hugs provides <tt/Addr/ and <tt/nullAddr/ but does not provide any of
 561 the index, read or write functions.  They can be implemented using
 562 GreenCard if required.
 563
 564 <sect> <idx/NumExts/
 565 <label id="sec:NumExts">
 566 <p>
 567
 568 The <tt/NumExts/ interface collect together various numeric
 569 operations that have proven to be commonly useful
 570
 571 <tscreen> <verb>
 572 -- Going between Doubles and Floats:
 573 doubleToFloat :: Double -> Float
 574 floatToDouble :: Float  -> Double
 575
 576 showHex       :: Integral a => a -> ShowS
 577 showOct       :: Integral a => a -> ShowS
 578 </verb> </tscreen>
 579
 580 Notes:
 581 <itemize>
 582 <item>
 583     If <tt/doubleToFloat/ is applied to a <tt/Double/ that is within
 584     the representable range for <tt/Float/, the result may be the next
 585     higher or lower representable <tt/Float/ value. If the <tt/Double/
 586     is out of range, the result is undefined.
 587 <item>
 588     No loss of precision occurs in the other direction with
 589     <tt/floatToDouble/, the floating value remains unchanged.
 590 <item>
 591     <tt/showOct/ and <tt/showHex/ will prefix <tt/0o/ and <tt/0x/
 592     respectively. Like <tt/Numeric.showInt/, these show functions
 593     work on positive numbers only.
 594 </itemize>
 595
 596 <sect> <idx/Foreign/
 597 <label id="sec:Foreign">
 598 <p>
 599
 600 This module is provided by GHC but not by Hugs.
 601 GreenCard for Hugs provides the <tt/ForeignObj/ type.
 602
 603 <sect> <idx/Concurrent/
 604 <label id="sec:Concurrent">
 605 <p>
 606
 607 This library provides the Concurrent Haskell extensions
 608 <cite id="concurrentHaskell:popl96">.
 609
 610 We are grateful to the Glasgow Haskell Project for allowing us to
 611 redistribute their implementation of this module.
 612
 613 <tscreen><verb>
 614 module Concurrent where
 615
 616 data ThreadId    -- thread identifiers
 617 instance Eq  ThreadId
 618 instance Ord ThreadId
 619
 620 forkIO           :: IO () -> IO ThreadId
 621 killThread       :: ThreadId -> IO ()
 622
 623 data MVar a      -- Synchronisation variables
 624 newEmptyMVar     :: IO (MVar a)
 625 newMVar          :: a -> IO (MVar a)
 626 takeMVar         :: MVar a -> IO a
 627 putMVar          :: MVar a -> a -> IO ()
 628 swapMVar         :: MVar a -> a -> IO a
 629 readMVar         :: MVar a -> IO a
 630 instance Eq (MVar a)
 631
 632 data Chan a      -- channels
 633 newChan          :: IO (Chan a)
 634 writeChan        :: Chan a -> a -> IO ()
 635 readChan         :: Chan a -> IO a
 636 dupChan          :: Chan a -> IO (Chan a)
 637 unReadChan       :: Chan a -> a -> IO ()
 638 getChanContents  :: Chan a -> IO [a]
 639 writeList2Chan   :: Chan a -> [a] -> IO ()
 640
 641 data CVar a       -- one element channels
 642 newCVar          :: IO (CVar a)
 643 putCVar          :: CVar a -> a -> IO ()
 644 getCVar          :: CVar a -> IO a
 645
 646 data QSem        -- General/quantity semaphores
 647 newQSem          :: Int  -> IO QSem
 648 waitQSem         :: QSem -> IO ()
 649 signalQSem       :: QSem -> IO ()
 650
 651 data QSemN       -- General/quantity semaphores
 652 newQSemN         :: Int   -> IO QSemN
 653 waitQSemN        :: QSemN -> Int -> IO ()
 654 signalQSemN      :: QSemN -> Int -> IO ()
 655
 656 type SampleVar a -- Sample variables
 657 newEmptySampleVar:: IO (SampleVar a)
 658 newSampleVar     :: a -> IO (SampleVar a)
 659 emptySampleVar   :: SampleVar a -> IO ()
 660 readSampleVar    :: SampleVar a -> IO a
 661 writeSampleVar   :: SampleVar a -> a -> IO ()
 662 </verb></tscreen>
 663
 664 Notes:
 665 <itemize>
 666
 667 <item>
 668   GHC uses preemptive multitasking:
 669   Context switches can occur at any time, except if you call a C
 670   function (like \verb"getchar") that blocks waiting for input.
 671
 672   Hugs uses cooperative multitasking:
 673   Context switches only occur when you use one of the primitives
 674   defined in this module.  This means that programs such as:
 675
 676 <tscreen><verb>
 677 main = forkIO (write 'a') >> write 'b'
 678  where write c = putChar c >> write c
 679 </verb></tscreen>
 680
 681   will print either <tt/aaaaaaaaaaaaaa.../ or <tt/bbbbbbbbbbbb.../,
 682   instead of some random interleaving of <tt/a/s and <tt/b/s.
 683
 684   In practice, cooperative multitasking is sufficient for writing
 685   simple graphical user interfaces.
 686
 687 <item>
 688 Hugs does not provide the functions <tt/mergeIO/ or <tt/nmergeIO/ since these
 689 require preemptive multitasking.
 690
 691 <item>
 692 Thread identities and <tt/killThread/ has not been implemented yet on
 693 either system. The plan is that <tt/killThread/ will raise an IO
 694 exception in the killed thread which it can catch --- perhaps allowing -->
 695 --it to kill its children before exiting.
 696
 697 <item>
 698 The <tt/Ord/ instance for <tt/ThreadId/s provides an arbitrary total ordering
 699 which might be used to build an ordered binary tree, say.
 700
 701 </itemize>
 702
 703 <sect> <idx/Pretty/
 704 <label id="sec:Pretty">
 705 <p>
 706
 707 This library contains Simon Peyton Jones' implementation of John
 708 Hughes's pretty printer combinators.
 709
 710 <tscreen><verb>
 711 module Pretty where
 712 infixl 6 <>
 713 infixl 6 <+>
 714 infixl 5 $$, $+$
 715 data Doc  -- the Document datatype
 716
 717 -- The primitive Doc values
 718 empty                     :: Doc
 719 text                      :: String   -> Doc
 720 char                      :: Char     -> Doc
 721 int                       :: Int      -> Doc
 722 integer                   :: Integer  -> Doc
 723 float                     :: Float    -> Doc
 724 double                    :: Double   -> Doc
 725 rational                  :: Rational -> Doc
 726 semi, comma, colon, space, equals              :: Doc
 727 lparen, rparen, lbrack, rbrack, lbrace, rbrace :: Doc
 728 parens, brackets, braces  :: Doc -> Doc
 729 quotes, doubleQuotes      :: Doc -> Doc
 730
 731 -- Combining Doc values
 732 (<>)   :: Doc -> Doc -> Doc     -- Beside
 733 hcat   :: [Doc] -> Doc          -- List version of <>
 734 (<+>)  :: Doc -> Doc -> Doc     -- Beside, separated by space
 735 hsep   :: [Doc] -> Doc          -- List version of <+>
 736 ($$)   :: Doc -> Doc -> Doc     -- Above; if there is no
 737                                   -- overlap it "dovetails" the two
 738 vcat   :: [Doc] -> Doc          -- List version of $$
 739 cat    :: [Doc] -> Doc          -- Either hcat or vcat
 740 sep    :: [Doc] -> Doc          -- Either hsep or vcat
 741 fcat   :: [Doc] -> Doc          -- ``Paragraph fill'' version of cat
 742 fsep   :: [Doc] -> Doc          -- ``Paragraph fill'' version of sep
 743 nest   :: Int -> Doc -> Doc     -- Nested
 744 hang   :: Doc -> Int -> Doc -> Doc
 745 punctuate :: Doc -> [Doc] -> [Doc]
 746 -- punctuate p [d1, ... dn] = [d1 <> p, d2 <> p, ... dn-1 <> p, dn]
 747
 748 -- Displaying Doc values
 749 instance Show Doc
 750 render     :: Doc -> String             -- Uses default style
 751 renderStyle  :: Style -> Doc -> String
 752 data Style = Style { lineLength     :: Int,   -- In chars
 753                        ribbonsPerLine :: Float, -- Ratio of ribbon length
 754                                                 -- to line length
 755                        mode :: Mode
 756                }
 757 data Mode = PageMode            -- Normal
 758             | ZigZagMode          -- With zig-zag cuts
 759             | LeftMode            -- No indentation, infinitely long lines
 760             | OneLineMode         -- All on one line
 761 </verb></tscreen>
 762
 763 <biblio files="refs" style="abbrv">
 764
 765
 766 </article>
 767