* 3.3 : Clarified use of foreign functions of pure type
authorManuel Chakravarty <chak@cse.unsw.edu.au>
Mon, 9 Jun 2003 14:57:53 +0000 (14:57 +0000)
committerManuel Chakravarty <chak@cse.unsw.edu.au>
Mon, 9 Jun 2003 14:57:53 +0000 (14:57 +0000)
* 4.1.1: Clarified the meaning of foreign imports without a & that have a
         non-functional type in Haskell
* 5.1  : Clarified the scope of safe use of unsafePerformIO
* 5.5  : "pre-emptive" dropped in footnote regarding finalizers.
* Typos throughout

ffi/ffi.tex

index cfa690b..a1c2d95 100644 (file)
 % does not claim to be a definition of the Haskell 98 Foreign Function
 % Interface. 
 
+% Changes since RC10:
+% * 3.3  : Clarified use of foreign functions of pure type
+% * 4.1.1: Clarified the meaning of foreign imports without a & that have a
+%          non-functional type in Haskell
+% * 5.1  : Clarified the scope of safe use of unsafePerformIO
+% * 5.5  : "pre-emptive" dropped in footnote regarding finalizers.
+% * Typos throughout
+%
 % Changes since RC9:
 % * 1:     Mentioning interaction with foreign threads as an open problem.
 % * 2 & 3: Removed `threadsafe' again, as the proposal for thread support is
 %          still evolving and it is not yet clear whether a new safety level
 %          is required.
-% * 5.5:   Added the type synonym `FinalizerPtr' and rewrite the documentation
+% * 5.5:   Added the type synonym `FinalizerPtr' and rewrote the documentation
 %          of finalizers.
 % * 5.6:   Clarified the description of `StablePtr'
 % * 5.8:   Added `finalizerFree'
 %   C bindings.
 
 % TODO:
+% * Add `newForeignPointer_' or similar
 % * Implement HTMLization.  (Malcolm suggests using
 %   <http://pauillac.inria.fr/~maranget/hevea/>)
 
 \excludeversion{FUTURE}  % material for future extensions
 
 %\def\Version{\relax}
-\def\Version{\\(Release Candidate 10)}
+\def\Version{\\(Release Candidate 11)}
 \begin{DRAFT}%
 {
   \gdef\Version{%
     \\
     \textbf{--- DRAFT ---}\\[1ex]
     \ttfamily\scriptsize
-    $\relax$Id: ffi.tex,v 1.43 2003/05/22 09:38:09 chak Exp $\relax$%
+    $\relax$Id: ffi.tex,v 1.44 2003/06/09 14:57:53 chak Exp $\relax$%
     \ignorespaces}
   }
 \end{DRAFT}
@@ -241,12 +250,12 @@ that generate code following the present specification.
 
 \subsection*{Acknowledgements}
 
-We heartly thank the kind people who assisted us with their comments and
-suggestions on the \code{ffi@haskell.org} mailing list as well as all the
-users of previous versions of the FFI who helped to shape the development by
-their feedback.  We thank Olaf Chitil, Peter Gammie, Wolfram Kahl, Martin D.
-Kealey, Ian Lynagh, Ross Paterson, and George Russell for errata to previous
-versions of this report.
+We heartily thank the kind people who assisted us with their comments and
+suggestions on the \code{ffi@haskell.org} and \code{haskell@haskell.org}
+mailing lists as well as all the users of previous versions of the FFI who
+helped to shape the development by their feedback.  We thank Olaf Chitil,
+Peter Gammie, Wolfram Kahl, Martin D.  Kealey, Ian Lynagh, Ross Paterson, and
+George Russell for errata to previous versions of this report.
 
 
 \clearemptydoublepage
@@ -452,7 +461,7 @@ dependent on the system for which the external entity has been compiled.
 
 As an example of how the calling convention is dominated by the system rather
 than the programming language, consider that an entity compiled to byte code
-for the Java Abstract Machine (JVM)~\cite{lindholm-etal:JVM} needs to be
+for the Java Virtual Machine (JVM)~\cite{lindholm-etal:JVM} needs to be
 invoked by the rules of the JVM rather than that of the source language in
 which it is implemented (the entity might be implemented in Oberon, for
 example).
@@ -477,7 +486,7 @@ identifiers for common calling conventions.
       \code{dotnet}
       & Calling convention of the \textsc{.net} platform\\
       \code{jvm} 
-      & Calling convention of the Java Abstract Machine\\
+      & Calling convention of the Java Virtual Machine\\
       \code{stdcall}
       & Calling convention of the Win32 API (matches Pascal conventions)\\
       \hline
@@ -587,6 +596,9 @@ foreign import ccall "math.h sin" sin :: CDouble -> CDouble.
 \end{verbatim}
 \end{quote}
 %
+Such a declaration asserts that the external entity is a true function; i.e.,
+when applied to the same argument values, it always produces the same result.
+
 Whether a particular form of external entity places a constraint on the
 Haskell type with which it can be imported is defined in
 Section~\ref{sec:extent}.  Although, some forms of external entities restrict
@@ -729,13 +741,37 @@ and \gterm{wrapper}, respectively, import stub functions that have to be
 generated by the Haskell system.  In the case of \gterm{dynamic}, the stub
 converts C function pointers into Haskell functions; and conversely, in the
 case of \gterm{wrapper}, the stub converts Haskell thunks to C function
-pointers.
-
-If neither of the specifiers \code{static}, \code{dynamic}, or \code{wrapper}
-is given, \code{static} is assumed.  The specifier \code{static} is
-nevertheless needed so that we can import C routines that are named
+pointers.  If neither of the specifiers \code{static}, \code{dynamic}, or
+\code{wrapper} is given, \code{static} is assumed.  The specifier
+\code{static} is nevertheless needed to import C routines that are named
 \code{dynamic} or \code{wrapper}.
 
+It should be noted that a static foreign declaration that does not import an
+address (i.e., where \gterm\& is not used in the specification of the external
+entity) always refers to a C function, even if the Haskell type is
+non-functional.  For example, 
+%
+\begin{quote}
+\begin{verbatim}
+foreign import ccall foo :: CInt
+\end{verbatim}
+\end{quote}
+%
+refers to a pure C function \code{foo} with no arguments that returns an
+integer value.  Similarly, if the type is \code{IO CInt}, the declaration
+refers to an impure nullary function.  If a Haskell program needs to access a
+C variable \code{bar} of integer type,
+%
+\begin{quote}
+\begin{verbatim}
+foreign import ccall "&" bar :: Ptr CInt
+\end{verbatim}
+\end{quote}
+%
+must be used to obtain a pointer referring to the variable.  The variable can
+be read and updated using the routines provided by the module \code{Storable}
+(cf.\ Section~\ref{sec:Storable}).
+
 \subsubsection{Export Declarations}
 
 External entities in \gnterm{ccall} export declarations are of the form
@@ -1021,22 +1057,27 @@ language-independent marshalling support.  These modules are \code{Bits},
 \code{Storable}, \code{MarshalAlloc}, \code{MarshalArray},
 \code{MarshalError}, and \code{MarshalUtils}.
 
-Furthermore, \code{Foreign} provides the following function:
+Sometimes an external entity is a pure function, except that it passes
+arguments and/or results via pointers.  To permit the packaging of
+such entities as pure functions, \code{Foreign} provides the following
+primitive:
 %
 \begin{codedesc}
-\item[unsafePerformIO ::\ IO a -> a] Execute an \code{IO} action in place of a
-  pure computations.  For the behaviour to be predictable, the IO computation
-  should be free of side effects and independent of its environment.
+\item[unsafePerformIO ::\ IO a -> a] Return the value resulting from executing
+  the \code{IO} action.  This value should be independent of the environment;
+  otherwise, the system behaviour is undefined.
   
   If the \code{IO} computation wrapped in \code{unsafePerformIO} performs side
   effects, then the relative order in which those side effects take place
   (relative to the main \code{IO} trunk, or other calls to
-  \code{unsafePerformIO}) is indeterminate.
+  \code{unsafePerformIO}) is indeterminate.  Moreover, the side effects may be
+  performed several times or not at all, depending on lazy evaluation and
+  whether the compiler unfolds an enclosing definition.
   
   Great care should be exercised in the use of this function.  Not only
   because of the danger of introducing side effects, but also because
-  \code{unsafePerformIO} may compromise typing, for example, when it is used
-  in conjunction with polymorphic references.
+  \code{unsafePerformIO} may compromise typing; in particular, the result of
+  \code{unsafePerformIO} should always have a monomorphic type.
 \end{codedesc}
 
 \subsection{\code{Bits}}
@@ -1249,7 +1290,7 @@ that---within the Haskell heap and stack---there are no more references left
 that are pointing to the \code{ForeignPtr}.  Typically, the finalizer will
 free the resources bound by the foreign object.  Finalizers are generally
 implemented in the foreign language\footnote{Finalizers in Haskell cannot be
-  savely realised without requiring support for pre-emptive
+  safely realised without requiring support for
   concurrency~\cite{boehm:finalizers}.} and have the following Haskell type:
 %
 \begin{quote}