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.  See Contributed Modules.

Reader Extensions
=================

SBCL supports extended package prefix syntax, which allows specifying an alternate package instead of *package* for the reader to use as the default package for interning symbols:

     <package-name>::<form-with-interning-into-package>

Example:

       'foo::(bar quux zot) == '(foo::bar foo::quux foo::zot)

Doesn't alter *package*: if foo::bar would cause a read-time package lock violation, so does foo::(bar).

Garbage Collection
==================

SBCL provides additional garbage collection functionality not specified by ANSI.

     [file var-sb-ext-star-after-gc-hooks-star.texinfo not included]
     [file fun-sb-ext-gc.texinfo not included]

Finalization
------------

Finalization allows code to be executed after an object has been garbage collected. This is useful for example for releasing foreign memory associated with a Lisp object.

     [file fun-sb-ext-finalize.texinfo not included]
     [file fun-sb-ext-cancel-finalization.texinfo not included]

Weak Pointers
-------------

Weak pointers allow references to objects to be maintained without keeping them from being garbage collected: useful for building caches among other things.

Hash tables can also have weak keys and values: see Hash Table Extensions.

     [file fun-sb-ext-make-weak-pointer.texinfo not included]
     [file fun-sb-ext-weak-pointer-value.texinfo not included]

Introspection and Tuning
------------------------

     [file var-sb-ext-star-gc-run-time-star.texinfo not included]
     [file fun-sb-ext-bytes-consed-between-gcs.texinfo not included]
     [file fun-sb-ext-dynamic-space-size.texinfo not included]
     [file fun-sb-ext-get-bytes-consed.texinfo not included]
     [file fun-sb-ext-gc-logfile.texinfo not included]
     [file fun-sb-ext-generation-average-age.texinfo not included]
     [file fun-sb-ext-generation-bytes-allocated.texinfo not included]
     [file fun-sb-ext-generation-bytes-consed-between-gcs.texinfo not included]
     [file fun-sb-ext-generation-minimum-age-before-gc.texinfo not included]
     [file fun-sb-ext-generation-number-of-gcs-before-promotion.texinfo not included]
     [file fun-sb-ext-generation-number-of-gcs.texinfo not included]

Metaobject Protocol
===================

AMOP Compatibility of 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:

  * 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.

  * The direct superclasses of sb-mop:funcallable-standard-object are (function standard-object), not (standard-object function).

     This is to ensure that the standard-object class is the last of the standardized classes before t appearing in the class precedence list of generic-function and standard-generic-function, as required by section 1.4.4.5 of the ANSI specification.

  * the arguments :declare and :declarations to ensure-generic-function are both accepted, with the leftmost argument defining the declarations to be stored and returned by generic-function-declarations.

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

  * although SBCL obeys the requirement in AMOP that validate-superclass should treat standard-class and funcallable-standard-class as compatible metaclasses, we impose an additional requirement at class finalization time: a class of metaclass funcallable-standard-class must have function in its superclasses, and a class of metaclass standard-class must not.

     After a class has been finalized, it is associated with a class prototype which is accessible by a standard mop function sb-mop:class-prototype.  The user can then ask whether this object is a function or not in several different ways: whether it is a function according to typep; whether its class-of is subtypep function, or whether 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:

          (defclass bad-object (funcallable-standard-object)
            ()
            (:metaclass standard-class))

          (defclass bad-funcallable-object (standard-object)
            ()
            (:metaclass funcallable-standard-class))

     The following definition is acceptable:

          (defclass mixin ()
            ((slot :initarg slot)))
          (defclass funcallable-object (funcallable-standard-object mixin)
            ()
            (:metaclass funcallable-standard-class))

     and leads to a class whose instances are funcallable and have one slot.

     Note that this requirement also applies to the class sb-mop:funcallable-standard-object, which has metaclass sb-mop:funcallable-standard-class rather than standard-class as AMOP specifies.

  * the requirement that ``No portable class C_p may inherit, by virtue of being a direct or indirect subclass of a specified class, any slot for which the name is a symbol accessible in the common-lisp-user package or exported by any package defined in the ANSI Common Lisp standard.'' is interpreted to mean that the standardized classes themselves should not have slots named by external symbols of public packages.

     The rationale behind the restriction is likely to be similar to the ANSI Common Lisp restriction on defining functions, variables and types named by symbols in the Common Lisp package: preventing two independent pieces of software from colliding with each other.

  * specializations of the new-value argument to (setf sb-mop:slot-value-using-class) are not allowed: all user-defined methods must have a specializer of the class t.

     This prohibition is motivated by a separation of layers: the slot-value-using-class family of functions is intended for use in implementing different and new slot allocation strategies, rather than in performing application-level dispatching.  Additionally, with this requirement, there is a one-to-one mapping between metaclass, class and slot-definition-class tuples and effective methods of (setf slot-value-using-class), which permits optimization of (setf slot-value-using-class)'s discriminating function in the same manner as for slot-value-using-class and slot-boundp-using-class.

     Note that application code may specialize on the new-value argument of slot accessors.

  * the class named by the name argument to ensure-class, if any, is only redefined if it is the proper name of that class; otherwise, a new class is created.

     This is consistent with the description of ensure-class in AMOP as the functional version of defclass, which has this behaviour; however, it is not consistent with the weaker requirement in AMOP, which states that any class found by find-class, no matter what its class-name, is redefined.

Metaobject Protocol Extensions
------------------------------

In addition, SBCL supports extensions to the Metaobject protocol from AMOP; at present, they are:

  * compile-time support for generating specializer metaobjects from specializer names in defmethod forms is provided by the make-method-specializers-form function, which returns a form which, when evaluated in the lexical environment of the defmethod, returns a list of specializer metaobjects.  This operator suffers from similar restrictions to those affecting make-method-lambda, namely that the generic function must be defined when the defmethod form is expanded, so that the correct method of make-method-specializers-form is invoked. The system-provided method on make-method-specializers-form generates a call to find-class for each symbol specializer name, and a call to intern-eql-specializer for each (eql X) specializer name.

  * run-time support for converting between specializer names and specializer metaobjects, mostly for the purposes of find-method, is provided by parse-specializer-using-class and unparse-specializer-using-class, which dispatch on their first argument, the generic function associated with a method with the given specializer.  The system-provided methods on those methods convert between classes and proper names and between lists of the form (eql X) and interned eql specializer objects.

  * distinguising unbound instance allocated slots from bound ones when using standard-instance-access and funcallable-standard-instance-access is possible by comparison to the constant +slot-unbound+.

Support For Unix
================

Command-line arguments
----------------------

The UNIX command line can be read from the variable sb-ext:*posix-argv*.

Querying the process environment
--------------------------------

The UNIX environment can be queried with the sb-ext:posix-getenv function.

     [file fun-sb-ext-posix-getenv.texinfo not included]

Running external programs
-------------------------

External programs can be run with sb-ext:run-program. (In SBCL versions prior to 1.0.13, sb-ext:run-program searched for executables in a manner somewhat incompatible with other languages.  As of this version, SBCL uses the system library routine execvp(3), and no longer contains the function, find-executable-in-search-path, which implemented the old search.  Users who need this function may find it in run-program.lisp versions 1.67 and earlier in SBCL's CVS repository here http://sbcl.cvs.sourceforge.net/sbcl/sbcl/src/code/run-program.lisp?view=log. However, we caution such users that this search routine finds executables that system library routines do not.)

     [file fun-sb-ext-run-program.texinfo not included]

When sb-ext:run-program is called with wait equal to NIL, an instance of class SB-EXT:PROCESS is returned.  The following functions are available for use with processes:

     [file fun-sb-ext-process-p.texinfo not included]

     [file fun-sb-ext-process-input.texinfo not included]

     [file fun-sb-ext-process-output.texinfo not included]

     [file fun-sb-ext-process-error.texinfo not included]

     [file fun-sb-ext-process-alive-p.texinfo not included]

     [file fun-sb-ext-process-status.texinfo not included]

     [file fun-sb-ext-process-wait.texinfo not included]

     [file fun-sb-ext-process-exit-code.texinfo not included]

     [file fun-sb-ext-process-core-dumped.texinfo not included]

     [file fun-sb-ext-process-close.texinfo not included]

     [file fun-sb-ext-process-kill.texinfo not included]

Customization Hooks for Users
=============================

The toplevel repl prompt may be customized, and the function that reads user input may be replaced completely.

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

     [file fun-common-lisp-require.texinfo not included]
     [file var-sb-ext-star-module-provider-functions-star.texinfo not included]

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

     [file fun-common-lisp-ed.texinfo not included]
     [file var-sb-ext-star-ed-functions-star.texinfo not included]

Conditions of type warning and style-warning are sometimes signaled at runtime, especially during execution of Common Lisp defining forms such as defun, defmethod, etc.  To muffle these warnings at runtime, SBCL provides a variable sb-ext:*muffled-warnings*:

     [file var-sb-ext-star-muffled-warnings-star.texinfo not included]

Tools To Help Developers
========================

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

The debugger supports a number of options. Its documentation is accessed by typing help at the debugger prompt. See Debugger.

Documentation for inspect is accessed by typing help at the inspect prompt.

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 sb-ext:resolve-conflict restart should be invoked with one argument, which should be a member of the list returned by the condition accessor sb-ext:name-conflict-symbols.

Hash Table Extensions
=====================

Hash table extensions supported by SBCL are all controlled by keyword arguments to make-hash-table.

     [file fun-common-lisp-make-hash-table.texinfo not included]

     [file macro-sb-ext-define-hash-table-test.texinfo not included]

     [file macro-sb-ext-with-locked-hash-table.texinfo not included]

     [file fun-sb-ext-hash-table-synchronized-p.texinfo not included]

     [file fun-sb-ext-hash-table-weakness.texinfo not included]

Miscellaneous Extensions
========================

     [file fun-sb-ext-array-storage-vector.texinfo not included]
     [file fun-sb-ext-delete-directory.texinfo not included]
     [file fun-sb-ext-get-time-of-day.texinfo not included]
     [file fun-sb-ext-seed-random-state.texinfo not included]
     [file macro-sb-ext-wait-for.texinfo not included]

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 src/code/gc.lisp and bring it up on the developers' mailing list.

SBCL has various hooks inherited from CMUCL, like 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.

Efficiency Hacks
================

The 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.

     [file fun-sb-ext-purify.texinfo not included]

The 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.

     [file special-operator-sb-ext-truly-the.texinfo not included]

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