2 @comment node-name, next, previous, up
5 In order to support evolution of interfaces in SBCL as well as in user
6 code, SBCL allows declaring functions, variables and types as
7 deprecated. Users of deprecated things are notified by means of warnings
8 while the deprecated thing in question is still available.
10 This chapter documents the interfaces for being notified when using
11 deprecated thing and declaring things as deprecated, the deprecation
12 process used for SBCL interfaces, and lists legacy interfaces in various
13 stages of deprecation.
15 @dfn{Deprecation} in this context should not be confused with those
16 things the ANSI Common Lisp standard calls @dfn{deprecated}: the
17 entirety of ANSI CL is supported by SBCL, and none of those interfaces
18 are subject to censure.
22 * The Deprecation Pipeline::
23 * Deprecation Conditions::
24 * Introspecting Deprecation Information::
25 * Deprecation Declaration::
26 * Deprecation Examples::
27 * Deprecated Interfaces in SBCL::
31 @comment node-name, next, previous, up
32 @section Why Deprecate?
33 @cindex Why Deprecate?
35 While generally speaking we try to keep SBCL changes as backwards
36 compatible as feasible, there are situations when existing interfaces
41 @item @strong{Broken Interfaces}
43 Sometimes it turns out that an interface is sufficiently misdesigned
44 that fixing it would be worse than deprecating it and replacing it
47 This is typically the case when fixing the interface would change its
48 semantics in ways that could break user code subtly: in such cases we
49 may end up considering the obvious breakage caused by deprecation to
52 Another example are functions or macros whose current signature makes
53 them hard or impossible to extend in the future: backwards compatible
54 extensions would either make the interface intolerably hairy, or are
55 sometimes outright impossible.
57 @item @strong{Internal Interfaces}
59 SBCL has several internal interfaces that were never meant to be used
60 in user code -- or at least never meant to be used in user code
61 unwilling to track changes to SBCL internals.
63 Ideally we'd like to be free to refactor our own internals as we
64 please, without even going through the hassle of deprecating things.
65 Sometimes, however, it turns out that our internal interfaces have
66 several external users who aren't using them advisedly, but due to
67 misunderstandings regarding their status or stability.
69 Consider a deprecated internal interface a reminder for SBCL
70 maintainers not to delete the thing just yet, even though it is seems
71 unused -- because it has external users.
73 When internal interfaces are deprecated we try our best to provide
74 supported alternatives.
76 @item @strong{Aesthetics & Ease of Maintenance}
78 Sometimes an interface isn't broken or internal, but just inconsistent
81 This mostly happens only with historical interfaces inherited from
82 CMUCL which often haven't been officially supported in SBCL before, or
83 with new extensions to SBCL that haven't been around for very long in
86 The alternative would be to keep the suboptimal version around
87 forever, possibly alongside an improved version. Sometimes we may do
88 just that, but because every line of code comes with a maintenance
89 cost, sometimes we opt to deprecate the suboptimal version instead:
90 SBCL doesn't have infinite developer resources.
92 We also believe that sometimes cleaning out legacy interfaces helps
93 keep the whole system more comprehensible to users, and makes
94 introspective tools such as
96 @code{apropos} more useful.
100 @node The Deprecation Pipeline
101 @comment node-name, next, previous, up
102 @section The Deprecation Pipeline
103 @cindex The Deprecation Pipeline
105 SBCL uses a @dfn{deprecation pipeline} with multiple stages: as time
106 goes by, deprecated things move from earlier stages of deprecation to
107 later stages before finally being removed. The intention is making users
108 aware of necessary changes early but allowing a migration to new
109 interfaces at a reasonable pace.
111 Deprecation proceeds in three stages, each lasting approximately a
112 year. In some cases it might move slower or faster, but one year per
113 stage is what we aim at in general. During each stage warnings (and
114 errors) of increasing severity are signaled, which note that the
115 interface is deprecated, and point users towards any replacements when
120 @item @strong{Early Deprecation}
122 During early deprecation the interface is kept in working
123 condition. However, when a thing in this deprecation stage is used, an
124 @tindex @sbext{early-deprecation-warning}
125 @code{sb-ext:early-deprecation-warning}, which is a
126 @tindex @cl{style-warning}
127 @code{style-warning}, is signaled at
130 The internals may change at this stage: typically because the interface
131 is re-implemented on top of its successor. While we try to keep things
132 as backwards-compatible as feasible (taking maintenance costs into account),
133 sometimes semantics change slightly.
135 For example, when the spinlock API was deprecated, spinlock objects ceased
136 to exist, and the whole spinlock API became a synonym for the mutex
137 API -- so code using the spinlock API continued working, but silently
138 switched to mutexes instead. However, if someone relied on
140 @code{(typep lock 'spinlock)}
142 returning @code{NIL} for a mutexes, trouble could ensue.
144 @item @strong{Late Deprecation}
146 During late deprecation the interface remains as it was during early
147 deprecation, but the compile-time warning is upgraded: when a thing in
148 this deprecation stage is used, a
149 @tindex @sbext{late-deprecation-warning}
150 @code{sb-ext:late-deprecation-warning},
153 @code{warning}, is signaled at compile-time.
155 @item @strong{Final Deprecation}
157 During final deprecation the symbols still exist. However, when a thing
158 in this deprecation stage is used, a
159 @tindex @sbext{final-deprecation-warning}
160 @code{sb-ext:final-deprecation-warning},
163 @code{warning}, is signaled at compile-time and an
165 @code{error} is signaled at run-time.
167 @item @strong{After Final Deprecation}
169 The interface is deleted entirely.
173 @node Deprecation Conditions
174 @comment node-name, next, previous, up
175 @section Deprecation Conditions
176 @cindex Deprecation Conditions
178 @tindex @sbext{deprecation-condition}
179 @code{sb-ext:deprecation-condition} is the superclass of all
180 deprecation-related warning and error conditions. All common slots and
181 readers are defined in this condition class.
183 @include condition-sb-ext-deprecation-condition.texinfo
185 @include condition-sb-ext-early-deprecation-warning.texinfo
187 @include condition-sb-ext-late-deprecation-warning.texinfo
189 @include condition-sb-ext-final-deprecation-warning.texinfo
191 @include condition-sb-ext-deprecation-error.texinfo
193 @node Introspecting Deprecation Information
194 @comment node-name, next, previous, up
195 @section Introspecting Deprecation Information
196 @cindex Introspecting Deprecation Information
197 @comment TODO @findex @sbcltl{function-information}
198 @comment TODO @findex @sbcltl{variable-information}
200 The deprecation status of functions and variables can be inspected
201 using the @code{sb-cltl2:function-information} and
202 @code{sb-cltl2:variable-information} functions provided by the
203 @code{sb-cltl2} contributed module.
205 @node Deprecation Declaration
206 @comment node-name, next, previous, up
207 @section Deprecation Declaration
208 @cindex Deprecation Declaration
209 @findex @sbext{deprecated}
211 The @code{sb-ext:deprecated} declaration can be used to declare objects
212 in various namespaces@footnote{See ``namespace'' entry in the glossary
213 of the Common Lisp Hyperspec.} as deprecated.
215 @deffn {Declaration} @sbext{deprecated}
219 @code{sb-ext:deprecated} stage since @{object-clause@}*
221 stage ::= @{:early | :late | :final@}
223 since ::= @{@var{version} | (@var{software} @var{version})@}
225 object-clause ::= (namespace @var{name} [:replacement @var{replacement}])
227 namespace ::= @{cl:variable | cl:function | cl:type@}
230 @noindent were @var{name} is the name of the deprecated thing,
231 @var{version} and @var{software} are strings describing the version in
232 which the thing has been deprecated and @var{replacement} is a name or a
233 list of names designating things that should be used instead of the
236 Currently the following namespaces are supported:
241 Declare functions, compiler-macros or macros as deprecated.
244 When declaring a function to be in @code{:final} deprecation, there
245 should be no actual definition of the function as the declaration emits
246 a stub function that signals a
247 @tindex @sbext{deprecation-error}
248 @code{sb-ext:deprecation-error} at run-time when called.
252 Declare special and global variables, constants and symbol-macros as
256 When declaring a variable to be in @code{:final} deprecation, there
257 should be no actual definition of the variable as the declaration emits
258 a symbol-macro that signals a
259 @tindex @sbext{deprecation-error}
260 @code{sb-ext:deprecation-error} at run-time when accessed.
264 Declare named types (i.e. defined via @code{deftype}), standard classes,
265 structure classes and condition classes as deprecated.
270 @node Deprecation Examples
271 @comment node-name, next, previous, up
272 @section Deprecation Examples
273 @cindex Deprecation Examples
275 Marking functions as deprecated:
279 (declaim (deprecated :early ("my-system" "1.2.3")
280 (function foo :replacement bar)))
282 ;; Remember: do not define the actual function or variable in case of
283 ;; :final deprecation:
284 (declaim (deprecated :final ("my-system" "1.2.3")
285 (function fez :replacement whoop)))
288 @noindent Attempting to use the deprecated functions:
292 | STYLE-WARNING: The function CL-USER::FOO has been deprecated...
299 | WARNING: The function CL-USER::FEZ has been deprecated...
302 |- ERROR: The function CL-USER::FEZ has been deprecated...
305 @node Deprecated Interfaces in SBCL
306 @comment node-name, next, previous, up
307 @section Deprecated Interfaces in SBCL
309 This sections lists legacy interfaces in various stages of deprecation.
311 @subsection List of Deprecated Interfaces
313 @subsubsection Early Deprecation
315 @tindex @sbext{early-deprecation-warning}
319 @item @strong{SOCKINT::WIN32-*}
321 Deprecated in favor of the corresponding prefix-less functions
322 (e.g. @code{sockint::bind} replaces @code{sockint::win32-bind}) as of
323 1.2.10 in March 2015. Expected to move into late deprecation in August
327 @item @strong{SB-UNIX:UNIX-EXIT}
329 Deprecated as of 1.0.56.55 in May 2012. Expected to move into late
330 deprecation in May 2013.
332 When the SBCL process termination was refactored as part of changes that
333 led to @code{sb-ext:quit} being deprecated, @code{sb-unix:unix-exit}
334 ceased to be used internally. Since @code{SB-UNIX} is an internal package
335 not intended for user code to use, and since we're slowly in the process
336 of refactoring things to be less Unix-oriented, @code{sb-unix:unix-exit}
337 was initially deleted as it was no longer used. Unfortunately it became
338 apparent that it was used by several external users, so it was re-instated
341 While the cost of keeping @code{sb-unix:unix-exit} indefinitely is
342 trivial, the ability to refactor our internals is important, so its
343 deprecation was taken as an opportunity to highlight that
344 @code{SB-UNIX} is an internal package and @code{SB-POSIX} should be
345 used by user-programs instead -- or alternatively calling the foreign
346 function directly if the desired interface doesn't for some reason
347 exist in @code{SB-POSIX}.
351 For code needing to work with legacy SBCLs, use e.g. @code{system-exit}
352 as show above in remedies for @code{sb-ext:quit}. In modern SBCLs
353 simply call either @code{sb-posix:exit} or @code{sb-ext:exit} with
354 appropriate arguments.
357 @item @strong{SB-C::MERGE-TAIL-CALLS Compiler Policy}
359 Deprecated as of 1.0.53.74 in November 2011. Expected to move into
360 late deprecation in November 2012.
362 This compiler policy was never functional: SBCL has always merged tail
363 calls when it could, regardless of this policy setting. (It was also
364 never officially supported, but several code-bases have historically
369 Simply remove the policy declarations. They were never necessary: SBCL
370 always merged tail-calls when possible. To disable tail merging,
371 structure the code to avoid the tail position instead.
374 @item @strong{Spinlock API}
376 Deprecated as of 1.0.53.11 in August 2011. Expected to move into late
377 deprecation in August 2012.
379 Spinlocks were an internal interface, but had a number of external users
380 and were hence deprecated instead of being simply deleted.
382 Affected symbols: @code{sb-thread::spinlock},
383 @code{sb-thread::make-spinlock}, @code{sb-thread::with-spinlock},
384 @code{sb-thread::with-recursive-spinlock},
385 @code{sb-thread::get-spinlock}, @code{sb-thread::release-spinlock},
386 @code{sb-thread::spinlock-value}, and @code{sb-thread::spinlock-name}.
390 Use the mutex API instead, or implement spinlocks suiting your needs
391 on top of @code{sb-ext:compare-and-swap},
392 @code{sb-ext:spin-loop-hint}, etc.
394 @item @strong{SOCKINT::HANDLE->FD}, @strong{SOCKINT::FD->HANDLE}
396 Internally deprecated in 2012. Declared deprecated as of 1.2.10 in March
397 2015. Expected to move into final deprecation in August 2015.
401 @subsubsection Late Deprecation
403 @tindex @sbext{late-deprecation-warning}
407 @item @strong{SB-THREAD:JOIN-THREAD-ERROR-THREAD and SB-THREAD:INTERRUPT-THREAD-ERROR-THREAD}
409 Deprecated in favor of @code{sb-thread:thread-error-thread} as of
410 1.0.29.17 in June 2009. Expected to move into final deprecation in
415 For code that needs to support legacy SBCLs, use e.g.:
419 (defun get-thread-error-thread (condition)
420 #+#.(cl:if (cl:find-symbol "THREAD-ERROR-THREAD" :sb-thread)
422 (sb-thread:thread-error-thread condition)
423 #-#.(cl:if (cl:find-symbol "THREAD-ERROR-THREAD" :sb-thread)
426 (sb-thread:join-thread-error
427 (sb-thread:join-thread-error-thread condition))
428 (sb-thread:interrupt-thread-error
429 (sb-thread:interrupt-thread-error-thread condition))))
434 @item @strong{SB-INTROSPECT:FUNCTION-ARGLIST}
436 Deprecated in favor of @code{sb-introspect:function-lambda-list} as of
437 1.0.24.5 in January 2009. Expected to move into final deprecation in
440 Renamed for consistency and aesthetics. Functions have lambda-lists,
445 For code that needs to support legacy SBCLs, use e.g.:
449 (defun get-function-lambda-list (function)
450 #+#.(cl:if (cl:find-symbol "FUNCTION-LAMBDA-LIST" :sb-introspect)
452 (sb-introspect:function-lambda-list function)
453 #-#.(cl:if (cl:find-symbol "FUNCTION-LAMBDA-LIST" :sb-introspect)
455 (sb-introspect:function-arglist function))
460 @item @strong{Stack Allocation Policies}
462 Deprecated in favor of @code{sb-ext:*stack-allocate-dynamic-extent*}
463 as of 1.0.19.7 in August 2008, and are expected to be removed in
466 Affected symbols: @code{sb-c::stack-allocate-dynamic-extent},
467 @code{sb-c::stack-allocate-vector}, and
468 @code{sb-c::stack-allocate-value-cells}.
470 These compiler policies were never officially supported, and turned
471 out the be a flawed design.
475 For code that needs stack-allocation in legacy SBCLs, conditionalize
480 #-#.(cl:if (cl:find-symbol "*STACK-ALLOCATE-DYNAMIC-EXTENT*" :sb-ext)
482 (declare (optimize sb-c::stack-allocate-dynamic-extent))
486 However, unless stack allocation is essential, we recommend simply
487 removing these declarations. Refer to documentation on
488 @code{sb-ext:*stack-allocate-dynamic*} for details on stack allocation
489 control in modern SBCLs.
492 @item @strong{SB-SYS:OUTPUT-RAW-BYTES}
494 Deprecated as of 1.0.8.16 in June 2007. Expected to move into final
495 deprecation in June 2012.
497 Internal interface with some external users. Never officially
498 supported, deemed unnecessary in presence of @code{write-sequence} and
503 Use streams with element-type @code{(unsigned-byte 8)}
504 or @code{:default} -- the latter allowing both binary and
505 character IO -- in conjunction with @code{write-sequence}.
509 @subsubsection Final Deprecation
511 @tindex @sbext{final-deprecation-warning}
513 No interfaces are currently in final deprecation.
515 @subsection Historical Interfaces
517 The following is a partial list of interfaces present in historical
518 versions of SBCL, which have since then been deleted.
522 @item @strong{SB-KERNEL:INSTANCE-LAMBDA}
524 Historically needed for CLOS code. Deprecated as of 0.9.3.32 in August
525 2005. Deleted as of 1.0.47.8 in April 2011. Plain @code{lambda} can be
526 used where @code{sb-kernel:instance-lambda} used to be needed.
529 @item @strong{SB-ALIEN:DEF-ALIEN-ROUTINE, SB-ALIEN:DEF-ALIEN-VARIABLE, SB-ALIEN:DEF-ALIEN-TYPE}
531 Inherited from CMUCL, naming convention not consistent with preferred
532 SBCL style. Deprecated as of 0.pre7.90 in December 2001. Deleted as of
533 1.0.9.17 in September 2007. Replaced by
534 @code{sb-alien:define-alien-routine},
535 @code{sb-alien:define-alien-variable}, and
536 @code{sb-alien:define-alien-type}.