malloc package:ghc-internal

Allocate a block of memory that is sufficient to hold values of type a. The size of the area allocated is determined by the sizeOf method from the instance of Storable for the appropriate type. The memory may be deallocated using free or finalizerFree when no longer required.

Allocate some memory and return a ForeignPtr to it. The memory will be released automatically when the ForeignPtr is discarded. mallocForeignPtr is equivalent to

do { p <- malloc; newForeignPtr finalizerFree p }

although it may be implemented differently internally: you may not assume that the memory returned by mallocForeignPtr has been allocated with malloc. GHC notes: mallocForeignPtr has a heavily optimised implementation in GHC. It uses pinned memory in the garbage collected heap, so the ForeignPtr does not require a finalizer to free the memory. Use of mallocForeignPtr and associated functions is strongly recommended in preference to newForeignPtr with a finalizer.

This function is similar to mallocArray, but yields a memory area that has a finalizer attached that releases the memory area. As with mallocForeignPtr, it is not guaranteed that the block of memory was allocated by malloc.

This function is similar to mallocArray0, but yields a memory area that has a finalizer attached that releases the memory area. As with mallocForeignPtr, it is not guaranteed that the block of memory was allocated by malloc.

This function is similar to mallocForeignPtr, except that the size of the memory required is given explicitly as a number of bytes.

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 using free or finalizerFree when no longer required.

Allocate storage for the given number of elements of a storable type (like malloc, but for multiple elements).

Like mallocArray, but add an extra position to hold a special termination element.

This function is similar to mallocForeignPtrBytes, except that the size and alignment of the memory required is given explicitly as numbers of bytes.

Allocate some memory and return a ForeignPtr to it. The memory will be released automatically when the ForeignPtr is discarded. GHC notes: mallocPlainForeignPtr has a heavily optimised implementation in GHC. It uses pinned memory in the garbage collected heap, as for mallocForeignPtr. Unlike mallocForeignPtr, a ForeignPtr created with mallocPlainForeignPtr carries no finalizers. It is not possible to add a finalizer to a ForeignPtr created with mallocPlainForeignPtr. This is useful for ForeignPtrs that will live only inside Haskell (such as those created for packed strings). Attempts to add a finalizer to a ForeignPtr created this way, or to finalize such a pointer, will throw an exception.

This function is similar to mallocForeignPtrAlignedBytes, except that the internally an optimised ForeignPtr representation with no finalizer is used. Attempts to add a finalizer will cause an exception to be thrown.

This function is similar to mallocForeignPtrBytes, except that the internally an optimised ForeignPtr representation with no finalizer is used. Attempts to add a finalizer will cause an exception to be thrown.

The pointer refers to a byte array. The MutableByteArray# field means that the MutableByteArray# is reachable (by GC) whenever the ForeignPtr is reachable. When the ForeignPtr becomes unreachable, the runtime's normal GC recovers the memory backing it. Here, the finalizer function intended to be used to free() any ancillary *unmanaged* memory pointed to by the MutableByteArray#. See the zlib library for an example of this use.

1. Invariant: The Addr# in the parent ForeignPtr is an interior pointer into this MutableByteArray#.
2. Invariant: The MutableByteArray# is pinned, so the Addr# does not get invalidated by the GC moving the byte array.
3. Invariant: A MutableByteArray# must not be associated with more than one set of finalizers. For example, this is sound:

incrGood :: ForeignPtr Word8 -> ForeignPtr Word8
incrGood (ForeignPtr p (MallocPtr m f)) = ForeignPtr (plusPtr p 1) (MallocPtr m f)

But this is unsound:

incrBad :: ForeignPtr Word8 -> IO (ForeignPtr Word8)
incrBad (ForeignPtr p (MallocPtr m _)) = do
f <- newIORef NoFinalizers
pure (ForeignPtr p (MallocPtr m f))

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.

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

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.

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