Editing Arrays (section)

== StorableArray (module [http://www.haskell.org/ghc/docs/latest/html/libraries/array/Data-Array-Storable.html Data.Array.Storable]) ==

A storable array is an IO-mutable array which stores its
contents in a contiguous memory block living in the C
heap. Elements are stored according to the class 'Storable'.
You can obtain the pointer to the array contents to manipulate
elements from languages like C.

It is similar to 'IOUArray' (in particular, it implements the same
MArray interface) but slower. The advantage is that it's compatible
with C through the foreign function interface. The memory addresses of
storable arrays are fixed, so you can pass them to C routines.

The pointer to the array contents is obtained by 'withStorableArray'.
The idea is similar to 'ForeignPtr' (used internally here).
The pointer should be used only during execution of the 'IO' action
returned by the function passed as argument to 'withStorableArray'.

<haskell>
 {-# OPTIONS_GHC -fglasgow-exts #-}
 import Data.Array.Storable
 import Foreign.Ptr
 import Foreign.C.Types
 
 main = do arr <- newArray (1,10) 37 :: IO (StorableArray Int Int)
           a <- readArray arr 1
           withStorableArray arr 
               (\ptr -> memset ptr 0 40)
           b <- readArray arr 1
           print (a,b)
 
 foreign import ccall unsafe "string.h" 
     memset  :: Ptr a -> CInt -> CSize -> IO ()
</haskell>

If you want to use this pointer afterwards, ensure that you call
'touchStorableArray' AFTER the last use of the pointer,
so that the array will be not freed too early.


Additional comments: GHC 6.6 made access to 
'StorableArray' as fast as to any other unboxed arrays. The only difference between 'StorableArray' and 'UArray' is that UArray lies in relocatable part of GHC heap while 'StorableArray' lies in non-relocatable part and therefore keep the fixed address, what allow to pass this address to the C routines and save it in the C data structures.

GHC 6.6 also adds an 'unsafeForeignPtrToStorableArray' operation that allows
the use of any Ptr as the address of a 'StorableArray' and in particular works with
arrays returned by C routines. Here is an example of using this operation:

<haskell>
import Data.Array.Storable
import Data.Array.Unsafe
import Foreign.Marshal.Alloc
import Foreign.Marshal.Array
import Foreign.ForeignPtr

main = do ptr <- mallocArray 10
          fptr <- newForeignPtr_ ptr
          arr <- unsafeForeignPtrToStorableArray (1,10) fptr :: IO (StorableArray Int Int)
          writeArray arr 1 64
          a <- readArray arr 1
          print a
          free ptr
</haskell>

This example allocates memory for 10 Ints (which emulates an array returned by some C function),
then converts the returned 'Ptr Int' to 'ForeignPtr Int' and 'ForeignPtr Int' to
'StorableArray Int Int'. It then writes and reads the first element of the array. At the end, the
memory used by the array is deallocated by 'free', which again emulates deallocation
by C routines. We can also enable the automatic freeing of the allocated block by replacing
"newForeignPtr_ ptr" with "newForeignPtr finalizerFree ptr". In this case memory will be 
automatically freed after the last array usage, as for any other Haskell objects.