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 import GHC.IO
  36
  37 {- |
  38 Sometimes an external entity is a pure function, except that it passes
  39 arguments and/or results via pointers.  The function
  40 @unsafeLocalState@ permits the packaging of such entities as pure
  41 functions.
  42
  43 The only IO operations allowed in the IO action passed to
  44 @unsafeLocalState@ are (a) local allocation (@alloca@, @allocaBytes@
  45 and derived operations such as @withArray@ and @withCString@), and (b)
  46 pointer operations (@Foreign.Storable@ and @Foreign.Ptr@) on the
  47 pointers to local storage, and (c) foreign functions whose only
  48 observable effect is to read and/or write the locally allocated
  49 memory.  Passing an IO operation that does not obey these rules
  50 results in undefined behaviour.
  51
  52 It is expected that this operation will be
  53 replaced in a future revision of Haskell.
  54 -}
  55 unsafeLocalState :: IO a -> a
  56 unsafeLocalState = unsafePerformIO