%************************************************************************
%* *
\subsection[options-C-compiler]{Options affecting the C compiler (if applicable)}
+\index{include-file-option}
\index{C compiler options}
\index{GCC options}
-\index{include file option}
%* *
%************************************************************************
Sometimes it is useful to make the connection between a source file
and the command-line options it requires, quite tight. For instance,
if a (Glasgow) Haskell source file uses \tr{casm}s, the C back-end
-often needs to be told about header files to use,
-\ref{include file option}. Rather than maintaining the list of
-files the source depends on in a \tr{Makefile}, it is possible to
-do this directly in the source file using the \tr{OPTIONS} pragma
-\index{OPTIONS pragma}:
+often needs to be told about header files to use. Rather than
+maintaining the list of files the source depends on in a
+\tr{Makefile} (using \tr{-#include} option), it is possible to do this
+directly in the source file using the \tr{OPTIONS} pragma
+\index{OPTIONS pragma}:
\begin{verbatim}
{-# OPTIONS -#include "foo.h" #-}
To make sure you get the syntax right, tailoring an existing interface
file is a Good Idea.
-\bf{Note:} This is all a temporary solution, a version of the compiler
+{\bf Note:} This is all a temporary solution, a version of the compiler
that handles mutually recursive properly without the manual
construction of interface file, is in the works.
-
%----------------------------------------------------------------------
%\subsubsection[arity-checking]{Options to insert arity-checking code}
%\index{arity checking}
negateInt# :: Int# -> Int#
\end{verbatim}
-\bf{Note:} No error/overflow checking!
+{\bf Note:} No error/overflow checking!
\subsubsubsection{Unboxed-@Double@ and @Float@ operations}
\begin{verbatim}
We implement @Integers@ (arbitrary-precision integers) using the GNU
multiple-precision (GMP) package (version 1.3.2).
-\bf{Note:} some of this might change when we upgrade to using GMP~2.x.
+{\bf Note:} some of this might change when we upgrade to using GMP~2.x.
The data type for @Integer@ must mirror that for @MP_INT@ in @gmp.h@
(see @gmp.info@ in \tr{ghc/includes/runtime/gmp}). It comes out as:
There is also a C procedure @FreeStablePtr@ which frees a stable pointer.
-%{\em Andy's comment.} \bf{Errors:} The following is not strictly true: the current
+%{\em Andy's comment.} {\bf Errors:} The following is not strictly true: the current
%implementation is not as polymorphic as claimed. The reason for this
%is that the C programmer will have to use a different entry-routine
%for each type of stable pointer. At present, we only supply a very
%arguments and to enter (stable pointers to) boxed primitive values.
%{\em End of Andy's comment.}
-
%
% Rewritten and updated for MallocPtr++ -- 4/96 SOF
%
-> StateAndForeignObj# RealWorld ForeignObj#
\end{verbatim}
-\bf{Note:} the foreign object value and its finaliser are contained
+{\bf Note:} the foreign object value and its finaliser are contained
in the primitive value @ForeignObj#@, so there's no danger of an
aggressive optimiser somehow separating the two. (with the result
that the foreign reference would not be freed).
%a GC too? Is there any need for a function that provides finer
%control over GC: argument = amount of space required; result = amount
%of space recovered.
+=======
+The C function {\tt PerformGC\/}, allows the C world to force Haskell
+to do a garbage collection. It can only be called while Haskell is
+performing a C Call.
+
+Note that this function can be used to define a Haskell IO operation
+with the same effect:
+\begin{verbatim}
+> performGCIO :: PrimIO ()
+> performGCIO = _ccall_gc_ PerformGC
+\end{verbatim}
+
+{\bf ToDo:} Is there any need for abnormal/normal termination to force
+a GC too? Is there any need for a function that provides finer
+control over GC: argument = amount of space required; result = amount
+of space recovered.
\subsection{@spark#@ primitive operation (for parallel execution)}
\subsection{C Calls}
-\bf{ToDo:} current implementation has state variable as second
+{\bf ToDo:} current implementation has state variable as second
argument not last argument.
The @ccall#@ primitive can't be given an ordinary type, because it has
\end{verbatim}
-\bf{Note:} all the derived operators over @ST@ are implemented using
+{\bf Note:} all the derived operators over @ST@ are implemented using
the {\em strict} @ST@ instance of @Monad@.
\subsubsection{The @PrimIO@ monad}
Everything in this section goes for @_casm_@ too.
-\bf{ToDo:} {\em mention @_ccall_gc_@ and @_casm_gc_@...}
+{\bf ToDo:} {\em mention @_ccall_gc_@ and @_casm_gc_@...}
The @_ccall_@ construct has the following form:
$$@_ccall_@~croutine~a_1~\ldots~a_n$$
Array, ByteArray, MutableArray, MutableByteArray, ForeignObj
\end{verbatim}
-\bf{ToDo:} I'm pretty wary of @Array@ and @MutableArray@ being in
+{\bf ToDo:} I'm pretty wary of @Array@ and @MutableArray@ being in
this list, and not too happy about @State@ [WDP].
-\bf{ToDo:} Can code generator pass all the primitive types? Should this be
+{\bf ToDo:} Can code generator pass all the primitive types? Should this be
extended to include {\tt Bool\/} (or any enumeration type?)
The type checker must be able to figure out just which of the C-callable/returnable
make one wait:\index{delay a concurrent thread}
\index{wait for a file descriptor}
\begin{verbatim}
-threadDelay :: Int -> IO () -- delay rescheduling for N microseconds
-threadWait :: Int -> IO () -- wait for input on specified file descriptor
+threadDelay :: Int -> IO () -- delay rescheduling for N microseconds
+threadWaitRead :: Int -> IO () -- wait for input on specified file descriptor
+threadWaitWrite :: Int -> IO () -- (read and write, respectively).
\end{verbatim}
%************************************************************************
\item The GHC system library - collection of interfaces that mainly
have grown out of abstractions used to implement GHC itself.
\item Parts of the HBC libraries.
-\item The Posix interface - a quality interface to OS functionality as
-specified by {\tt POSIX 1003.1}. Sadly, this library hasn't made it
-into a standard Haskell library.
+\item The Posix interface - a mostly complete interface to OS functionality as
+specified by {\tt POSIX 1003.1}. Sadly, this library isn't a standard
+Haskell library...yet.
\item The contrib libraries - oodles of numeric codes..
\end{itemize}
%* *
%************************************************************************
-You need to \tr{import PackedString} and heave in your \tr{-syslib
-ghc} to use \tr{PackedString}s.
+You need to \tr{import PackedString} and heave in your
+\tr{-syslib ghc} to use \tr{PackedString}s.
The basic type and functions available are:
\begin{verbatim}
\end{verbatim}
Various examples of networking Haskell code are provided in
-\tr{ghc/misc/examples/}, notably the \tr{net???/Main.hs} programs.
+%\tr{ghc/misc/examples/}, notably the \tr{net???/Main.hs} programs.
%************************************************************************
%* *
The @Posix@ interface gives you access to the set of OS services
standardised by POSIX 1003.1b (or the {\em IEEE Portable Operating System
Interface for Computing Environments} - IEEE Std. 1003.1). The
-interface is accessed by \tr{import Posix} and adding \tr{-syslib
-posix} on your command-line.
+interface is accessed by \tr{import Posix} and adding
+\tr{-syslib posix} on your command-line.
-\subsubsection[Posix-data-types]{Posix data types}
+\subsubsection[Posix data types]{Posix data types}
\index{Posix, data types}
be an arithmetic type.
\begin{verbatim}
-> data EpochTime -- instances of : Eq Ord Num Real Integral Ix Enum Show
+data EpochTime -- instances of : Eq Ord Num Real Integral Ix Enum Show
\end{verbatim}
A \tr{EpochTime} is a primitive of type \tr{time_t}, which is
deriving (Eq, Show)
\end{verbatim}
-\subsubsection{posix-process-env}{Posix Process Primitives}
+\subsubsection[Process Primitives]{Posix Process Primitives}
\begin{verbatim}
forkProcess :: IO (Maybe ProcessID)
\end{verbatim}
\tr{forkProcess} calls \tr{fork}, returning
-\tr{Just pid} to the parent, where <var>pid</var> is the
+\tr{Just pid} to the parent, where \tr{pid} is the
ProcessID of the child, and returning \tr{Nothing} to the
child.
\tr{installHandler int handler iset} calls \tr{sigaction} to install
an interrupt handler for signal \tr{int}. If \tr{handler} is
\tr{Default}, \tr{SIG_DFL} is installed; if \tr{handler} is
-\tr{Ignore}, \tr{SIG_IGN} is installed; if \tr{handler} is \tr{Catch
-action}, a handler is installed which will invoke \tr{action} as a
+\tr{Ignore}, \tr{SIG_IGN} is installed; if \tr{handler} is
+\tr{Catch action}, a handler is installed which will invoke \tr{action} as a
replacement for \tr{main}. If \tr{iset} is \tr{Just s}, then the
\tr{sa_mask} of the \tr{sigaction} structure is set to \tr{s};
otherwise it is cleared. The previously installed signal handler for
program until at least \tr{i} seconds have elapsed or a signal is
received.
-\subsubsection[posix-proc-env]{Posix Process Environment}
+\subsubsection[Process Environment]{Posix Process Environment}
\index{Posix, process environment}
\begin{verbatim}
The requested system limit or option is undefined.
\end{itemize}
-\subsubsection[posix-files-dir]{Files and Directories}
+\subsubsection[Files and Directories]{Posix operations on files and directories}
\index{Posix, files and directories}
\begin{verbatim}
Various other causes.
\end{itemize}
-\subsubsection[posix-input-output]{Posix Input and Output Primitives}
+\subsubsection[Inut Output]{Posix Input and Output Primitives}
\index{Posix, input/output}
\begin{verbatim}
indicated by \tr{whence}. It returns the resulting offset from the
start of the file in bytes.
-\subsubsection[posix-device-class]{Posix, Device- and Class-Specific Functions}
+\subsubsection[Device Specific Functions]{Posix, Device- and Class-Specific Functions}
\index{Posix, device and class-specific functions}
\begin{verbatim}
associated with the terminal attached to \tr{Channel}
\tr{fd} to \tr{pgid}.
-\subsubsection[posix-system-db]{Posix System Databases}
+\subsubsection[System Database]{Posix System Databases}
\index{Posix, system databases}
\begin{verbatim}
There is no user entry for the name.
\end{itemize}
-\subsubsection[posix-errors]{POSIX Errors}
+\subsubsection[Error reporting and handling]{POSIX Errors}
\index{Posix, errors}
\begin{verbatim}