with-stack-fobject

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

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-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.