Lisp %var naming convention

Question

In the https://www.cliki.net/Naming+conventions page i read

low-level, fast, dangerous function, or Lisp system specific implementation of foo

Can someone translate this into again with perhaps an example of those contexts?

Answer 1

Take this function:

(defun add (x y)
  (+ x y))

which does general addition. It supports integers, floats, complex numbers and ratios as arguments - all the numeric types defined in Lisp.

However if you have:

(defun add (x y)
  (declare (fixnum x y) (optimize speed (safety 0) (debug 0)))
  (the fixnum (+ x y)))

this tells the compiler to optimize the function for fixnum values that fit in an assembly register. When you use an implementation that compiles down to assembly this results in very efficient code, as you can check with (disassemble (compile 'add)). For example in Allegro CL:

cl-user(10): (disassemble 'add)
;; disassembly of #<Function add>                                                                                                                                                                                                                 
;; formals: x y                                                                                                                                                                                                                                   

;; code start: #x10008ae4740:                                                                                                                                                                                                                     
   0: 48 01 f7       addq       rdi,rsi
   3: f8             clc
   4: 4c 8b 74 24 10 movq       r14,[rsp+16]
   9: c3             ret

However this faster code comes at the cost of not having any error checking: the code assumes you pass in 2 fixnum arguments, no more or less, and also you promise that the result will not overflow the fixnum range - so not e.g. (add most-positive-fixnum most-positive-fixnum).

If you break this promise by passing floats like (add 3.4 1.2) or only arg (add 3) you are asking for big trouble - this might corrupt data structures or even exit the Lisp.

The second function could be called %add-2-fixnums to signal it's special, not intended for general use but instead specialized for certain arguments, and callers need to be very careful.

Answer 2

The function without % is the general interface into some functionality and may even check its arguments. It then calls a low-level implementation.

The same function with the prefix % then might implement the functionality efficiently, even in a platform specific way.

If this function then uses a macro for even more specific low-level code generation, one might prefix the macro with %%.

these other cases can be seen, too:

• type specific functions
• inlined functions
• implementation specific functions
• very low-level code working near the Lisp implementation level
• Lisp assembly functions (functions written in inline assembler)

Example: If one checks for example the source code of Clozure Common Lisp, there is a lot of use of the % naming conventions.