| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 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. 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-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |