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