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 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.

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). 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.

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. An accidental reference to the object might result in the de-allocation of the object and re-allocation of the same object, thus causing the pointer to look as if it were pointing either to garbage to some other newly allocated object.

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-2008, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 8.1. This page is new in the 8.1 release.
Created 2007.4.30.