Foreign/Marshal.hs

   1 {-# LANGUAGE CPP, NoImplicitPrelude #-}
   2
   3 -----------------------------------------------------------------------------
   4 -- |
   5 -- Module      :  Foreign.Marshal
   6 -- Copyright   :  (c) The FFI task force 2003
   7 -- License     :  BSD-style (see the file libraries/base/LICENSE)
   8 --
   9 -- Maintainer  :  ffi@haskell.org
  10 -- Stability   :  provisional
  11 -- Portability :  portable
  12 --
  13 -- Marshalling support
  14 --
  15 -----------------------------------------------------------------------------
  16
  17 module Foreign.Marshal
  18         (
  19          -- | The module "Foreign.Marshal" re-exports the other modules in the
  20          -- @Foreign.Marshal@ hierarchy:
  21           module Foreign.Marshal.Alloc
  22         , module Foreign.Marshal.Array
  23         , module Foreign.Marshal.Error
  24         , module Foreign.Marshal.Pool
  25         , module Foreign.Marshal.Utils
  26          -- | and provides one function:
  27         , unsafeLocalState
  28         ) where
  29
  30 import Foreign.Marshal.Alloc
  31 import Foreign.Marshal.Array
  32 import Foreign.Marshal.Error
  33 import Foreign.Marshal.Pool
  34 import Foreign.Marshal.Utils
  35
  36 #ifdef __GLASGOW_HASKELL__
  37 import GHC.IO
  38 #else
  39 import System.IO.Unsafe
  40 #endif
  41
  42 {- |
  43 Sometimes an external entity is a pure function, except that it passes
  44 arguments and/or results via pointers.  The function
  45 @unsafeLocalState@ permits the packaging of such entities as pure
  46 functions.
  47
  48 The only IO operations allowed in the IO action passed to
  49 @unsafeLocalState@ are (a) local allocation (@alloca@, @allocaBytes@
  50 and derived operations such as @withArray@ and @withCString@), and (b)
  51 pointer operations (@Foreign.Storable@ and @Foreign.Ptr@) on the
  52 pointers to local storage, and (c) foreign functions whose only
  53 observable effect is to read and/or write the locally allocated
  54 memory.  Passing an IO operation that does not obey these rules
  55 results in undefined behaviour.
  56
  57 It is expected that this operation will be
  58 replaced in a future revision of Haskell.
  59 -}
  60 unsafeLocalState :: IO a -> a
  61 unsafeLocalState = unsafePerformIO