| Allegro CL version 8.2 Moderately revised from 8.1. 8.1 version |
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
, 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-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 8.1 page.
Created 2016.6.21.
| Allegro CL version 8.2 Moderately revised from 8.1. 8.1 version |