base-4.3.1.0: Basic libraries

Portability | portable
Stability | provisional
Maintainer | sven.panne@aedion.de

Foreign.Marshal.Pool

Contents

- Pool management
- (Re-)Allocation within a pool
- Combined allocation and marshalling

Description

This module contains support for pooled memory management. Under this scheme, (re-)allocations belong to a given pool, and everything in a pool is deallocated when the pool itself is deallocated. This is useful when `Foreign.Marshal.Alloc.alloca` with its implicit allocation and deallocation is not flexible enough, but explicit uses of `Foreign.Marshal.Alloc.malloc` and `free` are too awkward.

Synopsis

- data Pool
- newPool :: IO Pool
- freePool :: Pool -> IO ()
- withPool :: (Pool -> IO b) -> IO b
- pooledMalloc :: Storable a => Pool -> IO (Ptr a)
- pooledMallocBytes :: Pool -> Int -> IO (Ptr a)
- pooledRealloc :: Storable a => Pool -> Ptr a -> IO (Ptr a)
- pooledReallocBytes :: Pool -> Ptr a -> Int -> IO (Ptr a)
- pooledMallocArray :: Storable a => Pool -> Int -> IO (Ptr a)
- pooledMallocArray0 :: Storable a => Pool -> Int -> IO (Ptr a)
- pooledReallocArray :: Storable a => Pool -> Ptr a -> Int -> IO (Ptr a)
- pooledReallocArray0 :: Storable a => Pool -> Ptr a -> Int -> IO (Ptr a)
- pooledNew :: Storable a => Pool -> a -> IO (Ptr a)
- pooledNewArray :: Storable a => Pool -> [a] -> IO (Ptr a)
- pooledNewArray0 :: Storable a => Pool -> a -> [a] -> IO (Ptr a)

# Pool management

data Pool

A memory pool.

newPool :: IO Pool

Allocate a fresh memory pool.

freePool :: Pool -> IO ()

Deallocate a memory pool and everything which has been allocated in the pool itself.

withPool :: (Pool -> IO b) -> IO b

Execute an action with a fresh memory pool, which gets automatically deallocated (including its contents) after the action has finished.

# (Re-)Allocation within a pool

pooledMalloc :: Storable a => Pool -> IO (Ptr a)

Allocate space for storable type in the given pool. The size of the area allocated is determined by the `sizeOf` method from the instance of `Storable` for the appropriate type.

pooledMallocBytes :: Pool -> Int -> IO (Ptr a)

Allocate the given number of bytes of storage in the pool.

pooledRealloc :: Storable a => Pool -> Ptr a -> IO (Ptr a)

Adjust the storage area for an element in the pool to the given size of the required type.

pooledReallocBytes :: Pool -> Ptr a -> Int -> IO (Ptr a)

Adjust the storage area for an element in the pool to the given size.

pooledMallocArray :: Storable a => Pool -> Int -> IO (Ptr a)

Allocate storage for the given number of elements of a storable type in the pool.

pooledMallocArray0 :: Storable a => Pool -> Int -> IO (Ptr a)

Allocate storage for the given number of elements of a storable type in the pool, but leave room for an extra element to signal the end of the array.

pooledReallocArray :: Storable a => Pool -> Ptr a -> Int -> IO (Ptr a)

Adjust the size of an array in the given pool.

pooledReallocArray0 :: Storable a => Pool -> Ptr a -> Int -> IO (Ptr a)

Adjust the size of an array with an end marker in the given pool.

# Combined allocation and marshalling

pooledNew :: Storable a => Pool -> a -> IO (Ptr a)

Allocate storage for a value in the given pool and marshal the value into this storage.

pooledNewArray :: Storable a => Pool -> [a] -> IO (Ptr a)

Allocate consecutive storage for a list of values in the given pool and marshal these values into it.

pooledNewArray0 :: Storable a => Pool -> a -> [a] -> IO (Ptr a)

Allocate consecutive storage for a list of values in the given pool and marshal these values into it, terminating the end with the given marker.