The constantfold Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The constantfold Reference Manual

This is the constantfold Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 17:53:42 2020 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction


* Constantfold - User-defined constant folding facility 

This is a supporting library for NUMCL.
It provides a single macro, =(constantfold name &key commutative associative copier)=.

=constantfold= registers the function =NAME= as an additional form that is
considered as a candidate for a constant.  For example,

#+begin_src lisp
(defstruct point2d
  (x 0 :type 'real)
  (y 0 :type 'real))

(defun point2d-add/2 (p1 p2)
  (ematch* (p1 p2)
    (((point2d :x x1 :y y1)
      (point2d :x x2 :y y2))
     (make-point2d :x (+ x1 x2) :y (+ y1 y2)))))

(defun point2d-add (&rest args)
  (reduce #'point2d-add/2 args))

(constantfold make-point2d :copier copy-point2d)
(constantfold point2d-add  :copier copy-point2d :commutative t :associative t)
#+end_src

This allows the compiler to constant fold

#+begin_src lisp
(defun fn1 () (point2d-add (make-point2d :x 1 :y 2) (make-point2d :x 3 :y 4)))
#+end_src

and

#+begin_src lisp
(defun fn1 () (point2d-add #S(point2d :x 1 :y 2) #S(point2d :x 3 :y 4)))
#+end_src

into

#+begin_src lisp
(defun fn1 () (copy-point2d #S(point2d :x 4 :y 6))).
#+end_src

When =:associative= and/or =:commutative= is true, it performs the corresponding
code morphing and tries to fold constants as much as possible.  For example,

#+begin_src lisp
(defun fn2 (p1 p2 x y)
  (point2d-add (make-point2d :x 1 :y 2)
               p1
               (make-point2d :x 3 :y 4)
               p2
               (make-point2d :x x :y y)))
#+end_src

gets compiled into

#+begin_src lisp
(defun fn2 (p1 p2 x y)
  (point2d-add (copy-point2d #S(point2d :x 4 :y 6))
               p1
               p2
               (make-point2d :x x :y y)))
#+end_src

due to commutativity.

This library preserves the original semantics of the code. For example,

#+begin_src lisp
(defun fn3 ()
  (make-point2d :x 1 :y 2))
#+end_src

originally always instantiates a new object. This is compiled into

#+begin_src lisp
(defun fn3 ()
  (copy-point2d #S(point2d :x 1 :y 2)))
#+end_src

which also instantiates a new object.
The reason why =fn1/fn2= are allowed to remove some instance creations while
=fn3= does not perform the pruning is that the result of =make-point2d= in =fn1/fn2=
are so-called *rvalues* which are not visible to the user
while the result of =(make-point2d :x 1 :y 2)= is going to be returned to the user
and is thus an *lvalue*.

It might then be confusing why =fn2= does not completely remove the instantiation.
This is because =point2d-add= may perform a destructive operation on the argument,
and thus the value (e.g. slots) of the constant could be modified.
=copy-point2d= is called in order to avoid the effect of this destructive operation.

COPIER could be ommited when the object is known to be immutable
and there is no need for copying the object.
In this case the compilation result always returns the same object under =EQ=.

Note that if the result of the constant folding is an object of class
=CL:STANDARD-OBJECT= / =CL:STRUCTURE-OBJECT= / =CL:CONDITION= / =CL:CLASS=, the
corresponding =CL:MAKE-LOAD-FORM= method should be defined.

** Dependencies
This library is at least tested on implementation listed below:

+ SBCL 1.4.12 on X86-64 Linux 4.4.0-141-generic (author's environment)
+ SBCL 1.5.1  on X86-64 Linux 4.4.0-141-generic (author's environment)

Also, it depends on the following libraries:

+ trivia by *Masataro Asai* :
    NON-optimized pattern matcher compatible with OPTIMA, with extensible optimizer interface and clean codebase
+ alexandria by *Nikodemus Siivola , and others.* :
    Alexandria is a collection of portable public domain utilities.
+ iterate by ** :
    Jonathan Amsterdam's iterator/gatherer/accumulator facility
+ lisp-namespace by *Masataro Asai* :
    Provides LISP-N --- extensible namespaces in Common Lisp.

[[./constantfold.png]]

** Author, License, Copyright

Masataro Asai (guicho2.71828@gmail.com)

Licensed under LGPL v3.

Copyright (c) 2019 IBM Corporation


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 constantfold

Author

Masataro Asai

Contact

guicho2.71828@gmail.com

License

LGPL

Description

User-defined constant folding facility

Version

0.1

Dependencies
Source

constantfold.asd (file)

Component

package.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 constantfold.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/constantfold-20191227-git/constantfold.asd

Systems

constantfold (system)


Previous: , Up: Lisp files   [Contents][Index]

3.1.2 constantfold/package.lisp

Parent

constantfold (system)

Location

package.lisp

Packages

constantfold

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 constantfold

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: constantfold NAME &key COMMUTATIVE ASSOCIATIVE COPIER

Registers a constant folding compiler macros to the function NAME.

Package

constantfold

Source

package.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: unfold NAME

Unregister the compiler macro

Package

constantfold

Source

package.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *constant-form-doc-table*
Package

constantfold

Source

package.lisp (file)

Special Variable: *constant-form-table*
Package

constantfold

Source

package.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Compiler macros

Compiler Macro: foldable-associative-fn &rest ARGS

Performs constant-folding for associative functions. Following optimization is performed:

(+ a 2 3 b) –> (+ a (+ 2 3) b) –> (+ a 5 b)

Package

constantfold

Source

package.lisp (file)

Compiler Macro: foldable-commutative-associative-fn &rest ARGS

Performs constant-folding for commutative and associative functions. Following optimization is performed:

(+ a 2 3 b 1) –> (+ (+ 2 3 1) a b) –> (+ 6 a b)

Package

constantfold

Source

package.lisp (file)

Compiler Macro: foldable-fn &rest ARGS

Performs a simple constant-folding. Constantfold when all arguments are constants.

Package

constantfold

Source

package.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: %foldable-associative-fn WHOLE ENV
Package

constantfold

Source

package.lisp (file)

Function: %foldable-commutative-associative-fn WHOLE ENV
Package

constantfold

Source

package.lisp (file)

Function: %foldable-fn WHOLE ARGS ENV
Package

constantfold

Source

package.lisp (file)

Function: compiler-macro-form-name WHOLE

Extracts the name of the function from the &whole argument of a compiler macro.

Package

constantfold

Source

package.lisp (file)

Function: constant-form-boundp SYMBOL

Automatically defined boolean function.

Package

constantfold

Source

package.lisp (file)

Function: constant-form-copier NAME
Package

constantfold

Source

package.lisp (file)

Function: constant-form-p FORM &optional ENV

Recursively checks if the form is a constant form.
Returns a boolean. When FORM is a standard constant form reconized by constantp, it also returns T as the secondary value.

Package

constantfold

Source

package.lisp (file)

Function: evaluate-constants NAME ARGS
Package

constantfold

Source

package.lisp (file)

Function: flatten-associative-nested-fn FORM

Flattens a tree of forms of the same functions. For example, (+ (+ 2 3) (+ 5 6)) into (+ 2 3 5 6).

Package

constantfold

Source

package.lisp (file)

Function: register-constant-form NAME &optional COPIER
Package

constantfold

Source

package.lisp (file)

Function: symbol-constant-form SYMBOL &optional DEFAULT

Automatically defined getter function. When DEFAULT is supplied, the value is set automatically.

Package

constantfold

Source

package.lisp (file)

Writer

(setf symbol-constant-form) (function)

Function: (setf symbol-constant-form) NEW-VALUE SYMBOL

Automatically defined setter function.

Package

constantfold

Source

package.lisp (file)

Reader

symbol-constant-form (function)

Function: wrap-inline NAME FORM

Allows further calls to the compiler macro.

Package

constantfold

Source

package.lisp (file)

Function: wrap-notinline NAME FORM

Suppresses further calls to the compiler macro which otherwise causes an infinite loop.

Package

constantfold

Source

package.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Conditions

Condition: unbound-constant-form ()
Package

constantfold

Source

package.lisp (file)

Direct superclasses

unbound-variable (condition)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.5 Types

Type: constant-form-type ()
Package

constantfold

Source

package.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
constantfold.asd: The constantfold․asd file
constantfold/package.lisp: The constantfold/package․lisp file

F
File, Lisp, constantfold.asd: The constantfold․asd file
File, Lisp, constantfold/package.lisp: The constantfold/package․lisp file

L
Lisp File, constantfold.asd: The constantfold․asd file
Lisp File, constantfold/package.lisp: The constantfold/package․lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %   (  
C   E   F   M   R   S   U   W  
Index Entry  Section

%
%foldable-associative-fn: Internal functions
%foldable-commutative-associative-fn: Internal functions
%foldable-fn: Internal functions

(
(setf symbol-constant-form): Internal functions

C
Compiler Macro, foldable-associative-fn: Internal compiler macros
Compiler Macro, foldable-commutative-associative-fn: Internal compiler macros
Compiler Macro, foldable-fn: Internal compiler macros
compiler-macro-form-name: Internal functions
constant-form-boundp: Internal functions
constant-form-copier: Internal functions
constant-form-p: Internal functions
constantfold: Exported macros

E
evaluate-constants: Internal functions

F
flatten-associative-nested-fn: Internal functions
foldable-associative-fn: Internal compiler macros
foldable-commutative-associative-fn: Internal compiler macros
foldable-fn: Internal compiler macros
Function, %foldable-associative-fn: Internal functions
Function, %foldable-commutative-associative-fn: Internal functions
Function, %foldable-fn: Internal functions
Function, (setf symbol-constant-form): Internal functions
Function, compiler-macro-form-name: Internal functions
Function, constant-form-boundp: Internal functions
Function, constant-form-copier: Internal functions
Function, constant-form-p: Internal functions
Function, evaluate-constants: Internal functions
Function, flatten-associative-nested-fn: Internal functions
Function, register-constant-form: Internal functions
Function, symbol-constant-form: Internal functions
Function, unfold: Exported functions
Function, wrap-inline: Internal functions
Function, wrap-notinline: Internal functions

M
Macro, constantfold: Exported macros

R
register-constant-form: Internal functions

S
symbol-constant-form: Internal functions

U
unfold: Exported functions

W
wrap-inline: Internal functions
wrap-notinline: Internal functions

Jump to:   %   (  
C   E   F   M   R   S   U   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*constant-form-doc-table*: Internal special variables
*constant-form-table*: Internal special variables

S
Special Variable, *constant-form-doc-table*: Internal special variables
Special Variable, *constant-form-table*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S   T   U  
Index Entry  Section

C
Condition, unbound-constant-form: Internal conditions
constant-form-type: Internal types
constantfold: The constantfold system
constantfold: The constantfold package

P
Package, constantfold: The constantfold package

S
System, constantfold: The constantfold system

T
Type, constant-form-type: Internal types

U
unbound-constant-form: Internal conditions

Jump to:   C   P   S   T   U