| Copyright | (c) The FFI task force 2001 |
|---|---|
| License | BSD-style (see the file libraries/base/LICENSE) |
| Maintainer | ffi@haskell.org |
| Stability | provisional |
| Portability | portable |
| Safe Haskell | Trustworthy |
| Language | Haskell2010 |
Foreign.Marshal.Alloc
Description
The moduleForeign.Marshal.Alloc provides operations to allocate and deallocate blocks of raw memory (i.e., unstructured chunks of memory outside of the area maintained by the Haskell storage manager). These memory blocks are commonly used to pass compound data structures to foreign functions or to provide space in which compound result values are obtained from foreign functions.
If any of the allocation functions fails, an exception is thrown. In some cases, memory exhaustion may mean the process is terminated. Iffree orreallocBytes is applied to a memory area that has been allocated withalloca orallocaBytes, the behaviour is undefined. Any further access to memory areas allocated withalloca orallocaBytes, after the computation that was passed to the allocation function has terminated, leads to undefined behaviour. Any further access to the memory area referenced by a pointer passed torealloc,reallocBytes, orfree entails undefined behaviour.
All storage allocated by functions that allocate based on asize in bytes must be sufficiently aligned for any of the basic foreign types that fits into the newly allocated storage. All storage allocated by functions that allocate based on a specific type must be sufficiently aligned for that type. Array allocation routines need to obey the same alignment constraints for each array element.
alloca ::forall a b.Storable a => (Ptr a ->IO b) ->IO bSource#
alloca ff, passing as argument a pointer to a temporarily allocated block of memory sufficient to hold values of typea.
The memory is freed whenf terminates (either normally or via an exception), so the pointer passed tof mustnot be used after this.
allocaBytes ::Int -> (Ptr a ->IO b) ->IO bSource#
allocaBytes n ff, passing as argument a pointer to a temporarily allocated block of memory ofn bytes. The block of memory is sufficiently aligned for any of the basic foreign types that fits into a memory block of the allocated size.
The memory is freed whenf terminates (either normally or via an exception), so the pointer passed tof mustnot be used after this.
malloc ::forall a.Storable a =>IO (Ptr a)Source#
Allocate a block of memory that is sufficient to hold values of typea. The size of the area allocated is determined by thesizeOf method from the instance ofStorable for the appropriate type.
The memory may be deallocated usingfree orfinalizerFree when no longer required.
mallocBytes ::Int ->IO (Ptr a)Source#
Allocate a block of memory of the given number of bytes. The block of memory is sufficiently aligned for any of the basic foreign types that fits into a memory block of the allocated size.
The memory may be deallocated usingfree orfinalizerFree when no longer required.
calloc ::forall a.Storable a =>IO (Ptr a)Source#
Likemalloc but memory is filled with bytes of value zero.
callocBytes ::Int ->IO (Ptr a)Source#
LlikemallocBytes but memory is filled with bytes of value zero.
realloc ::forall a b.Storable b =>Ptr a ->IO (Ptr b)Source#
Resize a memory area that was allocated withmalloc ormallocBytes to the size needed to store values of typeb. The returned pointer may refer to an entirely different memory area, but will be suitably aligned to hold values of typeb. The contents of the referenced memory area will be the same as of the original pointer up to the minimum of the original size and the size of values of typeb.
If the argument torealloc isnullPtr,realloc behaves likemalloc.
reallocBytes ::Ptr a ->Int ->IO (Ptr a)Source#
Resize a memory area that was allocated withmalloc ormallocBytes to the given size. The returned pointer may refer to an entirely different memory area, but will be sufficiently aligned for any of the basic foreign types that fits into a memory block of the given size. The contents of the referenced memory area will be the same as of the original pointer up to the minimum of the original size and the given size.
If the pointer argument toreallocBytes isnullPtr,reallocBytes behaves likemalloc. If the requested size is 0,reallocBytes behaves likefree.
Free a block of memory that was allocated withmalloc,mallocBytes,realloc,reallocBytes,new or any of thenewX functions inForeign.Marshal.Array orForeign.C.String.
finalizerFree ::FinalizerPtr aSource#
A pointer to a foreign function equivalent tofree, which may be used as a finalizer (cfForeignPtr) for storage allocated withmalloc,mallocBytes,realloc orreallocBytes.
Produced byHaddock version 2.24.0