a0bffa205c2bd842a36ea94d341b456110083a42
[sbcl.git] / doc / manual / beyond-ansi.texinfo
1 @node  Beyond the ANSI Standard
2 @comment  node-name,  next,  previous,  up
3 @chapter Beyond the ANSI Standard
4
5 SBCL is derived from CMUCL, which implements many extensions to the
6 ANSI standard. SBCL doesn't support as many extensions as CMUCL, but
7 it still has quite a few.  @xref{Contributed Modules}.
8
9 @menu
10 * Things Which Might Be In The Next ANSI Standard::  
11 * Support For Unix::            
12 * Customization Hooks for Users::  
13 * Tools To Help Developers::    
14 * Resolution of Name Conflicts::
15 * Stale Extensions::            
16 * Efficiency Hacks::            
17 @end menu
18
19 @node  Things Which Might Be In The Next ANSI Standard
20 @comment  node-name,  next,  previous,  up
21 @section Things Which Might Be In The Next ANSI Standard
22
23 SBCL provides extensive support for calling external C code,
24 @ref{Foreign Function Interface}.
25
26 SBCL provides additional garbage collection functionality not
27 specified by ANSI. Weak pointers allow references to objects to be
28 maintained without keeping them from being GCed (garbage
29 collected). And ``finalization'' hooks are available to cause code to
30 be executed when an object has been GCed.
31 @c <!-- FIXME: Actually documenting these would be good.:-| -->
32
33 SBCL supports @dfn{Gray streams}, user-overloadable CLOS classes whose
34 instances can be used as Lisp streams (e.g. passed as the first
35 argument to @code{format}).  Additionally, the bundled contrib module
36 @dfn{sb-simple-streams} implements a subset of the Franz Allegro
37 simple-streams proposal.
38
39 SBCL supports a MetaObject Protocol which is intended to be compatible
40 with AMOP; present exceptions to this (as distinct from current bugs)
41 are:
42
43 @itemize
44   
45 @item
46 the abstract @code{metaobject} class is not present in the class
47 hierarchy;
48   
49 @item
50 the @code{standard-object} and @code{funcallable-standard-object}
51 classes are disjoint;
52   
53 @item
54 @code{compute-effective-method} only returns one value, not two;
55   
56 @item
57 the system-supplied @code{:around} method for @code{compute-slots}
58 specialized on @code{funcallable-standard-class} does not respect the
59 requested order from a user-supplied primary method.
60
61 @end itemize
62
63 @node  Support For Unix
64 @comment  node-name,  next,  previous,  up
65 @section Support For Unix
66
67 The UNIX command line can be read from the variable
68 @code{sb-ext:*posix-argv*}. The UNIX environment can be queried with
69 the @code{sb-ext:posix-getenv} function.
70
71 @include fun-sb-ext-posix-getenv.texinfo
72
73
74 @node  Customization Hooks for Users
75 @comment  node-name,  next,  previous,  up
76 @section Customization Hooks for Users
77
78 The toplevel repl prompt may be customized, and the function
79 that reads user input may be replaced completely.
80 @c <!-- FIXME but I don't currently remember how -->
81
82 The behaviour of @code{require} when called with only one argument is
83 implementation-defined.  In SBCL, @code{require} behaves in the
84 following way:
85
86 @include fun-common-lisp-require.texinfo
87 @include var-sb-ext-star-module-provider-functions-star.texinfo
88
89 Although SBCL does not provide a resident editor, the @code{ed}
90 function can be customized to hook into user-provided editing
91 mechanisms as follows:
92
93 @include fun-common-lisp-ed.texinfo
94 @include var-sb-ext-star-ed-functions-star.texinfo
95
96 @node Tools To Help Developers
97 @comment  node-name,  next,  previous,  up
98 @section Tools To Help Developers
99
100 SBCL provides a profiler and other extensions to the ANSI @code{trace}
101 facility.  For more information, see @ref{Macro common-lisp:trace}.
102
103 The debugger supports a number of options. Its documentation is
104 accessed by typing @kbd{help} at the debugger prompt. @xref{Debugger}.
105
106 Documentation for @code{inspect} is accessed by typing @kbd{help} at
107 the @code{inspect} prompt.
108
109 @node Resolution of Name Conflicts
110 @section Resolution of Name Conflicts
111
112 The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
113 packages be resolvable in favour of any of the conflicting symbols.  In
114 the interactive debugger, this is achieved by prompting for the symbol
115 in whose favour the conflict should be resolved; for programmatic use,
116 the @code{sb-ext:resolve-conflict} restart should be invoked with one
117 argument, which should be a member of the list returned by the condition
118 accessor @code{sb-ext:name-conflict-symbols}.
119
120 @node Stale Extensions
121 @comment  node-name,  next,  previous,  up
122 @section Stale Extensions
123
124 SBCL has inherited from CMUCL various hooks to allow the user to
125 tweak and monitor the garbage collection process. These are somewhat
126 stale code, and their interface might need to be cleaned up. If you
127 have urgent need of them, look at the code in @file{src/code/gc.lisp}
128 and bring it up on the developers' mailing list.
129
130 SBCL has various hooks inherited from CMUCL, like
131 @code{sb-ext:float-denormalized-p}, to allow a program to take
132 advantage of IEEE floating point arithmetic properties which aren't
133 conveniently or efficiently expressible using the ANSI standard. These
134 look good, and their interface looks good, but IEEE support is
135 slightly broken due to a stupid decision to remove some support for
136 infinities (because it wasn't in the ANSI spec and it didn't occur to
137 me that it was in the IEEE spec). If you need this stuff, take a look
138 at the code and bring it up on the developers' mailing
139 list.
140
141
142 @node  Efficiency Hacks
143 @comment  node-name,  next,  previous,  up
144 @section Efficiency Hacks
145
146 The @code{sb-ext:purify} function causes SBCL first to collect all
147 garbage, then to mark all uncollected objects as permanent, never
148 again attempting to collect them as garbage. This can cause a large
149 increase in efficiency when using a primitive garbage collector, or a
150 more moderate increase in efficiency when using a more sophisticated
151 garbage collector which is well suited to the program's memory usage
152 pattern. It also allows permanent code to be frozen at fixed
153 addresses, a precondition for using copy-on-write to share code
154 between multiple Lisp processes. it is less important with modern
155 generational garbage collectors.
156
157 @include fun-sb-ext-purify.texinfo
158
159 The @code{sb-ext:truly-the} special form declares the type of the
160 result of the operations, producing its argument; the declaration is
161 not checked. In short: don't use it.
162
163 @include special-operator-sb-ext-truly-the.texinfo
164
165 The @code{sb-ext:freeze-type} declaration declares that a
166 type will never change, which can make type testing
167 (@code{typep}, etc.) more efficient for structure types.
168
169 The @code{sb-ext:constant-function} declaration specifies
170 that a function will always return the same value for the same
171 arguments, which may allow the compiler to optimize calls
172 to it. This is appropriate for functions like @code{sqrt}, but
173 is @emph{not} appropriate for functions like @code{aref},
174 which can change their return values when the underlying data are
175 changed.
176 @c <!-- FIXME: This declaration does not seem to be supported in the 
177 @c      current compiler. -->