allocate-fobject

$Revision: 5.0.2.2 $

Function

Package: FOREIGN-FUNCTIONS

Arguments: (type &optional allocation size)

Allocate an object of the given type in heap described by the allocation argument. If the size argument is given, then it is the minimum size (in bytes) of the data portion of the object that will be allocated. The valid allocation argument values are as follows (default is :foreign). type should be a type defined with def-foreign-type.

:foreign - The object is allocated in the lisp heap using a lisp data type unique to Allegro called the (array excl::foreign). This kind of array has one lisp slot at the beginning, with all subsequent slots holding raw integer data. The foreign types facility uses the first, lisp-valued, slot to hold a pointer to a description of the type of data held in this object. Because these objects are stored in the Lisp heap, it doesn't make sense to ask for the address of a slot of one of these objects, as it may have moved by the time you get your answer.
:foreign-static-gc - These objects look just like :foreign allocated objects. The difference is that they are allocated in static space (i.e. space allocated with the C function aclmalloc). Unlike other objects allocated in static space, these objects are automatically gc'ed (the C aclfree function is called on them) when the last pointer to them in the Lisp heap disappears. The advantage of this allocation type over :foreign is that the object doesn't move. This makes it very useful when the object must be passed to a C foreign-function that releases the heap (e.g. most functions in the Windows package).
:lisp - A lisp array of type (unsigned-byte 8) of sufficient size to hold the object is allocated in the lisp heap. The object does not record the foreign type of which it is an instance. This allocation type is useful if you've got a binary file you want to read and take apart, and the format of the file is described by a C struct definition. In that case you can allocate an object of type :lisp and then call read-sequence to read the data from the binary file into the foreign object. Note, however, that read-sequence will also work for :foreign allocated objects. There is one tricky case: if the foreign structure requires 8 byte alignment (e.g. it begins with a double float) then the first four bytes of the lisp array allocated will not be used by fslot-value-typed. If you read-sequence into such an array, then your data will be displaced 4 bytes from where fslot-value-typed thinks it is.
:c - The object is allocated in static space (via aclmalloc() which is like C's malloc except that the data is preserved through a call to dumplisp) and a pointer to the space is returned. Thus the object is represented by an integer value. The object is not automatically freed. You must do the freeing with free-fobject
:aligned - This is just like :c except that it returns an aligned pointer.

See foreign_functions.htm for general information on foreign functions in Allegro CL. See ftype.htm for information on foreign types.

The general documentation description is in introduction.htm. The index is in index.htm.