it still has quite a few. @xref{Contributed Modules}.
@menu
-* Things Which Might Be In The Next ANSI Standard::
+* 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 Things Which Might Be In The Next ANSI Standard
+@node Garbage Collection
@comment node-name, next, previous, up
-@section Things Which Might Be In The Next ANSI Standard
-
-SBCL provides extensive support for calling external C code,
-@ref{Foreign Function Interface}.
+@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 GCed (garbage
-collected). And ``finalization'' hooks are available to cause code to
-be executed when an object has been GCed.
-@c <!-- FIXME: Actually documenting these would be good.:-| -->
-
-SBCL supports @dfn{Gray streams}, user-overloadable CLOS classes whose
-instances can be used as Lisp streams (e.g. passed as the first
-argument to @code{format}). Additionally, the bundled contrib module
-@dfn{sb-simple-streams} implements a subset of the Franz Allegro
-simple-streams proposal.
-
-SBCL supports a MetaObject Protocol which is intended to be compatible
+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
-the abstract @code{metaobject} class is not present in the class
-hierarchy;
+@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
-the @code{standard-object} and @code{funcallable-standard-object}
-classes are disjoint;
-
+@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
-@code{compute-effective-method} only returns one value, not two;
-
+@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.
+
+@tindex funcallable-standard-object
+@tindex sb-mop:funcallable-standard-object
+Note that this requirement also applies to the class
+@code{sb-mop:funcallable-standard-object}, which has metaclass
+@code{sb-mop:funcallable-standard-class} rather than
+@code{standard-class} as AMOP specifies.
+
+@item
+the requirement that ``No portable class @math{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
+@code{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.
+
@item
-the system-supplied @code{:around} method for @code{compute-slots}
-specialized on @code{funcallable-standard-class} does not respect the
-requested order from a user-supplied primary method.
+@findex slot-value-using-class
+@findex sb-mop:slot-value-using-class
+@findex (setf slot-value-using-class)
+@findex (setf sb-mop:slot-value-using-class)
+@findex slot-boundp-using-class
+@findex sb-mop:slot-boundp-using-class
+specializations of the @code{new-value} argument to @code{(setf
+sb-mop:slot-value-using-class)} are not allowed: all user-defined
+methods must have a specializer of the class @code{t}.
+
+This prohibition is motivated by a separation of layers: the
+@code{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 @code{(setf
+slot-value-using-class)}, which permits optimization of @code{(setf
+slot-value-using-class)}'s discriminating function in the same manner as
+for @code{slot-value-using-class} and @code{slot-boundp-using-class}.
+
+Note that application code may specialize on the @code{new-value}
+argument of slot accessors.
+
+@item
+@findex defclass
+@findex ensure-class
+@findex ensure-class-using-class
+@findex sb-mop:ensure-class
+@findex sb-mop:ensure-class-using-class
+@findex find-class
+@findex class-name
+the class named by the @code{name} argument to @code{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 @code{ensure-class} in AMOP
+as the functional version of @code{defclass}, which has this behaviour;
+however, it is not consistent with the weaker requirement in AMOP, which
+states that any class found by @code{find-class}, no matter what its
+@code{class-name}, is redefined.
@end itemize
@include fun-sb-ext-posix-getenv.texinfo
+External programs can be run with @code{sb-ext:run-program}.
+
+@include fun-sb-ext-run-program.texinfo
+
+@include fun-sb-ext-process-p.texinfo
+
+@include fun-sb-ext-process-input.texinfo
+
+@include fun-sb-ext-process-output.texinfo
+
+@include fun-sb-ext-process-error.texinfo
+
+@include fun-sb-ext-process-alive-p.texinfo
+
+@include fun-sb-ext-process-status.texinfo
+
+@include fun-sb-ext-process-wait.texinfo
+
+@include fun-sb-ext-process-exit-code.texinfo
+
+@include fun-sb-ext-process-core-dumped.texinfo
+
+@include fun-sb-ext-process-close.texinfo
+
+@include fun-sb-ext-process-kill.texinfo
@node Customization Hooks for Users
@comment node-name, next, previous, up
@include fun-common-lisp-ed.texinfo
@include var-sb-ext-star-ed-functions-star.texinfo
-@node Tools To Help Developers
+@node Tools To Help Developers
@comment node-name, next, previous, up
@section Tools To Help Developers
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
@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. it is less important with modern
-generational garbage collectors.
+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
projects / sbcl.git / blobdiff