@node  Beyond the ANSI Standard
@comment  node-name,  next,  previous,  up
@chapter Beyond the ANSI Standard

SBCL is derived from CMUCL, which implements many extensions to the
ANSI standard. SBCL doesn't support as many extensions as CMUCL, but
it still has quite a few.  @xref{Contributed Modules}.

@menu
* Garbage Collection::          
* Metaobject Protocol::         
* Support For Unix::            
* Customization Hooks for Users::  
* Tools To Help Developers::    
* Resolution of Name Conflicts::  
* Stale Extensions::            
* Efficiency Hacks::            
@end menu

@node  Garbage Collection
@comment  node-name,  next,  previous,  up
@section Garbage Collection

SBCL provides additional garbage collection functionality not
specified by ANSI. Weak pointers allow references to objects to be
maintained without keeping them from being garbage collected, and
``finalization'' hooks are available to cause code to be executed when
an object has been garbage collected. Additionally users can specify
their own cleanup actions to be executed with garbage collection.

@include fun-sb-ext-finalize.texinfo
@include fun-sb-ext-cancel-finalization.texinfo
@include fun-sb-ext-make-weak-pointer.texinfo
@include fun-sb-ext-weak-pointer-value.texinfo
@include var-sb-ext-star-after-gc-hooks-star.texinfo

@node Metaobject Protocol
@comment  node-name,  next,  previous,  up
@section Metaobject Protocol

SBCL supports a metaobject protocol which is intended to be compatible
with AMOP; present exceptions to this (as distinct from current bugs)
are:

@itemize
  
@item
@findex compute-effective-method
@findex sb-mop:compute-effective-method
@code{compute-effective-method} only returns one value, not two.

There is no record of what the second return value was meant to
indicate, and apparently no clients for it.
  
@item
@findex ensure-generic-function
@findex generic-function-declarations
@findex sb-mop:generic-function-declarations
the arguments @code{:declare} and @code{:declarations} to
@code{ensure-generic-function} are both accepted, with the leftmost
argument defining the declarations to be stored and returned by
@code{generic-function-declarations}.

Where AMOP specifies @code{:declarations} as the keyword argument to
@code{ensure-generic-function}, the Common Lisp standard specifies
@code{:declare}.  Portable code should use @code{:declare}.

@item
@findex validate-superclass
@findex finalize-inheritance
@findex sb-mop:validate-superclass
@findex sb-mop:finalize-inheritance
@tindex standard-class
@tindex funcallable-standard-class
@tindex sb-mop:funcallable-standard-class
@tindex function
@findex sb-mop:class-prototype
@findex class-prototype
although SBCL obeys the requirement in AMOP for
@code{validate-superclass} for @code{standard-class} and
@code{funcallable-standard-class} to be compatible metaclasses, we
impose an additional requirement at class finalization time: a class
of metaclass @code{funcallable-standard-class} must have
@code{function} in its superclasses, and a class of metaclass
@code{standard-class} must not.

@findex typep
@findex class-of
@findex subtypep
At class finalization, a class prototype which is accessible by a
standard mop function @code{sb-mop:class-prototype}.  The user can
then ask whether this object is a @code{function} or not in several
different ways: whether it is a function according to @code{typep};
whether its @code{class-of} is @code{subtypep} @code{function}, or
whether @code{function} appears in the superclasses of the class.  The
additional consistency requirement comes from the desire to make all
of these answers the same.

The following class definitions are bad, and will lead to errors
either immediately or if an instance is created:
@lisp
(defclass bad-object (funcallable-standard-object)
  ()
  (:metaclass standard-class))
@end lisp
@lisp
(defclass bad-funcallable-object (standard-object)
  ()
  (:metaclass funcallable-standard-class))
@end lisp
The following definition is acceptable:
@lisp
(defclass mixin ()
  ((slot :initarg slot)))
(defclass funcallable-object (funcallable-standard-object mixin)
  ()
  (:metaclass funcallable-standard-class))
@end lisp
and leads to a class whose instances are funcallable and have one slot.

@end itemize

@node  Support For Unix
@comment  node-name,  next,  previous,  up
@section Support For Unix

The UNIX command line can be read from the variable
@code{sb-ext:*posix-argv*}. The UNIX environment can be queried with
the @code{sb-ext:posix-getenv} function.

@include fun-sb-ext-posix-getenv.texinfo


@node  Customization Hooks for Users
@comment  node-name,  next,  previous,  up
@section Customization Hooks for Users

The toplevel repl prompt may be customized, and the function
that reads user input may be replaced completely.
@c <!-- FIXME but I don't currently remember how -->

The behaviour of @code{require} when called with only one argument is
implementation-defined.  In SBCL, @code{require} behaves in the
following way:

@include fun-common-lisp-require.texinfo
@include var-sb-ext-star-module-provider-functions-star.texinfo

Although SBCL does not provide a resident editor, the @code{ed}
function can be customized to hook into user-provided editing
mechanisms as follows:

@include fun-common-lisp-ed.texinfo
@include var-sb-ext-star-ed-functions-star.texinfo

@node Tools To Help Developers
@comment  node-name,  next,  previous,  up
@section Tools To Help Developers

SBCL provides a profiler and other extensions to the ANSI @code{trace}
facility.  For more information, see @ref{Macro common-lisp:trace}.

The debugger supports a number of options. Its documentation is
accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.

Documentation for @code{inspect} is accessed by typing @kbd{help} at
the @code{inspect} prompt.

@node Resolution of Name Conflicts
@section Resolution of Name Conflicts

The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
packages be resolvable in favour of any of the conflicting symbols.  In
the interactive debugger, this is achieved by prompting for the symbol
in whose favour the conflict should be resolved; for programmatic use,
the @code{sb-ext:resolve-conflict} restart should be invoked with one
argument, which should be a member of the list returned by the condition
accessor @code{sb-ext:name-conflict-symbols}.

@node Stale Extensions
@comment  node-name,  next,  previous,  up
@section Stale Extensions

SBCL has inherited from CMUCL various hooks to allow the user to
tweak and monitor the garbage collection process. These are somewhat
stale code, and their interface might need to be cleaned up. If you
have urgent need of them, look at the code in @file{src/code/gc.lisp}
and bring it up on the developers' mailing list.

SBCL has various hooks inherited from CMUCL, like
@code{sb-ext:float-denormalized-p}, to allow a program to take
advantage of IEEE floating point arithmetic properties which aren't
conveniently or efficiently expressible using the ANSI standard. These
look good, and their interface looks good, but IEEE support is
slightly broken due to a stupid decision to remove some support for
infinities (because it wasn't in the ANSI spec and it didn't occur to
me that it was in the IEEE spec). If you need this stuff, take a look
at the code and bring it up on the developers' mailing
list.


@node  Efficiency Hacks
@comment  node-name,  next,  previous,  up
@section Efficiency Hacks

The @code{sb-ext:purify} function causes SBCL first to collect all
garbage, then to mark all uncollected objects as permanent, never again
attempting to collect them as garbage. This can cause a large increase
in efficiency when using a primitive garbage collector, or a more
moderate increase in efficiency when using a more sophisticated garbage
collector which is well suited to the program's memory usage pattern. It
also allows permanent code to be frozen at fixed addresses, a
precondition for using copy-on-write to share code between multiple Lisp
processes.  This is less important with modern generational garbage
collectors, but not all SBCL platforms use such a garbage collector.

@include fun-sb-ext-purify.texinfo

The @code{sb-ext:truly-the} special form declares the type of the
result of the operations, producing its argument; the declaration is
not checked. In short: don't use it.

@include special-operator-sb-ext-truly-the.texinfo

The @code{sb-ext:freeze-type} declaration declares that a
type will never change, which can make type testing
(@code{typep}, etc.) more efficient for structure types.

The @code{sb-ext:constant-function} declaration specifies
that a function will always return the same value for the same
arguments, which may allow the compiler to optimize calls
to it. This is appropriate for functions like @code{sqrt}, but
is @emph{not} appropriate for functions like @code{aref},
which can change their return values when the underlying data are
changed.
@c <!-- FIXME: This declaration does not seem to be supported in the 
@c      current compiler. -->
