The compiler-macro-notes Reference Manual

Table of Contents

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

The compiler-macro-notes Reference Manual

This is the compiler-macro-notes Reference Manual, version 0.2.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 04:30:54 2022 GMT+0.


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

1 Introduction

compiler-macro-notes

Another attempt at compiler-macro.

EXAMPLE USAGE

Notes may be muffled by

The effect is that the notes are signalled but not printed.


(defun foo (a b)
  (+ a b))

(define-condition not-a-number (optimization-failure-note)
  ((form :initarg :form :reader form))
  (:report (lambda (c s)
             (format s "~S is not a number" (form c)))))

(define-compiler-macro foo (&whole form a b &environment env)
  (with-notes (form env)
    (unless (numberp a)
      (signal 'not-a-number :form a))
    (unless (numberp b)
      (signal 'not-a-number :form b))
    (return-from foo (+ a b))))

(defun bar (a b) (foo a b))
; Compiler-macro of FOO is unable to optimize
;   (FOO A B)
; because:
;
;   A is not a number

(defun bar (a b)
  (declare (muffle not-a-number)) ; no note printed
  (foo a b))

(disassemble 'bar)
; disassembly for BAR
; Size: 29 bytes. Origin: #x52DB5C53                          ; BAR
; 53:       498B4510         MOV RAX, [R13+16]                ; thread.binding-stack-pointer
; 57:       488945F8         MOV [RBP-8], RAX
; 5B:       488BD6           MOV RDX, RSI
; 5E:       488BFB           MOV RDI, RBX
; 61:       B904000000       MOV ECX, 4
; 66:       FF7508           PUSH QWORD PTR [RBP+8]
; 69:       E9F42F66FD       JMP #x50418C62                   ; #<FDEFN FOO>
; 6E:       CC10             INT3 16                          ; Invalid argument count trap

(defun baz () (foo 4 5))

(disassemble 'baz)
; disassembly for BAZ
; Size: 21 bytes. Origin: #x52DB5CEC                          ; BAZ
; CEC:       498B4510         MOV RAX, [R13+16]               ; thread.binding-stack-pointer
; CF0:       488945F8         MOV [RBP-8], RAX
; CF4:       BA12000000       MOV EDX, 18
; CF9:       488BE5           MOV RSP, RBP
; CFC:       F8               CLC
; CFD:       5D               POP RBP
; CFE:       C3               RET
; CFF:       CC10             INT3 16                         ; Invalid argument count trap

DOCUMENTATION

*muffled-notes-type*

Variable
Default Value: NIL

Bound to a type. Notes that are of type given by the value of this variable will not be printed. Example:

The compile time value of this variable is OR-ed with the muffle declarations to decide which notes to muffle.

muffle

Function: (muffle note)

Do not print this note. As a declaration, this takes in type specifiers as arguments.

note

Condition

optimization-failure-note

Condition

with-notes

Macro: (with-notes
        (form env &key (name) (unwind-on-signal t) (other-conditions NIL)
         (per-line-prefix ; ) (optimization-note-condition t))
        &body body)

A macro to readably signal compiler-macro-notes:note for end-users:


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 compiler-macro-notes

Author

Shubhamkar B. Ayare

License

MIT

Description

Provides a macro and some conditions for use within macros and compiler-macros.

Version

0.2.0

Dependencies
Source

compiler-macro-notes.asd (file)

Components

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 compiler-macro-notes.asd

Location

compiler-macro-notes.asd

Systems

compiler-macro-notes (system)


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

3.1.2 compiler-macro-notes/package.lisp

Parent

compiler-macro-notes (system)

Location

package.lisp

Packages

compiler-macro-notes


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

3.1.3 compiler-macro-notes/notes.lisp

Dependency

package.lisp (file)

Parent

compiler-macro-notes (system)

Location

notes.lisp

Exported Definitions
Internal Definitions

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

3.1.4 compiler-macro-notes/with-notes.lisp

Dependency

notes.lisp (file)

Parent

compiler-macro-notes (system)

Location

with-notes.lisp

Exported Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 compiler-macro-notes

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 Special variables

Special Variable: *muffled-notes-type*

Bound to a type. Notes that are of type given by the value of this variable will not be printed.
Example:
- No notes will be printed if values is T.
- Optimization notes will not be printed if values is COMPILER-MACRO-NOTES:OPTIMIZATION-FAILURE-NOTE

The compile time value of this variable is OR-ed with the MUFFLE declarations to decide which notes to muffle.

Package

compiler-macro-notes

Source

with-notes.lisp (file)


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

5.1.2 Macros

Macro: with-notes (FORM ENV &key NAME UNWIND-ON-SIGNAL OTHER-CONDITIONS PER-LINE-PREFIX OPTIMIZATION-NOTE-CONDITION) &body BODY

A macro to readably signal COMPILER-MACRO-NOTES:NOTE for end-users:
- Expects ENV to evaluate to an environment suitable for passing to CL-ENVIRONMENTS.CLTL2:DEFINE-DECLARATION
- BODY is surrounded by a (BLOCK WITH-NOTES ...) on the outside
- Further, WITH-NOTES also wraps the BODY in an UNWIND-PROTECT and prints the conditions that were signalled before exiting. If UNWIND-ON-SIGNAL is non-NIL, then returns FORM if a condition was signalled, else if no condition was signalled returns the (primary) return value of BODY.
- If UNWIND-ON-SIGNAL is NIL, surrounds BODY in a HANDLER-BIND and prints all the compiler notes that were signalled. If non-NIL, prints only the first signalled note.
- OPTIMIZATION-FAILURE-NOTEs are printed only if OPTIMIZATION-NOTE-CONDITION form evaluates to non-NIL: OPTIMIZATION-NOTE-CONDITION is expected to be a form.
- OTHER-CONDITIONS is a type-specifier that indicates which other conditions should be reported.
- If the user code in BODY does result in an expansion, then it is expected to avoid performing a nonlocal exit to a place outside WITH-NOTES. Not
doing so could result in an incorrect print of the expansion paths.

Package

compiler-macro-notes

Source

with-notes.lisp (file)


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

5.1.3 Functions

Function: muffle NOTE

Do not print this NOTE.
As a declaration, this takes in type specifiers as arguments.

Package

compiler-macro-notes

Source

notes.lisp (file)


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

5.1.4 Conditions

Condition: note ()
Package

compiler-macro-notes

Source

notes.lisp (file)

Direct superclasses

condition (condition)

Direct subclasses

optimization-failure-note (condition)

Direct methods
Direct slots
Slot: datum
Initargs

:datum

Readers

datum (generic function)

Slot: args
Initargs

:args

Readers

args (generic function)

Slot: muffled-p
Initform

(quote nil)

Readers

muffled-p (generic function)

Writers

(setf muffled-p) (generic function)

Condition: optimization-failure-note ()
Package

compiler-macro-notes

Source

notes.lisp (file)

Direct superclasses

note (condition)


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

5.2 Internal definitions


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

5.2.1 Generic functions

Generic Function: args CONDITION
Package

compiler-macro-notes

Methods
Method: args (CONDITION note)
Source

notes.lisp (file)

Generic Function: datum CONDITION
Package

compiler-macro-notes

Methods
Method: datum (CONDITION note)
Source

notes.lisp (file)

Generic Function: muffled-p CONDITION
Generic Function: (setf muffled-p) NEW-VALUE CONDITION
Package

compiler-macro-notes

Methods
Method: muffled-p (CONDITION note)
Method: (setf muffled-p) NEW-VALUE (CONDITION note)
Source

notes.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
compiler-macro-notes.asd: The compiler-macro-notes․asd file
compiler-macro-notes/notes.lisp: The compiler-macro-notes/notes․lisp file
compiler-macro-notes/package.lisp: The compiler-macro-notes/package․lisp file
compiler-macro-notes/with-notes.lisp: The compiler-macro-notes/with-notes․lisp file

F
File, Lisp, compiler-macro-notes.asd: The compiler-macro-notes․asd file
File, Lisp, compiler-macro-notes/notes.lisp: The compiler-macro-notes/notes․lisp file
File, Lisp, compiler-macro-notes/package.lisp: The compiler-macro-notes/package․lisp file
File, Lisp, compiler-macro-notes/with-notes.lisp: The compiler-macro-notes/with-notes․lisp file

L
Lisp File, compiler-macro-notes.asd: The compiler-macro-notes․asd file
Lisp File, compiler-macro-notes/notes.lisp: The compiler-macro-notes/notes․lisp file
Lisp File, compiler-macro-notes/package.lisp: The compiler-macro-notes/package․lisp file
Lisp File, compiler-macro-notes/with-notes.lisp: The compiler-macro-notes/with-notes․lisp file

Jump to:   C   F   L  

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

A.2 Functions

Jump to:   (  
A   D   F   G   M   W  
Index Entry  Section

(
(setf muffled-p): Internal generic functions
(setf muffled-p): Internal generic functions

A
args: Internal generic functions
args: Internal generic functions

D
datum: Internal generic functions
datum: Internal generic functions

F
Function, muffle: Exported functions

G
Generic Function, (setf muffled-p): Internal generic functions
Generic Function, args: Internal generic functions
Generic Function, datum: Internal generic functions
Generic Function, muffled-p: Internal generic functions

M
Macro, with-notes: Exported macros
Method, (setf muffled-p): Internal generic functions
Method, args: Internal generic functions
Method, datum: Internal generic functions
Method, muffled-p: Internal generic functions
muffle: Exported functions
muffled-p: Internal generic functions
muffled-p: Internal generic functions

W
with-notes: Exported macros

Jump to:   (  
A   D   F   G   M   W  

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

A.3 Variables

Jump to:   *  
A   D   M   S  
Index Entry  Section

*
*muffled-notes-type*: Exported special variables

A
args: Exported conditions

D
datum: Exported conditions

M
muffled-p: Exported conditions

S
Slot, args: Exported conditions
Slot, datum: Exported conditions
Slot, muffled-p: Exported conditions
Special Variable, *muffled-notes-type*: Exported special variables

Jump to:   *  
A   D   M   S  

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

A.4 Data types

Jump to:   C   N   O   P   S  
Index Entry  Section

C
compiler-macro-notes: The compiler-macro-notes system
compiler-macro-notes: The compiler-macro-notes package
Condition, note: Exported conditions
Condition, optimization-failure-note: Exported conditions

N
note: Exported conditions

O
optimization-failure-note: Exported conditions

P
Package, compiler-macro-notes: The compiler-macro-notes package

S
System, compiler-macro-notes: The compiler-macro-notes system

Jump to:   C   N   O   P   S