allocate-fobject

Arguments: type &optional allocation size

This function allocates an object of the given type in the heap area 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 function sizeof-fobject, which returns the size of an object of the given foreign type, might be useful in determining possible values for size.

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 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 for 32-bit Lisps (it is not an issue on 64-bit Lisps): 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.

• :lisp-short - A lisp short-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 type is the same as the :lisp type described just above, except that the data is held in a short-array. (short-arrays are a new data type corresponding to the older array type in Allegro CL. See Arrays and short arrays section in implementation.htm.) Except for using a short-array, this type is the same as :lisp.
• :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. Objects allocated in :aligned mode should be freed with free-fobject-aligned.

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

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.