1.0.28.39: more error reporting tweakery

[sbcl.git] / doc / manual / efficiency.texinfo

diff --git a/doc/manual/efficiency.texinfo b/doc/manual/efficiency.texinfo
index de905ae..c03c733 100644 (file)
--- a/doc/manual/efficiency.texinfo
+++ b/doc/manual/efficiency.texinfo
@@ -4,11 +4,69 @@
 @cindex Efficiency
 
 @menu
+* Slot access::
 * Dynamic-extent allocation::
 * Modular arithmetic::
+* Global and Always-Bound variables::
 * Miscellaneous Efficiency Issues::
 @end menu
 
+@node  Slot access
+@comment  node-name,  next,  previous,  up
+@section Slot access
+@cindex Slot access
+
+@subsection Structure object slot access
+
+Structure slot accessors are efficient only if the compiler is able to
+open code them: compiling a call to a structure slot accessor before
+the structure is defined, declaring one @code{notinline}, or passing
+it as a functional argument to another function causes severe
+perfomance degradation.
+
+@subsection Standard object slot access
+
+The most efficient way to access a slot of a @code{standard-object} is
+by using @code{slot-value} with a constant slot name argument inside a
+@code{defmethod} body, where the variable holding the instance is a
+specializer parameter of the method and is never assigned to. The cost
+is roughly 1.6 times that of an open coded structure slot accessor.
+
+Second most efficient way is to use a CLOS slot accessor, or
+@code{slot-value} with a constant slot name argument, but in
+circumstances other than specified above. This may be up to 3 times as
+slow as the method described above.
+
+Example:
+
+@lisp
+(defclass foo () ((bar)))
+
+;; Fast: specializer and never assigned to
+(defmethod quux ((foo foo) new)
+  (let ((old (slot-value foo 'bar)))
+    (setf (slot-value foo 'bar) new)
+    old))
+
+;; Slow: not a specializer
+(defmethod quux ((foo foo) new)
+  (let* ((temp foo)
+         (old (slot-value temp 'bar)))
+    (setf (slot-value temp 'bar) new)
+    old))
+
+;; Slow: assignment to FOO
+(defmethod quux ((foo foo) new)
+  (let ((old (slot-value foo 'bar)))
+    (setf (slot-value foo 'bar) new)
+    (setf foo new)
+    old))
+@end lisp
+
+Note that when profiling code such as this, the first few calls to the
+generic function are not representative, as the dispatch mechanism is
+lazily set up during those calls.
+
 @node  Dynamic-extent allocation
 @comment  node-name,  next,  previous,  up
 @section Dynamic-extent allocation
@@ -67,7 +125,7 @@ call to the constructor is bound to a variable declared
 stack-allocated only on x86 and x86-64.
 
 @item
-all of the above when they appear as initial parts if another
+all of the above when they appear as initial parts of another
 stack-allocated object.
 
 @end itemize
@@ -166,6 +224,36 @@ argument. ``Good'' widths are 32 on HPPA, MIPS, PPC, Sparc and x86 and
 64 on Alpha.  While it is possible to support smaller widths as well,
 currently this is not implemented.
 
+@node  Global and Always-Bound variables
+@comment  node-name,  next,  previous,  up
+@section Global and Always-Bound variables
+
+@include macro-sb-ext-defglobal.texinfo
+
+@deftp {Declaration} sb-ext:global
+
+Syntax: @code{(sb-ext:global symbol*)}
+
+Only valid as a global proclamation.
+
+Specifies that the named symbols cannot be proclaimed or locally
+declared @code{special}. Proclaiming an already special or constant
+variable name as @code{global} signal an error. Allows more efficient
+value lookup in threaded environments in addition to expressing
+programmer intention.
+@end deftp
+
+@deftp {Declaration} sb-ext:always-bound
+
+Syntax: @code{(sb-ext:always-bound symbol*)}
+
+Only valid as a global proclamation.
+
+Specifies that the named symbols is always bound. Inhibits @code{makunbound}
+of the named symbols. Proclaiming an unbound symbol as @code{always-bound} signals
+an error. Allows compiler to elide boundness checks from value lookups.
+@end deftp
+
 @node  Miscellaneous Efficiency Issues
 @comment  node-name,  next,  previous,  up
 @section Miscellaneous Efficiency Issues