X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Flibraries%2Flibs.sgml;h=d5c132d60e9135e09bb7876d015f6aa738393f5f;hb=0cd4f3826fd789d6af23ed115184be43638304a3;hp=4f8b49e15732e7d5a17876baadc28a078c1eca65;hpb=6437de973015efcb9fe52566cfc87db6a89f8c52;p=ghc-hetmet.git diff --git a/ghc/docs/libraries/libs.sgml b/ghc/docs/libraries/libs.sgml index 4f8b49e..d5c132d 100644 --- a/ghc/docs/libraries/libs.sgml +++ b/ghc/docs/libraries/libs.sgml @@ -8,8 +8,9 @@
The Hugs-GHC Extension Libraries -<author>Alastair Reid <tt/reid-alastair@cs.yale.edu/ -<date>v0.7, 21 November 1997 +<author>Alastair Reid <tt/reid-alastair@cs.yale.edu/ + Simon Marlow <tt/simonm@dcs.gla.ac.uk/ +<date>v0.8, 14 December 1997 <abstract> Hugs and GHC provide a common set of libraries to aid portability. This document specifies the interfaces to these libraries and documents @@ -17,28 +18,24 @@ known differences. We hope that these modules will be adopted for inclusion as Standard Haskell Libraries sometime soon. </abstract> -<!-- Commented out the table of contents - ADR <toc> ---> -<sect> <idx/LazyST/ <p> +<sect> <idx/ST/ +<label id="sec:ST"> +<p> -This library provides support for both <em/lazy/ and <em/strict/ state -threads, as described in the PLDI '94 paper by John Launchbury and -Simon Peyton Jones <cite id="LazyStateThreads">. In addition to the -monad <tt/ST/, it also provides mutable variables <tt/STRef/ and -mutable arrays <tt/STArray/. As the name suggests, the monad <tt/ST/ -instance is <em/lazy/. +This library provides support for <em/strict/ state threads, as +described in the PLDI '94 paper by John Launchbury and Simon Peyton +Jones <cite id="LazyStateThreads">. In addition to the monad <tt/ST/, +it also provides mutable variables <tt/STRef/ and mutable arrays +<tt/STArray/. <tscreen><verb> -module LazyST( module LazyST, module Monad ) where +module ST( module ST, module Monad ) where import Monad data ST s a -- abstract type runST :: forall a. (forall s. ST s a) -> a -returnST :: a -> ST s a -thenLazyST :: ST s a -> (a -> ST s b) -> ST s b -thenStrictST :: ST s a -> (a -> ST s b) -> ST s b fixST :: (a -> ST s a) -> ST s a unsafeInterleaveST :: ST s a -> ST s a instance Functor (ST s) @@ -95,23 +92,37 @@ GHC soon. --> <item> -The only difference between the lazy and strict instances of the -<tt/ST/ monad is in their bind operators. The monadic bind operators -<tt/thenLazyST/ and <tt/thenStrictST/ are provided so that you can +Hugs provides <tt/thenLazyST/ and <tt/thenStrictST/ so that you can import <tt/LazyST/ (say) and still use the strict instance in those -places where it matters. GHC also allows you to write <tt/LazyST.>>=/ -and <tt/ST.>>=/ but this is not supported by Hugs yet. - +places where it matters. GHC implements LazyST and ST using different +types, so this isn't possible. +</item> </itemize> -<sect> <idx/ST/ <p> +<sect> <idx/LazyST/ +<label id="sec:LazyST"> +<p> + +This library is identical to <tt/ST/ except that the <tt/ST/ monad +instance is <em/lazy/. The lazy ST monad tends to be more prone to +space leaks than the strict version, so most programmers will use the +former unless laziness is explicitly required. <tt/LazyST/ provides +two additional operations: -This library is identical to <tt/LazyST/ except that the <tt/ST/ monad -instance is <em/strict/. Most programmers use the <em/strict/ instance -to avoid the space leaks associated with the <em/lazy/ instance. +<tscreen> <verb> +lazyToStrictST :: LazyST.ST s a -> ST.ST s a +strictToLazyST :: ST.ST s a -> LazyST.ST s a +</verb> </tscreen> -<sect> <idx/IOExts/ <p> +These are used to convert between lazy and strict state threads. The +semantics with respect to laziness are as you would expect: the strict +state thread passed to <tt/strictToLazyST/ is not performed until the +result of the lazy state thread it returns is demanded. + +<sect> <idx/IOExts/ +<label id="sec:IOExts"> +<p> This library provides the following extensions to the IO monad: <itemize> @@ -225,7 +236,9 @@ unsafePtrEq :: a -> a -> Bool --> -<sect> <idx/Bits/ <p> +<sect> <idx/Bits/ +<label id="sec:Bits"> +<p> This library defines bitwise operations for signed and unsigned ints. @@ -285,13 +298,15 @@ Notes: <tt/bit i/ is the value with the i'th bit set. </itemize> -<sect> <idx/Word/ <p> +<sect> <idx/Word/ +<label id="sec:Word"> +<p> This library provides unsigned integers of various sizes. The types supported are as follows: -<tabular ca="|l|l|"> -type | number of bits @ +<tabular ca="ll"> +type | number of bits @ <hline> Word8 | 8 @ Word16 | 16 @ @@ -378,12 +393,14 @@ Integer). Hugs only provides <tt/Eq/, <tt/Ord/, <tt/Read/ and <tt/Show/ instances for <tt/Word64/ at the moment. -<sect> <idx/Int/ <p> +<sect> <idx/Int/ +<label id="sec:Int"> +<p> This library provides signed integers of various sizes. The types supported are as follows: -<tabular ca="|l|l|l|"> +<tabular ca="ll"> type | number of bits @ <hline> Int8 | 8 @ @@ -430,7 +447,9 @@ ToDo: complete the set of coercion functions. </itemize> -<sect> <idx/Addr/ <p> +<sect> <idx/Addr/ +<label id="sec:Addr"> +<p> This library provides machine addresses and is primarily intended for use in creating foreign function interfaces using GreenCard. @@ -493,12 +512,16 @@ Hugs provides <tt/Addr/ and <tt/nullAddr/ but does not provide any of the index, read or write functions. They can be implemented using GreenCard if required. -<sect> <idx/ForeignObj/ <p> +<sect> <idx/ForeignObj/ +<label id="sec:ForeignObj"> +<p> This module is provided by GHC but not by Hugs. GreenCard for Hugs provides the <tt/ForeignObj/ type. -<sect> <idx/Concurrent/ <p> +<sect> <idx/Concurrent/ +<label id="sec:Concurrent"> +<p> This library provides the Concurrent Haskell extensions <cite id="concurrentHaskell:popl96">. @@ -596,7 +619,9 @@ which might be used to build an ordered binary tree, say. </itemize> -<sect> <idx/Pretty/ <p> +<sect> <idx/Pretty/ +<label id="sec:Pretty"> +<p> This library contains Simon Peyton Jones' implementation of John Hughes's pretty printer combinators.