The asdf-finalizers Reference Manual

This is the asdf-finalizers Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon May 15 03:18:38 2023 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 asdf-finalizers

Enforced calling of finalizers for Lisp code

Author

Francois-Rene Rideau

Dependency

asdf (system)., at least version "3.0"

Source

asdf-finalizers.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 asdf-finalizers/asdf-finalizers.asd

Source

asdf-finalizers.asd.

Parent Component

asdf-finalizers (system).

ASDF Systems

asdf-finalizers.


3.1.2 asdf-finalizers/pkgdcl.lisp

Source

asdf-finalizers.asd.

Parent Component

asdf-finalizers (system).

Packages

asdf-finalizers.


3.1.3 asdf-finalizers/finalizers.lisp

Dependency

pkgdcl.lisp (file).

Source

asdf-finalizers.asd.

Parent Component

asdf-finalizers (system).

Public Interface
Internals

3.1.4 asdf-finalizers/asdf-support.lisp

Dependency

finalizers.lisp (file).

Source

asdf-finalizers.asd.

Parent Component

asdf-finalizers (system).

Public Interface

3.1.5 asdf-finalizers/initialization.lisp

Dependency

pkgdcl.lisp (file).

Source

asdf-finalizers.asd.

Parent Component

asdf-finalizers (system).


4 Packages

Packages are listed by definition order.


4.1 asdf-finalizers

Source

pkgdcl.lisp.

Use List
  • asdf/interface.
  • common-lisp.
Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *warn-when-finalizers-off*

Flag to enable or disable the raising warnings
when finalizers are used outside of context.
Typically, you want that flag to be on while compiling your application, but off when your application is done compiled and you’re at runtime.

Package

asdf-finalizers.

Source

finalizers.lisp.


5.1.2 Macros

Macro: final-forms ()

This macro will expand into any final forms so far registered.
The forms will be expanded inside an
(EVAL-WHEN (:COMPILE-TOPLEVEL :LOAD-TOPLEVEL :EXECUTE) ...)
but you can override that with your own EVAL-WHEN.
You need to have finalizers enabled to use this macro (see WITH-FINALIZERS). In a file that uses finalizers, you MUST include (FINAL-FORMS)
after the last finalizer was used and before the end of the file,
or the compilation will fail.
Typically, you will write (FINAL-FORMS) as the very last form in your file, or if you didn’t use the asdf-finalizers package, you will instead write (ASDF-FINALIZERS:FINAL-FORMS).

Package

asdf-finalizers.

Source

finalizers.lisp.

Macro: with-finalizers ((&key finalize) &body body)

Evaluate BODY in a context where finalizers are enabled.
By default, don’t finalize, because we want to catch code
that fails to finalize in the same file that requires code finalization. This macro is typically used by ASDF when you configure it as below. For convenience, you may also use it to test code at the REPL;
you may then pass an argument FINALIZE with true value,
and WITH-FINALIZERS will evaluate finalization forms.

Package

asdf-finalizers.

Source

finalizers.lisp.


5.1.3 Ordinary functions

Function: assert-no-finalizer-left-behind ()
Package

asdf-finalizers.

Source

finalizers.lisp.

Function: call-with-finalizers (thunk &key finalize)
Package

asdf-finalizers.

Source

finalizers.lisp.

Function: check-finalizers-around-compile (fun)

Assuming your system :depends-on (:asdf-finalizers),
you may use this function as your :around-compile function
for an ASDF system, module or file, as in
:around-compile "asdf-finalizers:check-finalizers-around-compile" This will allow you to use finalizers within covered source files, and will issue an error if you fail to evaluate (FINAL-FORMS) after the last finalizer was used and before the end of the file. Alternatively, you may use ASDF::FINALIZED-CL-SOURCE-FILE below. You may also have your own custom :around-compile hooks
chain into CHECK-FINALIZERS-AROUND-COMPILE
to achieve the same effect and more.

Package

asdf-finalizers.

Source

asdf-support.lisp.

Function: compile-check-finalizers (input-file &rest keys &key &allow-other-keys)
Package

asdf-finalizers.

Source

asdf-support.lisp.

Function: eval-at-toplevel (form &optional already-done-p-form warning &rest warning-arguments)

This function, to be used within a macro, deftype, reader-macro, etc.,
will evaluate toplevel FORM now during the macroexpansion phase, but also
register it to be evaluated at the toplevel as part of the FINAL-FORMS,
so that assuming you use the FINAL-FORMS afterwards but before the end of current file, so it is available to whoever load the associated FASL or CFASL.
If the FORM has already been registered, it is skipped.
Either now or when loading the (C?)FASL, the evaluation of FORM will be skipped when ALREADY-DONE-P-FORM evaluates to a true value.
When finalizers are not enabled, warn with given warning and arguments or
with a default warning, unless ALREADY-DONE-P-FORM evaluated to a true value,
at which point we trust the user to somehow have done the right thing,
and a build from clean will hopefully catch him if he didn’t.

Package

asdf-finalizers.

Source

finalizers.lisp.

Function: no-finalizer-left-behind-p ()
Package

asdf-finalizers.

Source

finalizers.lisp.

Function: register-final-form (form)

This function, to be used within a macro, reader-macro, deftype, etc., will register a constant piece of code to the evaluated at toplevel at the end of the current code fragment (e.g. file).

Package

asdf-finalizers.

Source

finalizers.lisp.

Function: register-finalizer (finalizer)

This function, to be used within a macro, reader-macro, deftype, etc.,
will register a THUNK to be called during finalization.
Dependencies may be enforced by thunk calling thunk dependencies.
Any form returned by the THUNK will be included in the finalized code after the code from any previously registered thunk of constant code fragment, and after the code from any registered dependency.

Package

asdf-finalizers.

Source

finalizers.lisp.

Function: using-finalizers-p ()
Package

asdf-finalizers.

Source

finalizers.lisp.


5.1.4 Conditions

Condition: finalizers-off
Package

asdf-finalizers.

Source

finalizers.lisp.

Direct superclasses

condition.

Direct subclasses
Condition: finalizers-off-error
Package

asdf-finalizers.

Source

finalizers.lisp.

Direct superclasses
Direct subclasses

finalizers-off-simple-error.

Condition: finalizers-off-simple-error
Package

asdf-finalizers.

Source

finalizers.lisp.

Direct superclasses
Condition: finalizers-off-simple-warning
Package

asdf-finalizers.

Source

finalizers.lisp.

Direct superclasses
Condition: finalizers-off-warning
Package

asdf-finalizers.

Source

finalizers.lisp.

Direct superclasses
Direct subclasses

finalizers-off-simple-warning.


5.2 Internals


5.2.1 Special variables

Special Variable: *debug-finalizers*

Flag to enable debugging output for finalizers.

Package

asdf-finalizers.

Source

finalizers.lisp.

Special Variable: *finalizers*
Package

asdf-finalizers.

Source

finalizers.lisp.

Special Variable: *finalizers-data*
Package

asdf-finalizers.

Source

finalizers.lisp.


5.2.2 Macros

Macro: final-forms-internal ()
Package

asdf-finalizers.

Source

finalizers.lisp.


5.2.3 Ordinary functions

Function: disable-finalizers ()
Package

asdf-finalizers.

Source

finalizers.lisp.

Function: expand-final-forms ()
Package

asdf-finalizers.

Source

finalizers.lisp.

Function: reset-finalizers ()
Package

asdf-finalizers.

Source

finalizers.lisp.


5.2.4 Conditions

Condition: missing-final-forms
Package

asdf-finalizers.

Source

finalizers.lisp.

Direct superclasses

simple-warning.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   C   D   E   F   M   N   R   U   W  
Index Entry  Section

A
assert-no-finalizer-left-behind: Public ordinary functions

C
call-with-finalizers: Public ordinary functions
check-finalizers-around-compile: Public ordinary functions
compile-check-finalizers: Public ordinary functions

D
disable-finalizers: Private ordinary functions

E
eval-at-toplevel: Public ordinary functions
expand-final-forms: Private ordinary functions

F
final-forms: Public macros
final-forms-internal: Private macros
Function, assert-no-finalizer-left-behind: Public ordinary functions
Function, call-with-finalizers: Public ordinary functions
Function, check-finalizers-around-compile: Public ordinary functions
Function, compile-check-finalizers: Public ordinary functions
Function, disable-finalizers: Private ordinary functions
Function, eval-at-toplevel: Public ordinary functions
Function, expand-final-forms: Private ordinary functions
Function, no-finalizer-left-behind-p: Public ordinary functions
Function, register-final-form: Public ordinary functions
Function, register-finalizer: Public ordinary functions
Function, reset-finalizers: Private ordinary functions
Function, using-finalizers-p: Public ordinary functions

M
Macro, final-forms: Public macros
Macro, final-forms-internal: Private macros
Macro, with-finalizers: Public macros

N
no-finalizer-left-behind-p: Public ordinary functions

R
register-final-form: Public ordinary functions
register-finalizer: Public ordinary functions
reset-finalizers: Private ordinary functions

U
using-finalizers-p: Public ordinary functions

W
with-finalizers: Public macros


A.4 Data types

Jump to:   A   C   F   I   M   P   S  
Index Entry  Section

A
asdf-finalizers: The asdf-finalizers system
asdf-finalizers: The asdf-finalizers package
asdf-finalizers.asd: The asdf-finalizers/asdf-finalizers․asd file
asdf-support.lisp: The asdf-finalizers/asdf-support․lisp file

C
Condition, finalizers-off: Public conditions
Condition, finalizers-off-error: Public conditions
Condition, finalizers-off-simple-error: Public conditions
Condition, finalizers-off-simple-warning: Public conditions
Condition, finalizers-off-warning: Public conditions
Condition, missing-final-forms: Private conditions

F
File, asdf-finalizers.asd: The asdf-finalizers/asdf-finalizers․asd file
File, asdf-support.lisp: The asdf-finalizers/asdf-support․lisp file
File, finalizers.lisp: The asdf-finalizers/finalizers․lisp file
File, initialization.lisp: The asdf-finalizers/initialization․lisp file
File, pkgdcl.lisp: The asdf-finalizers/pkgdcl․lisp file
finalizers-off: Public conditions
finalizers-off-error: Public conditions
finalizers-off-simple-error: Public conditions
finalizers-off-simple-warning: Public conditions
finalizers-off-warning: Public conditions
finalizers.lisp: The asdf-finalizers/finalizers․lisp file

I
initialization.lisp: The asdf-finalizers/initialization․lisp file

M
missing-final-forms: Private conditions

P
Package, asdf-finalizers: The asdf-finalizers package
pkgdcl.lisp: The asdf-finalizers/pkgdcl․lisp file

S
System, asdf-finalizers: The asdf-finalizers system