malloc package:base
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.
- Invariant: The Addr# in the parent ForeignPtr is an
interior pointer into this MutableByteArray#.
- Invariant: The MutableByteArray# is pinned, so the
Addr# does not get invalidated by the GC moving the byte
array.
- 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.