doc/beyond-ansi.sgml

   1 <chapter id="beyond-ansi"><title>Beyond The &ANSI; Standard</>
   2
   3 <para>&SBCL; is mostly an implementation of the &ANSI; standard for
   4 Common Lisp. However, there's some important behavior which extends
   5 or clarifies the standard, and various behavior which outright
   6 violates the standard.
   7 </para>
   8
   9 <sect1 id="non-conformance"><title>Non-Conformance With The &ANSI; Standard</>
  10
  11 <para>
  12 Essentially every type of non-conformance is considered a bug.
  13 (The exceptions involve internal inconsistencies in the standard.)
  14 In &SBCL; 0.7.6, the master record of known bugs is in
  15 the <filename>BUGS</> file in the distribution.
  16 Some highlight information about bugs may also be found in the
  17 manual page. The recommended way to report bugs is through the sbcl-help or
  18 sbcl-devel mailings lists.
  19 </para>
  20
  21 </sect1>
  22
  23 <sect1 id="idiosyncrasies"><title>Idiosyncrasies</>
  24
  25 <para>The information in this section describes some of the ways
  26 that &SBCL; deals with choices that the &ANSI; standard
  27 leaves to the implementation.</para>
  28
  29 <para>Declarations are generally treated as assertions. This general
  30 principle, and its implications, and the bugs which still keep the
  31 compiler from quite satisfying this principle, are discussed in the
  32 <link linkend="compiler">chapter on the compiler</link>.</para>
  33
  34 <para>&SBCL; is essentially a compiler-only implementation of
  35 &CommonLisp;. That is, for all but a few special cases,
  36 <function>eval</> creates a
  37 lambda expression, calls <function>compile</> on the lambda
  38 expression to create a compiled function, and then calls
  39 <function>funcall</> on the resulting function object. This
  40 is explicitly allowed by the &ANSI; standard, but leads to some
  41 oddities, e.g. collapsing <function>functionp</> and
  42 <function>compiled-function-p</> into the same predicate.</para>
  43
  44 <para>&SBCL; is quite strict about ANSI's definition of
  45 <function>defconstant</>. ANSI says that doing <function>defconstant</>
  46 of the same symbol more than once is undefined unless the new value
  47 is <function>eql</> to the old value. Conforming to this specification
  48 is a nuisance when the "constant" value is only constant under some
  49 weaker test like <function>string=</> or <function>equal</>. It's
  50 especially annoying because <function>defconstant</> takes effect
  51 not only at load time but also at compile time, so that just
  52 compiling and loading reasonable code like
  53 <programlisting>(defconstant +foobyte+ '(1 4))</>
  54 runs into this undefined behavior. Many
  55 implementations of Common Lisp try to help the programmer around
  56 this annoyance by silently accepting the undefined code and
  57 trying to do what the programmer probably meant. &SBCL; instead
  58 treats the undefined behavior as an error. Often
  59 such code can be rewritten
  60 in portable &ANSI; Common Lisp which has the desired behavior.
  61 E.g., the code above can be given an exactly defined meaning by replacing
  62 <function>defconstant</> either with <function>defparameter</> or
  63 with a customized macro which does the right thing, possibly along the
  64 lines of the <function>defconstant-eqx</> macro used internally in the
  65 implementation of SBCL itself.</para>
  66
  67 <para>&SBCL; gives style warnings about various kinds of perfectly
  68 legal code, e.g.
  69 <itemizedlist>
  70   <listitem><para><function>defmethod</> without
  71     <function>defgeneric</></para></listitem>
  72   <listitem><para>multiple <function>defun</>s of the same
  73     symbol</para></listitem>
  74   <listitem><para>special variables not named in the conventional
  75     <varname>*foo*</> style, and lexical variables unconventionally named
  76     in the <varname>*foo*</> style</para></listitem>
  77 </itemizedlist>
  78 This causes friction with people
  79 who point out that other ways of organizing code (especially
  80 avoiding the use of <function>defgeneric</>)
  81 are just as aesthetically stylish.
  82 However, these warnings should be read not
  83 as "warning, bad aesthetics detected, you have no style" but
  84 "warning, this style keeps the compiler from understanding
  85 the code as well as you might like." That is,
  86 unless the compiler warns about such conditions, there's no
  87 way for the compiler to warn
  88 about some programming errors which would otherwise be
  89 easy to overlook. (related bug: The warning about
  90 multiple <function>defun</>s is pointlessly annoying when you compile
  91 and then load a function containing <function>defun</> wrapped
  92 in <function>eval-when</>, and ideally should be suppressed in
  93 that case, but still isn't as of &SBCL; 0.7.6.)</para>
  94
  95 </sect1>
  96
  97 <sect1 id="extensions"><title>Extensions</>
  98
  99 <para>&SBCL; is derived from &CMUCL;, which implements many extensions
 100 to the &ANSI; standard. &SBCL; doesn't support as many extensions as
 101 &CMUCL;, but it still has quite a few.</para>
 102
 103 <sect2><title>Things Which Might Be In The Next &ANSI; Standard</>
 104
 105 <para>&SBCL; provides extensive support for
 106 calling external C code, described
 107 <link linkend="ffi">in its own chapter</link>.</para>
 108
 109 <para>&SBCL; provides additional garbage collection functionality not
 110 specified by &ANSI;. Weak pointers allow references to objects to be
 111 maintained without keeping them from being GCed. And "finalization"
 112 hooks are available to cause code to be executed when an object is
 113 GCed.</para> <!-- FIXME: Actually documenting these would be good.:-| -->
 114
 115 <para>&SBCL; supports Gray streams, user-overloadable CLOS classes
 116 whose instances can be used as Lisp streams (e.g. passed as the
 117 first argument to <function>format</>).</para>
 118
 119 <para>&SBCL; supports a MetaObject Protocol which is intended to be
 120 compatible with &AMOP;; exceptions to this (as distinct from current
 121 bugs<!-- Such as the distinction between CL:FIND-CLASS and
 122 SB-PCL::FIND-CLASS :-( -->) are that
 123 <function>compute-effective-method</> only returns one value, not
 124 two<!-- FIXME: anything else? What about extensions? (e.g. COMPUTE-SLOTS
 125 behaviour) -->.</para>
 126
 127 </sect2>
 128
 129 <sect2><title>Support For Unix</>
 130
 131 <para>The UNIX command line can be read from the variable
 132 <varname>sb-ext:*posix-argv*</>. The UNIX environment can be queried with the
 133 <function>sb-ext:posix-getenv</> function.</para>
 134
 135 <para>The &SBCL; system can be terminated with <function>sb-ext:quit</>,
 136 optionally returning a specified numeric value to the calling Unix
 137 process. The normal Unix idiom of terminating on end of file on input
 138 is also supported.</para>
 139
 140 </sect2>
 141
 142 <sect2><title>Customization Hooks for Users</title>
 143
 144 <para>The behaviour of <function>require</function> when called with only
 145 one argument is implementation-defined.  In &SBCL; it calls functions
 146 on the user-settable list <varname>sb-ext:*module-provider-functions*</varname>
 147 - see the <function>require</function> documentation string for details.
 148
 149 <para>The toplevel repl prompt may be customized, and the function
 150 that reads user input may be replaced completely.  <!-- FIXME but I
 151 don't currently remember how -->
 152
 153 <sect2><title>Tools To Help Developers</title>
 154
 155 <para>&SBCL; provides a profiler and other extensions to the &ANSI;
 156 <function>trace</> facility. See the online function documentation for
 157 <function>trace</> for more information.</para>
 158
 159 <para>The debugger supports a number of options. Its documentation is
 160 accessed by typing <userinput>help</> at the debugger prompt.</para>
 161 <!-- FIXME:
 162      A true debugger section in the manual would be good. Start
 163      with CMU CL's debugger section, but remember:
 164        * no QUIT command (TOPLEVEL restart instead)
 165        * no GO command (CONTINUE restart instead)
 166        * Limitations of the x86 port of the debugger should be
 167          documented or fixed where possible.
 168        * Discuss TRACE and its unification with PROFILE. -->
 169
 170 <para>Documentation for <function>inspect</> is accessed by typing
 171 <userinput>help</> at the <function>inspect</> prompt.</para>
 172
 173 </sect2>
 174
 175 <sect2><title>Interface To Low-Level &SBCL; Implementation</title>
 176
 177 <para>&SBCL; has the ability to save its state as a file for later
 178 execution. This functionality is important for its bootstrapping
 179 process, and is also provided as an extension to the user See the
 180 documentation for <function>sb-ext:save-lisp-and-die</> for more
 181 information.</para>
 182
 183 <note><para>&SBCL; has inherited from &CMUCL; various hooks to allow
 184 the user to tweak and monitor the garbage collection process. These
 185 are somewhat stale code, and their interface might need to be cleaned
 186 up. If you have urgent need of them, look at the code in
 187 <filename>src/code/gc.lisp</filename> and bring it up on the
 188 developers' mailing list.</para></note>
 189
 190 <note><para>&SBCL; has various hooks inherited from &CMUCL;, like
 191 <function>sb-ext:float-denormalized-p</>, to allow a program to take
 192 advantage of &IEEE; floating point arithmetic properties which aren't
 193 conveniently or efficiently expressible using the &ANSI; standard. These
 194 look good, and their interface looks good, but &IEEE; support is
 195 slightly broken due to a stupid decision to remove some support for
 196 infinities (because it wasn't in the &ANSI; spec and it didn't occur to
 197 me that it was in the &IEEE; spec). If you need this stuff, take a look
 198 at the code and bring it up on the developers' mailing
 199 list.</para></note>
 200
 201 </sect2>
 202
 203 <sect2><title>Efficiency Hacks</title>
 204
 205 <para>The <function>sb-ext:purify</function> function causes &SBCL;
 206 first to collect all garbage, then to mark all uncollected objects as
 207 permanent, never again attempting to collect them as garbage. This can
 208 cause a large increase in efficiency when using a primitive garbage
 209 collector, or a more moderate increase in efficiency when using a more
 210 sophisticated garbage collector which is well suited to the program's
 211 memory usage pattern. It also allows permanent code to be frozen at
 212 fixed addresses, a precondition for using copy-on-write to share code
 213 between multiple Lisp processes. is less important with modern
 214 generational garbage collectors. </para>
 215
 216 <para>The <function>sb-ext:truly-the</> operator does what the
 217 <function>cl:the</> operator does in a more conventional
 218 implementation of &CommonLisp;, declaring the type of its argument
 219 without any runtime checks. (Ordinarily in &SBCL;, any type
 220 declaration is treated as an assertion and checked at runtime.)</para>
 221
 222 <para>The <function>sb-ext:freeze-type</> declaration declares that a
 223 type will never change, which can make type testing
 224 (<function>typep</>, etc.) more efficient for structure types.</para>
 225
 226 <para>The <function>sb-ext:constant-function</> declaration specifies
 227 that a function will always return the same value for the same
 228 arguments, which may allow the compiler to optimize calls
 229 to it. This is appropriate for functions like <function>sqrt</>, but
 230 is <emphasis>not</> appropriate for functions like <function>aref</>,
 231 which can change their return values when the underlying data are
 232 changed.</para>
 233
 234 </sect2>
 235
 236 </sect1>
 237
 238 </chapter>