From 6041a600e27fd241910edb6760ddeaaabf768b1b Mon Sep 17 00:00:00 2001 From: Chris Hanson Date: Wed, 10 Jan 2018 23:24:10 -0800 Subject: [PATCH] Remove documentation for now-obsolete generic-procedure dispatch. --- doc/ref-manual/procedures.texi | 192 +-------------------------------- doc/ref-manual/scheme.texinfo | 7 -- 2 files changed, 1 insertion(+), 198 deletions(-) diff --git a/doc/ref-manual/procedures.texi b/doc/ref-manual/procedures.texi index c7474d9e3..9a2345708 100644 --- a/doc/ref-manual/procedures.texi +++ b/doc/ref-manual/procedures.texi @@ -58,7 +58,6 @@ reasons, and may eventually change. * Primitive Procedures:: * Continuations:: * Application Hooks:: -* Generic Dispatch:: @end menu @node Procedure Operations, Arity, Procedures, Procedures @@ -455,7 +454,7 @@ is called must be a multiple-value continuation that was created by there are @var{object}s. @end deffn -@node Application Hooks, Generic Dispatch, Continuations, Procedures +@node Application Hooks, , Continuations, Procedures @section Application Hooks @cindex application hook (defn) @@ -540,192 +539,3 @@ Returns the extra component of @var{entity}. Changes the extra component of @var{entity} to be @var{object}. Returns an unspecified value. @end deffn - -@node Generic Dispatch, , Application Hooks, Procedures -@section Generic Dispatch - -@cindex generic procedure -@cindex procedure, generic -MIT/GNU Scheme provides a generic dispatch mechanism that can choose -an action to take based on the types of a set of objects. Performance -is guaranteed by the use of a hash-based method cache. - -This is @emph{not} an object-oriented programming system, although it -can provide the basis for such systems. The difference is that the -generic dispatch doesn't have any model for the relationship between -object types. Instead, there is a flat space of types and methods are -selected by procedural examination of the given operand types. - -@menu -* Generic Procedures:: -* Method Generators:: -* Dispatch Tags:: -@end menu - -@node Generic Procedures, Method Generators, Generic Dispatch, Generic Dispatch -@subsection Generic Procedures - -@cindex method, of generic procedure -The core of the dispatch mechanism is the @dfn{generic procedure}. -This is a procedure that is called in the usual way, but which -dispatches to a particular @dfn{method} based on the types of its -arguments. - -@deffn procedure make-generic-procedure arity [name] -Returns a new generic procedure accepting @var{arity}. @var{Arity} -must specify a minimum of one argument. - -@var{Name} is used for debugging: it is a symbol that has no role in -the semantics of the generic procedure. @var{Name} may be @code{#f} -to indicate that the generic procedure is anonymous. If @var{name} is -not specified, it defaults to @samp{#f}. - -Examples: - -@lisp -(define foo-bar (make-generic-procedure 2 'bar)) - -(define foo-baz (make-generic-procedure '(1 . 2) 'foo-baz)) - -(define foo-mum (make-generic-procedure '(1 . #f))) -@end lisp -@end deffn - -@deffn procedure generic-procedure? object -Returns @samp{#t} if @var{object} is a generic procedure, -and @samp{#f} otherwise. -@end deffn - -@deffn procedure generic-procedure-arity generic -Returns the arity of @var{generic}, as given to -@code{make-generic-procedure}. -@end deffn - -@deffn procedure generic-procedure-name generic -Returns the name of @var{generic}, as given to -@code{make-generic-procedure}. -@end deffn - -@deffn procedure generic-procedure-applicable? generic operands -Returns @samp{#t} if @var{generic} is applicable to @var{operands} -(which must be a list of objects), and @samp{#f} otherwise. -@end deffn - -@deffn {condition type} condition-type:no-applicable-methods operator operands -This condition type is signalled when a generic procedure is applied -and there are no applicable methods for the given operands. The condition's -@var{operator} field contains the generic procedure and the -@var{operands} field contains the given operands. -@end deffn - -@deffn {condition type} condition-type:extra-applicable-methods operator operands -This condition type is signalled when a generic procedure is applied -and there are more than one applicable methods for the given operands. -The condition's @var{operator} field contains the generic procedure -and the @var{operands} field contains the given operands. -@end deffn - -@node Method Generators, Dispatch Tags, Generic Procedures, Generic Dispatch -@subsection Method Generators - -Generic-procedure methods are dynamically chosen by @dfn{generators}, -which are procedures of two arguments. Each generic procedure has a -set of associated generators. Whenever the procedure is applied, each -associated generator is applied to two arguments: the generic -procedure and a list of the dispatch tags for the operands. The -return value from the generator is either a @dfn{method} (a procedure -accepting that number of arguments) or @samp{#f}. In order for the -application to succeed, exactly one of the generic procedure's -generators must return a method. - -Once a method has been chosen, it is cached. A subsequent call to the -generic procedure with operands of the same types will reuse that -cached method. Consequently, it is important that generators be -@dfn{functional}: they must always compute the same value from the -same arguments. - -@deffn procedure add-generic-procedure-generator generic generator -Adds @var{generator} to @var{generic}'s set of generators and returns -an unspecified value. -@end deffn - -@deffn procedure remove-generic-procedure-generator generic generator -Removes @var{generator} from @var{generic}'s set of generators and -returns an unspecified value. -@end deffn - -@deffn procedure remove-generic-procedure-generators generic tags -Calls each of @var{generic}'s set of generators on @var{tags} and -removes each generator that returns a method. Returns an unspecified -value. -@end deffn - -@deffn procedure generic-procedure-generator-list generic -Returns a list of @var{generic}'s generators. -@end deffn - -As a convenience, each generic procedure can have a @dfn{default -generator}, which is called only when all of the other generators have -returned @samp{#f}. When created, a generic procedure has no default -generator. - -@deffn procedure generic-procedure-default-generator generic -Returns @var{generic}'s default generator. -@end deffn - -@deffn procedure set-generic-procedure-default-generator! generic generator -Sets @var{generic}'s default generator to @var{generator} and returns -an unspecified value. -@end deffn - -@node Dispatch Tags, , Method Generators, Generic Dispatch -@subsection Dispatch Tags - -@cindex dispatch tag -@cindex tag, dispatch -A dispatch tag is an object that represents the ``type'' of an -object, for the purposes of generic dispatch. Every object has an -associated dispatch tag. Built-in objects like pairs or booleans have -predefined tags, while dynamically typed objects like records have -tags that are created as needed. - -@deffn procedure dispatch-tag object -Returns the dispatch tag for @var{object}. - -@example -@group -(dispatch-tag #f) @result{} #[dispatch-tag 17 (boolean)] -(dispatch-tag #t) @result{} #[dispatch-tag 17 (boolean)] -(dispatch-tag (list)) @result{} #[dispatch-tag 18 (null)] -(dispatch-tag (list 3)) @result{} #[dispatch-tag 19 (pair list)] -@end group -@end example -@end deffn - -@deffn procedure built-in-dispatch-tag name -Returns the built-in dispatch tag called @var{name}. @var{Name} must -be a symbol that is the name of a known built-in dispatch tag. - -@example -@group -(built-in-dispatch-tag 'boolean) @result{} #[dispatch-tag 17 (boolean)] -(built-in-dispatch-tag 'null) @result{} #[dispatch-tag 18 (null)] -(built-in-dispatch-tag 'pair) @result{} #[dispatch-tag 19 (pair list)] -(built-in-dispatch-tag 'list) @result{} #[dispatch-tag 19 (pair list)] -@end group -@end example -@end deffn - -@deffn procedure built-in-dispatch-tags -Returns a list of the built-in dispatch tags. -@end deffn - -@deffn procedure record-type-dispatch-tag record-type -Returns the dispatch tag associate with @var{record-type}. See -@xref{Records}, for more information about record types. -@end deffn - -@deffn procedure dispatch-tag? object -Returns @samp{#t} if @var{object} is a dispatch tag, and @samp{#f} -otherwise. -@end deffn diff --git a/doc/ref-manual/scheme.texinfo b/doc/ref-manual/scheme.texinfo index 596d60f16..bf99a2b9d 100644 --- a/doc/ref-manual/scheme.texinfo +++ b/doc/ref-manual/scheme.texinfo @@ -304,13 +304,6 @@ Procedures * Primitive Procedures:: * Continuations:: * Application Hooks:: -* Generic Dispatch:: - -Generic Dispatch - -* Generic Procedures:: -* Method Generators:: -* Dispatch Tags:: Environments -- 2.25.1