Interruptible FFI calls with pthread_kill and CancelSynchronousIO. v4

[ghc-hetmet.git] / docs / users_guide / ffi-chap.xml

diff --git a/docs/users_guide/ffi-chap.xml b/docs/users_guide/ffi-chap.xml
index 7e2c547..b33e95a 100644 (file)
--- a/docs/users_guide/ffi-chap.xml
+++ b/docs/users_guide/ffi-chap.xml
@@ -19,7 +19,7 @@ Foreign function interface (FFI)
 
   <para>The FFI libraries are documented in the accompanying library
   documentation; see for example the
-    <ulink url="../libraries/base/Control-Concurrent.html"><literal>Foreign</literal></ulink> module.</para>
+    <ulink url="&libraryBaseLocation;/Control-Concurrent.html"><literal>Foreign</literal></ulink> module.</para>
 
   <sect1 id="ffi-ghcexts">
     <title>GHC extensions to the FFI Addendum</title>
@@ -63,6 +63,21 @@ OK:
 </programlisting>
 </para>
       </sect2>
+
+      <sect2 id="ffi-prim">
+        <title>Primitive imports</title>
+       <para>
+         GHC extends the FFI with an additional calling convention
+         <literal>prim</literal>, e.g.:
+<programlisting>
+   foreign import prim "foo" foo :: ByteArray# -> (# Int#, Int# #)
+</programlisting>
+         This is used to import functions written in Cmm code that follow an
+         internal GHC calling convention. This feature is not intended for
+         use outside of the core libraries that come with GHC. For more
+         details see the GHC developer wiki.
+       </para>
+      </sect2>
   </sect1>
 
   <sect1 id="ffi-ghc">
@@ -461,6 +476,15 @@ int main(int argc, char *argv[])
           threads, but there may be an arbitrary number of foreign
           calls in progress at any one time, regardless of
           the <literal>+RTS -N</literal> value.</para>
+
+        <para>If a call is annotated as <literal>interruptible</literal>
+          and the program was multithreaded, the call may be
+          interrupted in the event that the Haskell thread receives an
+          exception.  The mechanism by which the interrupt occurs
+          is platform dependent, but is intended to cause blocking
+          system calls to return immediately with an interrupted error
+          code.  The underlying operating system thread is not to be
+          destroyed.</para>
       </sect3>
 
       <sect3 id="haskell-threads-and-os-threads">
@@ -483,7 +507,7 @@ int main(int argc, char *argv[])
           threads</emphasis>, which are Haskell threads tied to a
           particular OS thread.  For information on bound threads, see
           the documentation
-          for the <ulink url="../libraries/base/Control-Concurrent.html"><literal>Control.Concurrent</literal></ulink>
+          for the <ulink url="&libraryBaseLocation;/Control-Concurrent.html"><literal>Control.Concurrent</literal></ulink>
           module.</para>
       </sect3>
       
@@ -548,7 +572,6 @@ int main(int argc, char *argv[])
 
 <!-- Emacs stuff:
      ;;; Local Variables: ***
-     ;;; mode: xml ***
      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter") ***
      ;;; End: ***
  -->