Foreign/Marshal.hs

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