source: trunk/source/doc/src/mop.xml @ 8820

Last change on this file since 8820 was 8820, checked in by jaj, 12 years ago

This commit includes support for docbook 4.5, stylesheet changes, and updated documentation.

In order to support docbook 4.5 in nXML mode, I have added a new directory called docbook-rng-4.5 and changed schemas.xml to point to it. This should just work when editing the documentation in EMACS.

The two most obvious changes to the stylesheets are that the table of contents for each chapter now occurs at the beginning of the chapter, and the format for refentries is cleaner and more concise.

I think that we should consistently use refentry elements for all of the definitions of functions, macros, variables, etc. This retains the structured data for the definitions that can be reformatted to have different appearences by the stylesheets. We should also consistently use other docbook elements such as function and varname. I'm not really happy with their appearance right now, but that can be easily tweaked in the stylesheets as long as they are consistently used throughout the documentation.

File size: 16.3 KB
Line 
1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
3<!ENTITY rest "<varname>&amp;rest</varname>">
4<!ENTITY key "<varname>&amp;key</varname>">
5<!ENTITY optional "<varname>&amp;optional</varname>">
6<!ENTITY body "<varname>&amp;body</varname>">
7<!ENTITY aux "<varname>&amp;aux</varname>">
8<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
9<!ENTITY CCL "Clozure CL">
10]>
11
12  <chapter id="Writing-Portable-Extensions-to-the-Object-System-using-the-MetaObject-Protocol">
13    <title>Writing Portable Extensions to the Object System  using the MetaObject Protocol</title>
14
15    <sect1 id="MOP-Overview">
16      <title>Overview</title>
17      <para>&CCL; supports a fairly large subset of the
18      semi-standard MetaObject Protocol (MOP) for CLOS, as defined in
19      chapters 5 and 6 of "The Art Of The Metaobject Protocol",
20      (Kiczales et al, MIT Press 1991, ISBN 0-262-61074-4); this
21      specification is also available online at
22      http://www.alu.org/mop/index.html.</para>
23    </sect1>
24
25    <sect1 id="MOP-Implementation-status">
26      <title>Implementation status</title>
27      <para>The keyword :openmcl-partial-mop is on *FEATURES* to
28      indicate the presence of this functionality.</para>
29
30      <para>All of the symbols defined in the MOP specification
31      (whether implemented or not) are exported from the "CCL" package
32      and from an "OPENMCL-MOP" package.</para>
33      <para><informaltable><tgroup cols="2" colsep="1"
34      rowsep="1"><colspec align="center" colname="col0" /><colspec
35      align="center" colname="col1" /><thead><row><entry
36      align="center" valign="top"><para>construct</para></entry><entry
37      align="center"
38      valign="top"><para>status</para></entry></row></thead><tbody><row><entry
39      align="center"
40      valign="top"><para>accessor-method-slot-definition</para></entry><entry
41      align="center"
42      valign="top"><para>+</para></entry></row><row><entry
43      align="center"
44      valign="top"><para>add-dependent</para></entry><entry
45      align="center"
46      valign="top"><para>+</para></entry></row><row><entry
47      align="center"
48      valign="top"><para>add-direct-method</para></entry><entry
49      align="center"
50      valign="top"><para>+</para></entry></row><row><entry
51      align="center"
52      valign="top"><para>add-direct-subclass</para></entry><entry
53      align="center"
54      valign="top"><para>+</para></entry></row><row><entry
55      align="center"
56      valign="top"><para>add-method</para></entry><entry
57      align="center"
58      valign="top"><para>+</para></entry></row><row><entry
59      align="center"
60      valign="top"><para>class-default-initargs</para></entry><entry
61      align="center"
62      valign="top"><para>+</para></entry></row><row><entry
63      align="center"
64      valign="top"><para>class-direct-default-initargs</para></entry><entry
65      align="center"
66      valign="top"><para>+</para></entry></row><row><entry
67      align="center"
68      valign="top"><para>class-direct-slots</para></entry><entry
69      align="center"
70      valign="top"><para>+</para></entry></row><row><entry
71      align="center"
72      valign="top"><para>class-direct-subclasses</para></entry><entry
73      align="center"
74      valign="top"><para>+</para></entry></row><row><entry
75      align="center"
76      valign="top"><para>class-direct-superclasses</para></entry><entry
77      align="center"
78      valign="top"><para>+</para></entry></row><row><entry
79      align="center"
80      valign="top"><para>class-finalized-p</para></entry><entry
81      align="center"
82      valign="top"><para>+</para></entry></row><row><entry
83      align="center"
84      valign="top"><para>class-prototype</para></entry><entry
85      align="center"
86      valign="top"><para>+</para></entry></row><row><entry
87      align="center"
88      valign="top"><para>class-slots</para></entry><entry
89      align="center"
90      valign="top"><para>+</para></entry></row><row><entry
91      align="center"
92      valign="top"><para>compute-applicable-methods</para></entry><entry
93      align="center"
94      valign="top"><para>-</para></entry></row><row><entry
95      align="center"
96      valign="top"><para>compute-applicable-methods-using-classes</para></entry><entry
97      align="center"
98      valign="top"><para>-</para></entry></row><row><entry
99      align="center"
100      valign="top"><para>compute-class-precedence-list</para></entry><entry
101      align="center"
102      valign="top"><para>+</para></entry></row><row><entry
103      align="center"
104      valign="top"><para>compute-direct-initargs</para></entry><entry
105      align="center"
106      valign="top"><para>+</para></entry></row><row><entry
107      align="center"
108      valign="top"><para>compute-discriminating-function</para></entry><entry
109      align="center"
110      valign="top"><para>-</para></entry></row><row><entry
111      align="center"
112      valign="top"><para>compute-effective-method</para></entry><entry
113      align="center"
114      valign="top"><para>+</para></entry></row><row><entry
115      align="center"
116      valign="top"><para>compute-effective-slot-definition</para></entry><entry
117      align="center"
118      valign="top"><para>+</para></entry></row><row><entry
119      align="center"
120      valign="top"><para>compute-slots</para></entry><entry
121      align="center"
122      valign="top"><para>+</para></entry></row><row><entry
123      align="center"
124      valign="top"><para>direct-slot-definition-class</para></entry><entry
125      align="center"
126      valign="top"><para>+</para></entry></row><row><entry
127      align="center"
128      valign="top"><para>effective-slot-definition-class</para></entry><entry
129      align="center"
130      valign="top"><para>+</para></entry></row><row><entry
131      align="center"
132      valign="top"><para>ensure-class</para></entry><entry
133      align="center"
134      valign="top"><para>+</para></entry></row><row><entry
135      align="center"
136      valign="top"><para>ensure-class-using-class</para></entry><entry
137      align="center"
138      valign="top"><para>+</para></entry></row><row><entry
139      align="center"
140      valign="top"><para>ensure-generic-function-using-class</para></entry><entry
141      align="center"
142      valign="top"><para>+</para></entry></row><row><entry
143      align="center"
144      valign="top"><para>eql-specializer-object</para></entry><entry
145      align="center"
146      valign="top"><para>+</para></entry></row><row><entry
147      align="center"
148      valign="top"><para>extract-lambda-list</para></entry><entry
149      align="center"
150      valign="top"><para>+</para></entry></row><row><entry
151      align="center"
152      valign="top"><para>extract-specializer-names</para></entry><entry
153      align="center"
154      valign="top"><para>+</para></entry></row><row><entry
155      align="center"
156      valign="top"><para>finalize-inheritance</para></entry><entry
157      align="center"
158      valign="top"><para>+</para></entry></row><row><entry
159      align="center"
160      valign="top"><para>find-method-combination</para></entry><entry
161      align="center"
162      valign="top"><para>+</para></entry></row><row><entry
163      align="center"
164      valign="top"><para>funcallable-standard-instance-access</para></entry><entry
165      align="center"
166      valign="top"><para>+</para></entry></row><row><entry
167      align="center"
168      valign="top"><para>generic-function-argument-precedence-order</para></entry><entry
169      align="center"
170      valign="top"><para>+</para></entry></row><row><entry
171      align="center"
172      valign="top"><para>generic-function-declarations</para></entry><entry
173      align="center"
174      valign="top"><para>+</para></entry></row><row><entry
175      align="center"
176      valign="top"><para>generic-function-lambda-list</para></entry><entry
177      align="center"
178      valign="top"><para>+</para></entry></row><row><entry
179      align="center"
180      valign="top"><para>generic-function-method-class</para></entry><entry
181      align="center"
182      valign="top"><para>+</para></entry></row><row><entry
183      align="center"
184      valign="top"><para>generic-function-method-combination</para></entry><entry
185      align="center"
186      valign="top"><para>+</para></entry></row><row><entry
187      align="center"
188      valign="top"><para>generic-function-methods</para></entry><entry
189      align="center"
190      valign="top"><para>+</para></entry></row><row><entry
191      align="center"
192      valign="top"><para>generic-function-name</para></entry><entry
193      align="center"
194      valign="top"><para>+</para></entry></row><row><entry
195      align="center"
196      valign="top"><para>intern-eql-specializer</para></entry><entry
197      align="center"
198      valign="top"><para>+</para></entry></row><row><entry
199      align="center"
200      valign="top"><para>make-method-lambda</para></entry><entry
201      align="center"
202      valign="top"><para>-</para></entry></row><row><entry
203      align="center"
204      valign="top"><para>map-dependents</para></entry><entry
205      align="center"
206      valign="top"><para>+</para></entry></row><row><entry
207      align="center"
208      valign="top"><para>method-function</para></entry><entry
209      align="center"
210      valign="top"><para>+</para></entry></row><row><entry
211      align="center"
212      valign="top"><para>method-generic-function</para></entry><entry
213      align="center"
214      valign="top"><para>+</para></entry></row><row><entry
215      align="center"
216      valign="top"><para>method-lambda-list</para></entry><entry
217      align="center"
218      valign="top"><para>+</para></entry></row><row><entry
219      align="center"
220      valign="top"><para>method-qualifiers</para></entry><entry
221      align="center"
222      valign="top"><para>+</para></entry></row><row><entry
223      align="center"
224      valign="top"><para>method-specializers</para></entry><entry
225      align="center"
226      valign="top"><para>+</para></entry></row><row><entry
227      align="center"
228      valign="top"><para>reader-method-class</para></entry><entry
229      align="center"
230      valign="top"><para>+</para></entry></row><row><entry
231      align="center"
232      valign="top"><para>remove-dependent</para></entry><entry
233      align="center"
234      valign="top"><para>+</para></entry></row><row><entry
235      align="center"
236      valign="top"><para>remove-direct-method</para></entry><entry
237      align="center"
238      valign="top"><para>+</para></entry></row><row><entry
239      align="center"
240      valign="top"><para>remove-direct-subclass</para></entry><entry
241      align="center"
242      valign="top"><para>+</para></entry></row><row><entry
243      align="center"
244      valign="top"><para>remove-method</para></entry><entry
245      align="center"
246      valign="top"><para>+</para></entry></row><row><entry
247      align="center"
248      valign="top"><para>set-funcallable-instance-function</para></entry><entry
249      align="center"
250      valign="top"><para>-</para></entry></row><row><entry
251      align="center"
252      valign="top"><para>slot-boundp-using-class</para></entry><entry
253      align="center"
254      valign="top"><para>+</para></entry></row><row><entry
255      align="center"
256      valign="top"><para>slot-definition-allocation</para></entry><entry
257      align="center"
258      valign="top"><para>+</para></entry></row><row><entry
259      align="center"
260      valign="top"><para>slot-definition-initargs</para></entry><entry
261      align="center"
262      valign="top"><para>+</para></entry></row><row><entry
263      align="center"
264      valign="top"><para>slot-definition-initform</para></entry><entry
265      align="center"
266      valign="top"><para>+</para></entry></row><row><entry
267      align="center"
268      valign="top"><para>slot-definition-initfunction</para></entry><entry
269      align="center"
270      valign="top"><para>+</para></entry></row><row><entry
271      align="center"
272      valign="top"><para>slot-definition-location</para></entry><entry
273      align="center"
274      valign="top"><para>+</para></entry></row><row><entry
275      align="center"
276      valign="top"><para>slot-definition-name</para></entry><entry
277      align="center"
278      valign="top"><para>+</para></entry></row><row><entry
279      align="center"
280      valign="top"><para>slot-definition-readers</para></entry><entry
281      align="center"
282      valign="top"><para>+</para></entry></row><row><entry
283      align="center"
284      valign="top"><para>slot-definition-type</para></entry><entry
285      align="center"
286      valign="top"><para>+</para></entry></row><row><entry
287      align="center"
288      valign="top"><para>slot-definition-writers</para></entry><entry
289      align="center"
290      valign="top"><para>+</para></entry></row><row><entry
291      align="center"
292      valign="top"><para>slot-makunbound-using-class</para></entry><entry
293      align="center"
294      valign="top"><para>+</para></entry></row><row><entry
295      align="center"
296      valign="top"><para>slot-value-using-class</para></entry><entry
297      align="center"
298      valign="top"><para>+</para></entry></row><row><entry
299      align="center"
300      valign="top"><para>specializer-direct-generic-functions</para></entry><entry
301      align="center"
302      valign="top"><para>+</para></entry></row><row><entry
303      align="center"
304      valign="top"><para>specializer-direct-methods</para></entry><entry
305      align="center"
306      valign="top"><para>+</para></entry></row><row><entry
307      align="center"
308      valign="top"><para>standard-instance-access</para></entry><entry
309      align="center"
310      valign="top"><para>+</para></entry></row><row><entry
311      align="center"
312      valign="top"><para>update-dependent</para></entry><entry
313      align="center"
314      valign="top"><para>+</para></entry></row><row><entry
315      align="center"
316      valign="top"><para>validate-superclass</para></entry><entry
317      align="center"
318      valign="top"><para>+</para></entry></row><row><entry
319      align="center"
320      valign="top"><para>writer-method-class</para></entry><entry
321      align="center"
322      valign="top"><para>+</para></entry></row></tbody></tgroup></informaltable></para>
323     
324      <para>Note that those generic functions whose status is "-" in
325      the table above deal with the internals of generic function
326      dispatch and method invocation (the "Generic Function Invocation
327      Protocol".) Method functions are implemented a bit differently
328      in &CCL; from what the MOP expects, and it's not yet clear if
329      or how this subprotocol can be well-supported.</para>
330      <para>Those constructs that are marked as "+" in the table above
331      are nominally implemented as the MOP document specifies
332      (deviations from the specification should be considered bugs;
333      please report them as such.) Note that some CLOS implementations
334      in widespread use (e.g., PCL) implement some things
335      (ENSURE-CLASS-USING-CLASS comes to mind) a bit differently from
336      what the MOP specifies.</para>
337    </sect1>
338
339    <sect1 id="Concurrency-issues">
340      <title>Concurrency issues</title>
341      <para>The entire CLOS class and generic function hierarchy is
342      effectively a (large, complicated) shared data structure; it's
343      not generally practical for a thread to request exclusive access
344      to all of CLOS, and the effects of volitional modification of
345      the CLOS hierarchy (via clas redefinition, CHANGE-CLASS, etc) in
346      a multithreaded environment aren't always tractable.</para>
347      <para>Native threads exacerbate this problem (in that they
348      increase the opportunities for concurrent modification and
349      access.) The implementation should try to ensure that a thread's
350      view of any subset of the CLOS hierarchy is consistent (to the
351      extent that that's possible) and should try to ensure that
352      incidental modifications of the hierarchy (cache updates, etc.)
353      happen atomically; it's not generally possible for the
354      implementation to guarantee that a thread's view of things is
355      correct and current.</para>
356      <para>If you are loading code and defining classes in the most
357      usual way, which is to say, via the compiler, using only a
358      single thread, these issues are probably not going to affect you
359      much.</para>
360      <para>If, however, you are making finicky changes to the class
361      hierarchy while you're running multiple threads which manipulate
362      objects related to each other, more care is required.  Before
363      doing such a thing, you should know what you're doing and
364      already be aware of what precautions to take, without being
365      told.  That said, if you do it, you should seriously consider
366      what your application's critical data is, and use locks for
367      critical code sections.</para>
368    </sect1>
369  </chapter>
Note: See TracBrowser for help on using the repository browser.