with-stack-fobject

Arguments: (var type &key allocation size) &rest body

In releases prior to 8.1, the argument list was ((var type &rest etc) &rest body), but the etc argument was not documented. The new argument list uses keyword arguments. This should be backward compatible unless code has assumed the underlying implementation and given those arguments.

This macro allocates a foreign object of the specified type, allocation, and size, and binds it to var while evaluating body. The body is evaluated inside a lexical binding of var. Withing the body, the object may be accessed using fslot-value with the same allocation argument. The default allocation is :foreign. Under the right circumstances (described below) the object may be allocated on the stack.

The allocation argument defaults to :foreign, and can be one of :c, :aligned, :lisp, :lisp-short, :foreign, or :foreign-static-gc. Note that if allocation is :c or :aligned, it is not stack-allocated, but instead is allocated and deallocated at the appropriate places within the form.

If the type and allocation are compile-time constants, and the allocation is :foreign, :foreign-static-gc, :lisp, or :lisp-short, and the size argument is not specified, and if the body is compiled under suitable circumstances (dynamic-extent declarations are trusted), then the object is allocated on the stack. The object will disappear after control leaves body; thus the program must not maintain any pointers to the object past this point.

Otherwise, the object is allocated as specified. In this case, if the allocation requires explicit de-allocation, it is the responsibility of the application to de-allocate the object.

The size argument forces a minimum size on the allocated foreign object as in allocate-fobject. If this keyword is given, the stack allocation will fail, since this argument forces extra dynamic requirements on a construct that wants to be statically specified.

If a with-stack-fobject form is evaluated by the interpreter, or is compiled under circumstances that don't trust dynamic-extent declarations, the object will be allocated as specified (the default is as a :foreign object). If the intent is to allocate an object that does not move during garbage collection then the allocation argument must specify a static allocation type, ie :foreign-static-gc.

In situations where the allocation style is critical to an application, the compiled code may need to be inspected or disassembled to verify how the foreign object is allocated. A run-time check is also possible with excl::stack-allocated-p.

Multiple bindings can be done with with-stack-fobjects.

See also with-static-fobject, a macro that garantees de-allocation.

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-2009, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 8.1. The object described on this page has been modified in the 8.1 release; see the Release Notes.
Created 2007.4.30.