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 foreign    SYSTEM "Foreign.sgml">
   8   <!ENTITY glaexts    SYSTEM "GlaExts.sgml">
   9   <!ENTITY getopt     SYSTEM "GetOpt.sgml">
  10   <!ENTITY ioexts     SYSTEM "IOExts.sgml">
  11   <!ENTITY int        SYSTEM "Int.sgml">
  12   <!ENTITY ndset      SYSTEM "NDSet.sgml">
  13   <!ENTITY numexts    SYSTEM "NumExts.sgml">
  14   <!ENTITY pretty     SYSTEM "Pretty.sgml">
  15   <!ENTITY st         SYSTEM "ST.sgml">
  16   <!ENTITY weak       SYSTEM "Weak.sgml">
  17   <!ENTITY word       SYSTEM "Word.sgml">
  18 ]>
  19
  20 <!-- ToDo:
  21   o Add indexing support (to linuxdoc)
  22   o Fix citations in html
  23   -->
  24
  25 <article>
  26
  27 <title>The Hugs-GHC Extension Libraries
  28 <author>The Hugs/GHC Team
  29 <date>January 1999
  30 <abstract>
  31 Hugs and GHC provide a common set of libraries to aid portability.
  32 This document specifies the interfaces to these libraries and documents
  33 known differences.
  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 &foreign
  86 &glaexts
  87 &ioexts
  88 &int
  89
  90 &numexts
  91 &pretty
  92 &getopt
  93 &st
  94
  95 <sect> <idx/LazyST/
  96 <label id="sec:LazyST">
  97 <p>
  98
  99 This library is identical to <tt/ST/ except that the <tt/ST/ monad
 100 instance is <em/lazy/.  The lazy ST monad tends to be more prone to
 101 space leaks than the strict version, so most programmers will use the
 102 former unless laziness is explicitly required.  <tt/LazyST/ provides
 103 two additional operations:
 104
 105 <tscreen> <verb>
 106 lazyToStrictST :: LazyST.ST s a -> ST.ST s a
 107 strictToLazyST :: ST.ST s a -> LazyST.ST s a
 108 </verb> </tscreen>
 109
 110 These are used to convert between lazy and strict state threads.  The
 111 semantics with respect to laziness are as you would expect: the strict
 112 state thread passed to <tt/strictToLazyST/ is not performed until the
 113 result of the lazy state thread it returns is demanded.
 114
 115 &weak
 116 &word
 117
 118 <!-- ========================= -->
 119
 120 <biblio files="refs" style="abbrv">
 121
 122
 123 </article>
 124