ghc/docs/libraries/libs.sgml

   1 <!doctype linuxdoc system [
   2   <!ENTITY addr       SYSTEM "Addr.sgml">
   3   <!ENTITY bits       SYSTEM "Bits.sgml">
   4   <!ENTITY concurrent SYSTEM "Concurrent.sgml">
   5   <!ENTITY dynamic    SYSTEM "Dynamic.sgml">
   6   <!ENTITY exception  SYSTEM "Exception.sgml">
   7   <!ENTITY glaexts    SYSTEM "GlaExts.sgml">
   8   <!ENTITY ioexts     SYSTEM "IOExts.sgml">
   9   <!ENTITY int        SYSTEM "Int.sgml">
  10   <!ENTITY ndset      SYSTEM "NDSet.sgml">
  11   <!ENTITY numexts    SYSTEM "NumExts.sgml">
  12   <!ENTITY pretty     SYSTEM "Pretty.sgml">
  13   <!ENTITY st         SYSTEM "ST.sgml">
  14   <!ENTITY weak       SYSTEM "Weak.sgml">
  15   <!ENTITY word       SYSTEM "Word.sgml">
  16 ]>
  17
  18 <!-- ToDo:
  19   o Add indexing support (to linuxdoc)
  20   o Fix citations in html
  21   -->
  22
  23 <article>
  24
  25 <title>The Hugs-GHC Extension Libraries
  26 <author>Alastair Reid <tt/reid-alastair@cs.yale.edu/
  27         Simon Marlow <tt/simonm@dcs.gla.ac.uk/
  28 <date>v0.8, 28 January 1998
  29 <abstract>
  30 Hugs and GHC provide a common set of libraries to aid portability.
  31 This document specifies the interfaces to these libraries and documents
  32 known differences.  We hope that these modules will be adopted for inclusion
  33 as Standard Haskell Libraries sometime soon.
  34 </abstract>
  35
  36 <toc>
  37
  38 <sect> <idx/Naming conventions/
  39 <label id="sec:Naming conventions">
  40 <p>
  41
  42 The set of interfaces specified in this document try to adhere to the
  43 following naming conventions:
  44
  45 <itemize>
  46 <item>
  47 Actions that create a new values have the prefix <tt/new/ followed by
  48 the name of the type of object they're creating, e.g., <tt/newIORef/,
  49 <tt/newChan/ etc.
  50 <item>
  51 Operations that read a value from a mutable object are prefixed with
  52 <tt/read/, and operations that update the contents have the prefix
  53 <tt/write/, e.g., <tt/readChan/, <tt/readIOArray/.
  54
  55 Notes:
  56 <itemize>
  57 <item>
  58 This differs from the convention used to name the operations for
  59 reading and writing to a file <tt/Handle/, where <tt/get/ and <tt/put/
  60 are used instead.
  61 <item>
  62 Operations provided by various concurrency abstractions, e.g., <tt/MVar/,
  63 <tt/CVar/ , also deviate from this naming scheme. This is perhaps
  64 defensible, since the read and write operations have additional
  65 behaviour, e.g., <tt/takeMVar/ tries to read the current value
  66 of an <tt/MVar/, locking it if it succeeds.
  67 </itemize>
  68 <item>
  69 Conversions operators have the form <tt/AToB/ where <tt/A/ and <tt/B/
  70 are the types we're converting between.
  71 <item>
  72 Operations that lazily read values from a mutable object/handle, have
  73 the form <tt/getXContents/, e.g., <tt/Channel.getChanContents/ and
  74 <tt/IO.hGetContents/. (OK, so the latter isn't called
  75 <tt/getHandleContents/, but you hopefully get the picture.)
  76 </itemize>
  77
  78 <!-- ========================= -->
  79
  80 &addr
  81 &bits
  82 &concurrent
  83 &dynamic
  84 &exception
  85
  86 <sect> <idx/Foreign/
  87 <label id="sec:Foreign">
  88 <p>
  89 This module is provided by GHC but not by Hugs.
  90 GreenCard for Hugs provides the <tt/ForeignObj/ type.
  91
  92 &glaexts
  93 &ioexts
  94 &int
  95
  96 <sect> <idx/LazyST/
  97 <label id="sec:LazyST">
  98 <p>
  99
 100 This library is identical to <tt/ST/ except that the <tt/ST/ monad
 101 instance is <em/lazy/.  The lazy ST monad tends to be more prone to
 102 space leaks than the strict version, so most programmers will use the
 103 former unless laziness is explicitly required.  <tt/LazyST/ provides
 104 two additional operations:
 105
 106 <tscreen> <verb>
 107 lazyToStrictST :: LazyST.ST s a -> ST.ST s a
 108 strictToLazyST :: ST.ST s a -> LazyST.ST s a
 109 </verb> </tscreen>
 110
 111 These are used to convert between lazy and strict state threads.  The
 112 semantics with respect to laziness are as you would expect: the strict
 113 state thread passed to <tt/strictToLazyST/ is not performed until the
 114 result of the lazy state thread it returns is demanded.
 115
 116 &numexts
 117 &pretty
 118 &st
 119 &weak
 120 &word
 121
 122 <!-- ========================= -->
 123
 124 <biblio files="refs" style="abbrv">
 125
 126
 127 </article>
 128