with-static-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. Within the body, the object may be accessed, when the allocation argument is not :aligned, using fslot-value with the same value of its allocation argument; and when allocation is :aligned, with fslot-value-typed called with the allocation argument :aligned. The default allocation is :foreign, which for this macro only is equivalent to :foreign-static-gc. Under the right circumstances (described below) the object may be allocated on the stack.

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, and de-allocated after the body exits. Note that the de-allocation requires an implicit unwind-protect form.

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 this 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, which for this macro is equivalent to :foreign-static-gc). Either value will allocate the object in static space so the object that does not move during garbage collection.

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.

Warning: The var argument is considered dynamic-extent, and is always deallocated at the end of the form. No indefinite-extent capture of the object should be done; the object is freed regardless of whether there are any other pointers to it. Do not, for example, make the value of var be the value of a global variable for when the macro call completes, the value of the global variable may be invalid.

(defvar *my-global* nil)

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

See also with-stack-fobject, a macro that does not always de-allocate the object.

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-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 10.0 page.
Created 2019.8.20.