Misc doc-fixes and updates.
module Addr where
data Addr -- Address type
instance Eq Addr
+instance Ord Addr
nullAddr :: Addr
plusAddr :: Addr -> Int -> Addr
-- read value out of _immutable_ memory
indexCharOffAddr :: Addr -> Int -> Char
-indexIntOffAddr :: Addr -> Int -> Int -- should we drop this?
+indexIntOffAddr :: Addr -> Int -> Int
indexAddrOffAddr :: Addr -> Int -> Addr
indexFloatOffAddr :: Addr -> Int -> Float
indexDoubleOffAddr :: Addr -> Int -> Double
-- read value out of mutable memory
readCharOffAddr :: Addr -> Int -> IO Char
-readIntOffAddr :: Addr -> Int -> IO Int -- should we drop this?
+readIntOffAddr :: Addr -> Int -> IO Int
readAddrOffAddr :: Addr -> Int -> IO Addr
readFloatOffAddr :: Addr -> Int -> IO Float
readDoubleOffAddr :: Addr -> Int -> IO Double
-- write value into mutable memory
writeCharOffAddr :: Addr -> Int -> Char -> IO ()
-writeIntOffAddr :: Addr -> Int -> Int -> IO () -- should we drop this?
+writeIntOffAddr :: Addr -> Int -> Int -> IO ()
writeAddrOffAddr :: Addr -> Int -> Addr -> IO ()
writeForeignObjOffAddr :: Addr -> Int -> ForeignObj -> IO ()
writeFloatOffAddr :: Addr -> Int -> Float -> IO ()
Please notice that the Boolean value returned from <tt/isEmptyMVar/
represent just a snapshot of the state of the <tt/MVar/. By the
time a thread gets to inspect the result and act upon it, other
-threads may have accessed the <tt/MVar/ and changed its 'filled-in'
-status of the variable. Please be wary of this.
+threads may have accessed the <tt/MVar/ and changed the 'filled-in'
+status of the variable.
</itemize>
abstract type <tt/Dynamic/. Values can be converted into <tt/Dynamic/
ones, which can then be combined and manipulated by the program using
the operations provided over the abstract, dynamic type. One of
-these operations allows you to convert a dynamically-typed value back
-into a value with the same (monomorphic) type it had before converting
-it into a dynamically-typed value.
+these operations allows you to (try to) convert a dynamically-typed
+value back into a value with the same (monomorphic) type it had before
+converting it into a dynamically-typed value. If the dynamically-typed
+value isn't of the desired type, the coercion will fail.
The <tt/Dynamic/ library is capable of dealing with monomorphic types
only; no support for polymorphic dynamic values, but hopefully that
-can be added at a later stage.
+will be added at a later stage.
Examples where this library may come in handy (dynamic types, really -
hopefully the library provided here will suffice) are: persistent
form.
</itemize>
-<sect1>The <tt/Typeable/ class
+<sect1><idx>The Typeable class</idx>
<nidx>Typeable class</nidx>
<label id="sec:Dynamic:Typeable">
<p>
--- /dev/null
+ <sect> <idx/Foreign/
+<label id="sec:Foreign">
+<p>
+
+This module provides two types to better allow the Haskell world to
+share its data with the outside world (and vice versa), <em/foreign
+objects/ and <em/stable pointers/:
+
+<tscreen><verb>
+module Foreign where
+data ForeignObj -- abstract, instance of: Eq
+
+makeForeignObj :: Addr{-object-} -> Addr{-finaliser-} -> IO ForeignObj
+writeForeignObj :: ForeignObj -> Addr{-new value-} -> IO ()
+
+data StablePtr a -- abstract, instance of: Eq.
+makeStablePtr :: a -> IO (StablePtr a)
+deRefStablePtr :: StablePtr a -> IO a
+freeStablePtr :: StablePtr a -> IO ()
+</verb> </tscreen>
+
+<itemize>
+<item>The <tt/ForeignObj/ type provides foreign objects, encapsulated
+references to values outside the Haskell heap. Foreign objects are
+finalised by the garbage collector when they become dead. The
+finaliser to use is given as second argument to <tt/makeForeignOj/,
+and is currently a function pointer to a C function with
+the following signature
+
+<tscreen><verb>
+void finaliseFO(void* obj);
+</verb></tscreen>
+
+The finaliser is passed the reference to the external object (i.e.,
+the first argument to <tt/makeForeignObj/.)
+
+<item>
+The <tt/writeForeignObj/ lets you overwrite the encapsulated foreign
+reference with another.
+
+<item>
+Stable pointers allow you to hand out references to Haskell heap
+objects to the outside world. <bf/ToDo:/ <em/say more./
+</itemize>
+
+In addition to the above, the following operations for indexing via
+a <tt/ForeignObj/ are also, mirrored on the same operations provided
+over <tt/Addr/s:
+
+<tscreen><verb>
+indexCharOffForeignObj :: ForeignObj -> Int -> Char
+indexIntOffForeignObj :: ForeignObj -> Int -> Int
+indexAddrOffForeignObj :: ForeignObj -> Int -> Addr
+indexFloatOffForeignObj :: ForeignObj -> Int -> Float
+indexDoubleOffForeignObj :: ForeignObj -> Int -> Double
+indexWord8OffForeignObj :: ForeignObj -> Int -> Word8
+indexWord16OffForeignObj :: ForeignObj -> Int -> Word16
+indexWord32OffForeignObj :: ForeignObj -> Int -> Word32
+indexWord64OffForeignObj :: ForeignObj -> Int -> Word64
+
+indexInt8OffForeignObj :: ForeignObj -> Int -> Int8
+indexInt16OffForeignObj :: ForeignObj -> Int -> Int16
+indexInt32OffForeignObj :: ForeignObj -> Int -> Int32
+indexInt64OffForeignObj :: ForeignObj -> Int -> Int64
+
+-- read value out of mutable memory
+readCharOffForeignObj :: ForeignObj -> Int -> IO Char
+readIntOffForeignObj :: ForeignObj -> Int -> IO Int
+readAddrOffForeignObj :: ForeignObj -> Int -> IO Addr
+readFloatOffForeignObj :: ForeignObj -> Int -> IO Float
+readDoubleOffForeignObj :: ForeignObj -> Int -> IO Double
+readWord8OffForeignObj :: ForeignObj -> Int -> IO Word8
+readWord16OffForeignObj :: ForeignObj -> Int -> IO Word16
+readWord32OffForeignObj :: ForeignObj -> Int -> IO Word32
+readWord64OffForeignObj :: ForeignObj -> Int -> IO Word64
+readInt8OffForeignObj :: ForeignObj -> Int -> IO Int8
+readInt16OffForeignObj :: ForeignObj -> Int -> IO Int16
+readInt32OffForeignObj :: ForeignObj -> Int -> IO Int32
+readInt64OffForeignObj :: ForeignObj -> Int -> IO Int64
+
+writeCharOffForeignObj :: ForeignObj -> Int -> Char -> IO ()
+writeIntOffForeignObj :: ForeignObj -> Int -> Int -> IO ()
+writeAddrOffForeignObj :: ForeignObj -> Int -> Addr -> IO ()
+writeFloatOffForeignObj :: ForeignObj -> Int -> Float -> IO ()
+writeDoubleOffForeignObj :: ForeignObj -> Int -> Double -> IO ()
+writeWord8OffForeignObj :: ForeignObj -> Int -> Word8 -> IO ()
+writeWord16OffForeignObj :: ForeignObj -> Int -> Word16 -> IO ()
+writeWord32OffForeignObj :: ForeignObj -> Int -> Word32 -> IO ()
+writeWord64OffForeignObj :: ForeignObj -> Int -> Word64 -> IO ()
+writeInt8OffForeignObj :: ForeignObj -> Int -> Int8 -> IO ()
+writeInt16OffForeignObj :: ForeignObj -> Int -> Int16 -> IO ()
+writeInt32OffForeignObj :: ForeignObj -> Int -> Int32 -> IO ()
+writeInt64OffForeignObj :: ForeignObj -> Int -> Int64 -> IO ()
+</verb></tscreen>
+
<tt/performGC/ triggers an immediate garbage collection
<item>
-When called, <tt/trace/ prints the string in its first argument, and then
-returns the second argument as its result. The <tt/trace/ function is not
-referentially transparent, and should only be used for debugging, or for
-monitoring execution.
+When called, <tt/trace/ prints the string in its first argument to
+standard error, before returning the second argument as its result.
+The <tt/trace/ function is not referentially transparent, and should
+only be used for debugging, or for monitoring execution. Some
+implementations of <tt/trace/ may decorate the string that's output
+to indicate that you're tracing.
<!--
You should also be warned that, unless you understand some of the
<item>
Operations for coercing an <tt/ST/ action into an <tt/IO/ one, and
-vice versa are also provided. Notice that coercing an <tt/IO action
+vice versa are also provided. Notice that coercing an <tt/IO/ action
into an <tt/ST/ action is 'lossy', since any exception raised within the
<tt/IO/ action will not be caught within the <tt/ST/ monad, as it
doesn't support (monadic) exceptions.
<tscreen><verb>
data I -- Signed Ints
iToInt :: I -> Int -- not provided for Int64
-intToi :: Int -> I -- not provided for Int64
+intToI :: Int -> I -- not provided for Int64
instance Eq I
instance Ord I
instance Show I
showHex :: Integral a => a -> ShowS
showOct :: Integral a => a -> ShowS
+showBin :: Integral a => a -> ShowS
+
+showIntAtBase :: Integral a
+ => a -- base
+ -> (a -> Char) -- digit to char
+ -> a -- number to show.
+ -> ShowS
</verb> </tscreen>
Notes:
No loss of precision occurs in the other direction with
<tt/floatToDouble/, the floating value remains unchanged.
<item>
- <tt/showOct/ and <tt/showHex/ will prefix <tt/0o/ and <tt/0x/
- respectively. Like <tt/Numeric.showInt/, these show functions
- work on positive numbers only.
+ <tt/showOct/, <tt/showHex/ and <tt/showBin/ will prefix <tt/0o/,
+ <tt/0x/ and <tt/0b/, respectively. Like <tt/Numeric.showInt/,
+ these show functions work on positive numbers only.
+<item>
+ <tt/showIntAtBase/ is the more general function for converting
+ a number at some base into a series of characters. The above
+ <tt/show*/ functions use it, for instance, here's how <tt/showHex/
+ could be defined
+
+<tscreen><verb>
+
+</verb></tscreen>
+showHex :: Integral a => a -> ShowS
+showHex n r =
+ showString "0x" $
+ showIntAtBase 16 (toChrHex) n r
+ where
+ toChrHex d
+ | d < 10 = chr (ord '0' + fromIntegral d)
+ | otherwise = chr (ord 'a' + fromIntegral (d - 10))
</itemize>
<item>
All arithmetic is performed modulo 2^n
- One non-obvious consequequence of this is that <tt/negate/
+ One non-obvious consequence of this is that <tt/negate/
should <em/not/ raise an error on negative arguments.
<item>
<!ENTITY concurrent SYSTEM "Concurrent.sgml">
<!ENTITY dynamic SYSTEM "Dynamic.sgml">
<!ENTITY exception SYSTEM "Exception.sgml">
+ <!ENTITY foreign SYSTEM "Foreign.sgml">
<!ENTITY glaexts SYSTEM "GlaExts.sgml">
<!ENTITY ioexts SYSTEM "IOExts.sgml">
<!ENTITY int SYSTEM "Int.sgml">
<article>
<title>The Hugs-GHC Extension Libraries
-<author>Alastair Reid <tt/reid-alastair@cs.yale.edu/
- Simon Marlow <tt/simonm@dcs.gla.ac.uk/
-<date>v0.8, 28 January 1998
+<author>The Hugs/GHC Team
+<date>January 1999
<abstract>
Hugs and GHC provide a common set of libraries to aid portability.
This document specifies the interfaces to these libraries and documents
-known differences. We hope that these modules will be adopted for inclusion
-as Standard Haskell Libraries sometime soon.
+known differences.
</abstract>
<toc>
&concurrent
&dynamic
&exception
-
-<sect> <idx/Foreign/
-<label id="sec:Foreign">
-<p>
-This module is provided by GHC but not by Hugs.
-GreenCard for Hugs provides the <tt/ForeignObj/ type.
-
+&foreign
&glaexts
&ioexts
&int
+&numexts
+&pretty
+&st
+
<sect> <idx/LazyST/
<label id="sec:LazyST">
<p>
state thread passed to <tt/strictToLazyST/ is not performed until the
result of the lazy state thread it returns is demanded.
-&numexts
-&pretty
-&st
&weak
&word
projects / ghc-hetmet.git / commitdiff