LOAD-TIME-VALUE(3cl) |
Common Lisp Reference |
LOAD-TIME-VALUE(3cl) |
NAME
load-time-value – delay evaluation until run time (special operator)
SYNOPSIS
|
ARGUMENTS and VALUES
—a form, evaluated as described below.
—a boolean, not evaluated.
—the primary value resulting from evaluating .
DESCRIPTION
load-time-value provides a mechanism for delaying evaluation of until the expression is in the run-time environment.
t, the result is a read-only quantity that can, if appropriate to the implementation, be copied into read-only space and/or coalesced with similar constant objects from other programs. If nil (the default), the result must be neither copied nor coalesced; it must be considered to be potentially modifiable data. designates whether the result can be considered a constant object. If
If a load-time-value expression is processed by compile-file, the compiler performs its normal semantic processing (such as macro expansion and translation into machine code) on , but arranges for the execution of to occur at load time in a null lexical environment, with the result of this evaluation then being treated as a literal object at run time. It is guaranteed that the evaluation of will take place only once when the file is loaded , but the order of evaluation with respect to the evaluation of top level forms in the file is implementation-dependent.
If a load-time-value expression appears within a function compiled with compile, the form is evaluated at compile time in a null lexical environment. The result of this compile-time evaluation is treated as a literal object in the compiled code.
If a load-time-value expression is processed by eval, is evaluated in a null lexical environment, and one value is returned. Implementations that implicitly compile (or partially compile) expressions processed by eval might evaluate only once, at the time this compilation is performed.
If the same list (load-time-value ) is evaluated or compiled more than once, it is implementation-dependent whether is evaluated only once or is evaluated more than once. This can happen both when an expression being evaluated or compiled shares substructure, and when the same form is processed by eval or compile multiple times. Since a load-time-value expression can be referenced in more than one place and can be evaluated multiple times by eval, it is implementation-dependent whether each execution returns a fresh object or returns the same object as some other execution. Users must use caution when destructively modifying the resulting object.
If two lists (load-time-value ) that are the same under equal but are not identical are evaluated or compiled, their values always come from distinct evaluations of . Their values may not be coalesced unless is t.
AFFECTED BY
(none)
EXCEPTIONAL SITUATIONS
(none)
NOTES
load-time-value must appear outside of quoted structure in a “for evaluation” position. In situations which would appear to call for use of load-time-value within a quoted structure, the backquote reader macro is probably called for.
Specifying nil for is not a way to force an object to become modifiable if it has already been made read-only. It is only a way to say that, for an object that is modifiable, this operation is not intended to make that object read-only.
EXAMPLES
The function
(defun () (+ #.(random 17)))
(defun () (+ (load-time-value (random 17))))
always returns the same value, even in different images. The function always returns the same value in a given image, but the value it returns might vary from image to image.
The function
(defvar (list
(make-array 7) (make-array 8)))
(defun () (aref (load-time-value
(first ) nil) ))
(defun ()
(setf (aref (load-time-value
(first ) nil) ) ))
references the nth element of the first of the that is available at load time. It is permissible for that array to be modified (e.g., by ); will see the updated values.
The function
(defvar (list
(make-array 7) (make-array 8)))
(defun () (aref
(load-time-value (first ) t) ))
references the nth element of the first of the that is available at load time. The programmer has promised that the array will be treated as read-only, so the system can copy or coalesce the array.
This use of LOAD-TIME-VALUE permits the indicated vector to be coalesced even though NIL was specified, because the object was already read-only when it was written as a literal vector rather than created by a constructor. User programs must treat the vector as read-only.
(defun ()
(let (( (load-time-value #() nil)))
(values (svref ) )))
SEE ALSO
compile-file(3cl), compile(3cl), eval(3cl)
AUTHOR and COPYRIGHT
Substantial portions of this page are taken from draft proposed American National Standard for Information Systems—Programming Language—Common Lisp, X3J13/94-101R, Version 15.17R, Fri 12-Aug-1994 6:35pm EDT; no copyright indicated.
Additional clarification and comments by Michael Marking <marking@tatanka.com>, http://www.tatanka.com/software/cl-manpages/; alternatively, https://github.com/wakinyantanka/cl-manpages/. Copyright 2017 Michael Marking as both an original and a derivative work.
Licensed under Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0).
This page last revised Sunday 26 February 2017.