Changes between Version 24 and Version 25 of ForeignFunctionInterface

Timestamp:

10/21/09 05:01:59 (4 years ago)

Author:

chak@…

Comment:

--

ForeignFunctionInterface

@@ -57 +57 @@
  * Some issues have been raised with `Data.Bits`.  However, any helpful changes would be too significant to consider at this stage.  This is a minor problem as a future revision has to overhaul the libraries anyway.
 
+=== unsafePerformIO ===
+
+The FFI libraries will include the function `unsafePerformIO` (as in the FFI addendum).  However, we limit the support use of the function purely to implement memory management and memory access during marshalling for foreign functions that ought to get a pure Haskell type.  Specifically, we will use the following wording (or something close):
+
+  Wrap a pure computation that uses local memory.  The only IO operations permitted in the IO action passed to `unsafePerformIO` are
+  (a) local allocation (`alloca`, `allocaBytes` and derived operations such as `withArray` and `withCString`), and
+  (b) pointer operations (`Foreign.Storable` and `Foreign.Ptr`) on the pointers to local storage, and
+  (c) foreign functions whose only observable effect is to read and/or  write the locally allocated memory.
+  This primitive enables the packaging of external entities that are pure functions except that they pass arguments and/or results via pointers.  It is expected that this operation will be replaced in a future revision of Haskell.
+
 === Alignment ===
 
@@ -81 +91 @@
 
 == Considerations for the future ==
+
+As noted above, we expect that `unsafePerformIO` will be replaced in a future revision (that supports rank-2 types) with a function that safely encapsulates the local state.  A possible implementation would be the following:
+{{{
+{-# LANGUAGE RankNTypes, ForeignFunctionInterface, GeneralizedNewtypeDeriving #-}
+
+module Example where
+
+import Foreign.C.Types
+import qualified Foreign.Marshal.Alloc as F
+import qualified Foreign.Ptr as F
+import qualified Foreign.Storable as F
+import System.IO.Unsafe (unsafePerformIO)
+
+-- Monad for memory regions, and type of pointers within such regions.
+-- Ideally all the implementations would be hidden
+
+newtype ST s a = UnsafeIOToST { unsafeSTToIO :: IO a } deriving Monad
+
+newtype STPtr s a = STPtr (F.Ptr a)
+
+runST :: (forall s. ST s a) -> a
+peek :: F.Storable a => STPtr s a -> ST s a
+poke :: F.Storable a => STPtr s a -> a -> ST s ()
+alloca :: F.Storable a => (STPtr s a -> ST s b) -> ST s b
+
+-- sample implementations
+runST act = unsafePerformIO (unsafeSTToIO act)
+peek (STPtr p) = UnsafeIOToST (F.peek p)
+poke (STPtr p) v = UnsafeIOToST (F.poke p v)
+alloca f = UnsafeIOToST (F.alloca (unsafeSTToIO . f . STPtr))
+
+-- Example of a wrapping of an otherwise pure function using pass-by-reference
+
+frexp :: Double -> (Double, Int)
+frexp x = runST (alloca $ \ exp_ptr -> do
+                fraction <- c_frexp (realToFrac x) exp_ptr
+                exponent <- peek exp_ptr
+                return (realToFrac fraction, fromIntegral exponent))
+
+foreign import ccall "math.h frexp"
+        c_frexp :: CDouble -> STPtr s CInt -> ST s CDouble
+}}}