excl:pll-file [function]
arguments: none
Return the location of the current .pll file, or nil if there is no .pll file associated with this Lisp.
excl:use-pll-file [function]
arguments: name &key (global-gc t)
If the current Lisp has no .pll file, an association is made with the file name and the heap is remapped to use the resulting new pure space. An error is signaled if the current Lisp already has a .pll file. All code vectors in the heap are redirected if they have a corresponding bit-equivalent code vector in the file specified by name. Strings are redirected if they have equivalents in name, and if they appear as symbol-names in symbols, or if they appear in the constant vectors of function objects. All other strings must be redirected purified by the user using excl:maybe-purify-string or excl:pure-string [documented elsewhere]. Warning: the user must be careful not to purify a string that is not a constant; if subsequent modification of string contents is attempted, an error will be signaled.
The :global-gc argument defaults to t. Specifying nil for this argument allows the user to delay the global GC until all strings are purified. A global GC is necessary to remove all old code vectors and strings that have now been replaced in pure space. There are other ways a global gc can automatically occur. See the Garbage Collector documentation in the User Guide for more information on preventing these global GCs.
sys:record-code-vectors [macro]
arguments: (file &key verbose) &body body
Essentially a call to sys:record-training (documented in Tech memo #23). file is the name of an output .cvs file.
sys:record-strings [macro]
arguments: file &body body
Like sys:record-code-vectors, sys:record-strings provides a mechanism for building input to the cvdcvt program, which creates .pll files. The specified file is opened for writing, and all strings that are seen as constants during a load are written to this .str file. Also, any string that is seen in a excl:pure-string or excl:maybe-purify-string call is also written to the .str file.
The body of the macro should perform some system building activity, like loading in fasl files. Any load-time execution can also make a string look like a constant by calling maybe-purify-string or pure-string. Symbol-names are not automatically added to the .str file; The following paradigm should be used as one of the forms inside the body:
(do-symbols (sym (find-package :my-package)) (excl:maybe-purify-string (symbol-name sym)))
This reduction of automation was done purely as an optimization, to minimize the number of strings that are written to the .str file, since symbol-names show up so often in fasl files. When the symbol-name is later encountered in a fasl file being loaded into a Lisp that already has a .pll file, the pure name is automatically used.
cvdcvt [-o outfilename] [-u] [file1 file2 ...] |
[program] |
The file arguments must have been created using sys:write-codevectors, sys:record-strings, or sys:record-code-vectors.
A .pll file, outfilename, is created holding all the unique code vectors and strings. If outfilename is omitted it defaults to code.blob.
If -u is specified, then no duplications of strings are done, otherwise for every string that has no lowercase characters in it and at least one uppercase character, a lowercase copy is added to the output file. This is the default and is useful for set-case-mode. If no files are specified, stdin is used.
.str (string) files and .cvs (code vector) files are combined without redundancies; if two files of the same extension have identical objects, the object from the file specified first to cvdcvt is retained, and the latter object is removed from the output. This allows for files (.cvs files especially) to be arranged by code vectors in order of execution, to provide for locality of reference. Those .cvs files that were produced by training techniques should be placed first in order to have the desired effect.
Some base .str and .cvs files are provided. If these provided files are given to cvdcvt as well as user-created files, then the resulting .pll file will be more complete. Most provided files are named in such a way as to make obvious what is in them; e.g. lisp.str contains all strings in the base product.
system:flush-codevectors [Function]
Arguments: &optional file verbose
The first time this function is called, it writes out and dereferences all heap-allocated code vectors except those being executed when this function is called (perhaps by some other stack group as well). The code vectors are written to the file specified by file. This file cannot exist when this function is called for the first time (the system will create it). A heap-allocated code vector is one that is not stored in text space when the Lisp image is built. The function objects associated with the code vectors are destructively modified to become stub functions (with a pointer to file). The code vectors that are written to file are orphaned and thus will be garbage collected by the next global gc --a global gc is required to collect them because most code vectors are in oldspace.
In subsequent calls, the file argument is ignored. The file specified in the first call is used. All heap-allocated code vectors except those actually in use are flushed with each call. In the second and subsequent calls, newly created code vectors are appended to those already flushed.
If in the first call to system:flush-codevectors file is unspecified or nil, the system creates an anonymous filename that is not visible in the filesystem (ls will not find it, because it is unlinked after it is created, so it is removed automatically when Lisp exits). If you use an anonymous file, excl:dumplisp will not work (since the file where the code vectors are will not be available when the dumped image is restarted).
The verbose argument, if non-nil, will cause this function to print information about the actions it takes. The default for verbose is nil. Note that you can specify the file argument as nil if you wish to specify verbose as t and have the system choose an anonymous filename.
This function is primarily designed to clear the system before a training run to determine necessary code vectors for a specific application. However, periodically calling this function during ordi- nary Lisp operation may prevent the image from growing unnecessarily and may improve locality of reference. Please note that we say may in the last sentence.
system:write-codevectors [Function]
Arguments: file &optional verbose
This function creates a file named file and writes all heap-allocated code vectors for heap-allocated functions to it. (Our convention is that the filename should have the extension .cvs.) The code vectors written to file are not flushed from the heap, as with system:flush-codevectors, they are just written to file. The file written is appropriate as a command-line argument to build/install_lisp. system:write-codevectors cannot extend or append to an existing code-vector file, so different output filenames should be used if this function is called more than once.
If the verbose argument is specified non-nil, information about what is written to file will be printed.
system:trace-incremental-fasl [Function]
Arguments:
This function is no longer supported. See the note in section 4.1 above for more information.
system:record-training [Macro]
Arguments: (&key :code :verbose) &body body
This macro combines the use of the above three functions in a way that makes easy the recording of heap-allocated code vectors and tracing information during the evaluation of body to files given by the keywords :code and :fasl. Essentially, this macro calls system:flush-codevectors with nil as its argument, then executes body, then calls system:write-codevectors.
A filename must be supplied as the value of the :code keyword argument. The value of :code specifies a filename to which code vectors are written by system:write-codevectors. (Recall that flush-codevectors is called with nil as its argument so the initial flushing of code vectors is to an anonymous file.) The value of :fasl, allowed in releases prior to 4.3, is no longer supported.
If the :verbose argument is specified non-nil, information about the process is printed.
system:load-incremental-fasl-trace [Function]
Arguments:
This function is no longer supported. See the note in section 4.1 above for more information.
excl:resident-function [Function]
Arguments: func
Returns a fully loaded function corresponding to func, which must be a function object (not a symbol). If the function object is already fully loaded, it is simply returned. If the function object is a stub, the full definition (i.e. all the call-time info) is loaded and then the complete function object is returned.
It is important to make clear the timing of updating the internal function definition. The issue is that there may be pointers to the stub function definition in live Lisp objects. Those pointers must remain valid until they can be updated. Therefore, at first, the stub function is destructively modified to point to the complete definition. At the next garbage collection, all pointers are updated and the stub function is disposed of.
This means that things you would expect to be eq will not be eq, at least for a while. Thus, if the function is fully loaded when you call excl:resident-function, the returned value will be eq to the argument. If the function is not fully loaded, the returned value will not be eq to the argument and other references to the function object may not be eq to the returned value until a garbage collection.
Section 19.3.2 in the Allegro CL User Guide further discusses this point. See the information under the heading Affect on users 2: eq-ness of function objects.
excl:*libfasl* [Variable]
This variable provides the default value for the :libfasl keyword argument to load. The initial value of this variable depends on how Allegro CL was configured. If +presto was specified on the build/install_lisp command line, then the initial value of this variable is t but if +presto was not specified, the initial value is nil.
The next two functions are useful when dumping a Lisp image with excl:dumplisp. The first identifies all files that contain call-time function info. The second produces a new file that contains the call-time function info for every partially loaded function.
system:presto-fasl-set [Function]
Returns a list of files (actually strings naming files) that are referenced by unresolved stub functions in the image. This is an important function to call when dumping an image with excl:dumplisp since the dumped image must have all necessary files containing needed call-time function info available.
Each file that is libfasl loaded is associated with a weak vector with one entry for each stub function. The entry is removed when the function is fully loaded. However, the weak vector may still exist (even without any live elements) when this function is called and if it does, the associated file will be included in the returned list even though in fact it contains no necessary call-time function info. This may not be a problem but if you want the list with all such files removed, do a global gc just prior to calling this function:
(excl:gc t) (sys:presto-fasl-set)
system:presto-build-lib [Function]
Arguments: file
This function returns t after copying all the outstanding stub definitions to file and modifies the pointer in each stub function to point to file. Therefore, this function frees a prestoized image from the links to various fasl files loaded in libfasl mode and from the bundle file in the Lisp library (typically a file named files.bu) that may contain call-time function info for functions defined in the base Lisp, transferring the dependency to file, which becomes the bundle file for the image (and any descendent images created with excl:dumplisp) from this point on.
file must be a string. It can name a file with an absolute or relative pathname (including naming a file with no directory information -- e.g. "myfile"). If file is named with a relative pathname, Lisp will interpret it with respect to the current directory.
It is typical to call this function just before dumping an image with excl:dumplisp, particularly if you intend to run the dumped image on a different machine than the one the current image is running on. (If it will be run on the same machine and all the fasl files are in place, stubs should resolve without difficulty, barring network problems.) You should bind or set excl:*libfasl* to nil prior to calling this function and leave it nil until the call to excl:dumplisp has completed to ensure that other functions are not libfasl loaded during the call to excl:dumplisp (since their call-time function info will not be in the file).
file will not be a fasl file. That means that it cannot be loaded into Lisp. You can move file about with the dumped image. The pointers to file in stub functions will be to the filename of file and will be looked for the the home directory (the translation of sys:). The same information will be stored in the dumped image.