Foreign/Marshal/Alloc.hs

   1 {-# OPTIONS -fno-implicit-prelude #-}
   2 -----------------------------------------------------------------------------
   3 -- |
   4 -- Module      :  Foreign.Marshal.Alloc
   5 -- Copyright   :  (c) The FFI task force 2001
   6 -- License     :  BSD-style (see the file libraries/core/LICENSE)
   7 --
   8 -- Maintainer  :  ffi@haskell.org
   9 -- Stability   :  provisional
  10 -- Portability :  portable
  11 --
  12 -- Marshalling support: basic routines for memory allocation
  13 --
  14 -----------------------------------------------------------------------------
  15
  16 module Foreign.Marshal.Alloc (
  17   -- * Allocation
  18   malloc,       -- :: Storable a =>        IO (Ptr a)
  19   mallocBytes,  -- ::               Int -> IO (Ptr a)
  20
  21   alloca,       -- :: Storable a =>        (Ptr a -> IO b) -> IO b
  22   allocaBytes,  -- ::               Int -> (Ptr a -> IO b) -> IO b
  23
  24   reallocBytes, -- :: Ptr a -> Int -> IO (Ptr a)
  25
  26   free          -- :: Ptr a -> IO ()
  27 ) where
  28
  29 import Data.Maybe
  30 import Foreign.Ptr              ( Ptr, nullPtr )
  31 import Foreign.C.TypesISO       ( CSize )
  32 import Foreign.Storable         ( Storable(sizeOf) )
  33
  34 #ifdef __GLASGOW_HASKELL__
  35 import GHC.Exception            ( bracket )
  36 import GHC.IOBase
  37 import GHC.Real
  38 import GHC.Ptr
  39 import GHC.Err
  40 import GHC.Base
  41 #endif
  42
  43
  44 -- exported functions
  45 -- ------------------
  46
  47 -- |Allocate space for storable type.  The size of the area allocated
  48 -- is determined by the 'sizeOf' method from the instance of
  49 -- 'Storable' for the appropriate type.
  50 --
  51 malloc :: Storable a => IO (Ptr a)
  52 malloc  = doMalloc undefined
  53   where
  54     doMalloc       :: Storable a => a -> IO (Ptr a)
  55     doMalloc dummy  = mallocBytes (sizeOf dummy)
  56
  57 -- |Allocate given number of bytes of storage, equivalent to C\'s @malloc()@.
  58 --
  59 mallocBytes      :: Int -> IO (Ptr a)
  60 mallocBytes size  = failWhenNULL "malloc" (_malloc (fromIntegral size))
  61
  62 -- |Temporarily allocate space for a storable type.
  63 --
  64 -- * the pointer passed as an argument to the function must /not/ escape from
  65 --   this function; in other words, in @alloca f@ the allocated storage must
  66 --   not be used after @f@ returns
  67 --
  68 alloca :: Storable a => (Ptr a -> IO b) -> IO b
  69 alloca  = doAlloca undefined
  70   where
  71     doAlloca       :: Storable a => a -> (Ptr a -> IO b) -> IO b
  72     doAlloca dummy  = allocaBytes (sizeOf dummy)
  73
  74 -- |Temporarily allocate the given number of bytes of storage.
  75 --
  76 -- * the pointer passed as an argument to the function must /not/ escape from
  77 --   this function; in other words, in @allocaBytes n f@ the allocated storage
  78 --   must not be used after @f@ returns
  79 --
  80 #ifdef __GLASGOW_HASKELL__
  81 allocaBytes :: Int -> (Ptr a -> IO b) -> IO b
  82 allocaBytes (I# size) action = IO $ \ s ->
  83      case newPinnedByteArray# size s      of { (# s, mbarr# #) ->
  84      case unsafeFreezeByteArray# mbarr# s of { (# s, barr#  #) ->
  85      let addr = Ptr (byteArrayContents# barr#) in
  86      case action addr    of { IO action ->
  87      case action s       of { (# s, r #) ->
  88      case touch# barr# s of { s ->
  89      (# s, r #)
  90   }}}}}
  91 #else
  92 allocaBytes      :: Int -> (Ptr a -> IO b) -> IO b
  93 allocaBytes size  = bracket (mallocBytes size) free
  94 #endif
  95
  96 -- |Adjust a malloc\'ed storage area to the given size (equivalent to
  97 -- C\'s @realloc()@).
  98 --
  99 reallocBytes          :: Ptr a -> Int -> IO (Ptr a)
 100 reallocBytes ptr size  =
 101   failWhenNULL "realloc" (_realloc ptr (fromIntegral size))
 102
 103 -- |Free malloc\'ed storage (equivalent to
 104 -- C\'s @free()@)
 105 --
 106 free :: Ptr a -> IO ()
 107 free  = _free
 108
 109
 110 -- auxilliary routines
 111 -- -------------------
 112
 113 -- asserts that the pointer returned from the action in the second argument is
 114 -- non-null
 115 --
 116 failWhenNULL :: String -> IO (Ptr a) -> IO (Ptr a)
 117 failWhenNULL name f = do
 118    addr <- f
 119    if addr == nullPtr
 120 #ifdef __GLASGOW_HASKELL__
 121       then ioException (IOError Nothing ResourceExhausted name
 122                                         "out of memory" Nothing)
 123 #else
 124       then ioError (userError (name++": out of memory"))
 125 #endif
 126       else return addr
 127
 128 -- basic C routines needed for memory allocation
 129 --
 130 foreign import ccall unsafe "malloc"  _malloc  ::          CSize -> IO (Ptr a)
 131 foreign import ccall unsafe "realloc" _realloc :: Ptr a -> CSize -> IO (Ptr a)
 132 foreign import ccall unsafe "free"    _free    :: Ptr a -> IO ()