aclfree

Arguments: address

Frees a data block previously allocated with aclmalloc.

address - an integer that has been returned by aclmalloc and that has not previously been passed to aclfree. The block represented by this integer should no longer be used after this call.

aclmalloc calls the C function aclmalloc(). aclfree calls the C function aclfree(). address must not have been freed with that function either, of course.

If the argument is recognized as indicating a valid object, then this function returns the number of bytes that had originally been requested in the allocation. Otherwise 0 is returned. The actual number of bytes freed is at least the (non-zero value) returned and may be more if the original request was filled from a pool or larger areas.

The 0 return value is more complicated and means one of the following things:

1. The argument pointer is zero.
2. The argument pointer is not within the recorded allocations that aclmalloc has tracked.
3. A specific byte in the pointer's putative header is not the magic value it was originally set to.
4. The original aclmalloc request was for 0 bytes.

Cases 1 - 3 indicate a failure of some kind and no action is taken. Case 4 is odd but legal and does not indicated a failure.

Note on various Allegro CL malloc and free functions

The space allocated by excl:malloc and its C counterpart malloc() (described here collectively as "malloc") is different than the space allocated by excl:aclmalloc and the C aclmalloc() (described collectively as "aclmalloc"). Malloc allocates in space defined and maintained by the system, in whatever manner the system defines. Some operating systems allow the linking in of alternate versions of malloc() and its cohorts (usually including free(), calloc(), realloc(), and others), giving some flexibility in debugging malloc bugs (but of course this need arises much less often in Lisp programming). The aclmalloc functionalities are part of the Allegro CL library and allocate from space usually known as Aclmalloc heap space. aclmalloc is useful for allocating objects which should survive the rebirth of a dumped lisp.

The free and aclfree functionalities must always match objects to free with the mallocs of the same kind; i.e. one should never free an aclmalloc'd object, nor should one call an aclfree function on an object created with malloc. One can mix aclmalloc/aclfree with aclmalloc-aligned/aclfree-aligned, but only after proper conversions are done; see ff:address-to-aligned and ff:aligned-to-address.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 8.1 page.
Created 2016.6.21.