|
428
|
1 \input texinfo @c -*-texinfo-*-
|
|
|
2 @c %**start of header
|
|
|
3 @setfilename ../../info/internals.info
|
|
|
4 @settitle XEmacs Internals Manual
|
|
|
5 @c %**end of header
|
|
|
6
|
|
|
7 @ifinfo
|
|
|
8 @dircategory XEmacs Editor
|
|
|
9 @direntry
|
|
440
|
10 * Internals: (internals). XEmacs Internals Manual.
|
|
428
|
11 @end direntry
|
|
|
12
|
|
|
13 Copyright @copyright{} 1992 - 1996 Ben Wing.
|
|
|
14 Copyright @copyright{} 1996, 1997 Sun Microsystems.
|
|
1709
|
15 Copyright @copyright{} 1994 - 1998, 2002, 2003 Free Software Foundation.
|
|
428
|
16 Copyright @copyright{} 1994, 1995 Board of Trustees, University of Illinois.
|
|
|
17
|
|
|
18
|
|
|
19 Permission is granted to make and distribute verbatim copies of this
|
|
|
20 manual provided the copyright notice and this permission notice are
|
|
|
21 preserved on all copies.
|
|
|
22
|
|
|
23 @ignore
|
|
|
24 Permission is granted to process this file through TeX and print the
|
|
|
25 results, provided the printed document carries copying permission notice
|
|
|
26 identical to this one except for the removal of this paragraph (this
|
|
|
27 paragraph not being relevant to the printed manual).
|
|
|
28
|
|
|
29 @end ignore
|
|
|
30 Permission is granted to copy and distribute modified versions of this
|
|
|
31 manual under the conditions for verbatim copying, provided that the
|
|
|
32 entire resulting derived work is distributed under the terms of a
|
|
|
33 permission notice identical to this one.
|
|
|
34
|
|
|
35 Permission is granted to copy and distribute translations of this manual
|
|
|
36 into another language, under the above conditions for modified versions,
|
|
|
37 except that this permission notice may be stated in a translation
|
|
|
38 approved by the Foundation.
|
|
|
39
|
|
|
40 Permission is granted to copy and distribute modified versions of this
|
|
|
41 manual under the conditions for verbatim copying, provided also that the
|
|
|
42 section entitled ``GNU General Public License'' is included exactly as
|
|
|
43 in the original, and provided that the entire resulting derived work is
|
|
|
44 distributed under the terms of a permission notice identical to this
|
|
|
45 one.
|
|
|
46
|
|
|
47 Permission is granted to copy and distribute translations of this manual
|
|
|
48 into another language, under the above conditions for modified versions,
|
|
|
49 except that the section entitled ``GNU General Public License'' may be
|
|
|
50 included in a translation approved by the Free Software Foundation
|
|
|
51 instead of in the original English.
|
|
|
52 @end ifinfo
|
|
|
53
|
|
|
54 @c Combine indices.
|
|
|
55 @synindex cp fn
|
|
|
56 @syncodeindex vr fn
|
|
|
57 @syncodeindex ky fn
|
|
|
58 @syncodeindex pg fn
|
|
|
59 @syncodeindex tp fn
|
|
|
60
|
|
|
61 @setchapternewpage odd
|
|
|
62 @finalout
|
|
|
63
|
|
|
64 @titlepage
|
|
|
65 @title XEmacs Internals Manual
|
|
464
|
66 @subtitle Version 1.4, March 2001
|
|
428
|
67
|
|
|
68 @author Ben Wing
|
|
|
69 @author Martin Buchholz
|
|
|
70 @author Hrvoje Niksic
|
|
|
71 @author Matthias Neubauer
|
|
442
|
72 @author Olivier Galibert
|
|
428
|
73 @page
|
|
|
74 @vskip 0pt plus 1fill
|
|
|
75
|
|
|
76 @noindent
|
|
464
|
77 Copyright @copyright{} 1992 - 1996, 2001 Ben Wing. @*
|
|
428
|
78 Copyright @copyright{} 1996, 1997 Sun Microsystems, Inc. @*
|
|
|
79 Copyright @copyright{} 1994 - 1998 Free Software Foundation. @*
|
|
|
80 Copyright @copyright{} 1994, 1995 Board of Trustees, University of Illinois.
|
|
|
81
|
|
|
82 @sp 2
|
|
464
|
83 Version 1.4 @*
|
|
|
84 March 2001.@*
|
|
428
|
85
|
|
|
86 Permission is granted to make and distribute verbatim copies of this
|
|
|
87 manual provided the copyright notice and this permission notice are
|
|
|
88 preserved on all copies.
|
|
|
89
|
|
|
90 Permission is granted to copy and distribute modified versions of this
|
|
|
91 manual under the conditions for verbatim copying, provided also that the
|
|
|
92 section entitled ``GNU General Public License'' is included
|
|
|
93 exactly as in the original, and provided that the entire resulting
|
|
|
94 derived work is distributed under the terms of a permission notice
|
|
|
95 identical to this one.
|
|
|
96
|
|
|
97 Permission is granted to copy and distribute translations of this manual
|
|
|
98 into another language, under the above conditions for modified versions,
|
|
|
99 except that the section entitled ``GNU General Public License'' may be
|
|
|
100 included in a translation approved by the Free Software Foundation
|
|
|
101 instead of in the original English.
|
|
|
102 @end titlepage
|
|
|
103 @page
|
|
|
104
|
|
|
105 @node Top, A History of Emacs, (dir), (dir)
|
|
|
106
|
|
|
107 @ifinfo
|
|
464
|
108 This Info file contains v1.4 of the XEmacs Internals Manual, March 2001.
|
|
428
|
109 @end ifinfo
|
|
|
110
|
|
|
111 @menu
|
|
|
112 * A History of Emacs:: Times, dates, important events.
|
|
|
113 * XEmacs From the Outside:: A broad conceptual overview.
|
|
|
114 * The Lisp Language:: An overview.
|
|
|
115 * XEmacs From the Perspective of Building::
|
|
1333
|
116 * Build-Time Dependencies::
|
|
428
|
117 * XEmacs From the Inside::
|
|
|
118 * The XEmacs Object System (Abstractly Speaking)::
|
|
|
119 * How Lisp Objects Are Represented in C::
|
|
868
|
120 * Major Textual Changes::
|
|
428
|
121 * Rules When Writing New C Code::
|
|
965
|
122 * Regression Testing XEmacs::
|
|
802
|
123 * CVS Techniques::
|
|
428
|
124 * A Summary of the Various XEmacs Modules::
|
|
|
125 * Allocation of Objects in XEmacs Lisp::
|
|
442
|
126 * Dumping::
|
|
428
|
127 * Events and the Event Loop::
|
|
|
128 * Evaluation; Stack Frames; Bindings::
|
|
|
129 * Symbols and Variables::
|
|
|
130 * Buffers and Textual Representation::
|
|
|
131 * MULE Character Sets and Encodings::
|
|
|
132 * The Lisp Reader and Compiler::
|
|
|
133 * Lstreams::
|
|
|
134 * Consoles; Devices; Frames; Windows::
|
|
|
135 * The Redisplay Mechanism::
|
|
|
136 * Extents::
|
|
|
137 * Faces::
|
|
|
138 * Glyphs::
|
|
|
139 * Specifiers::
|
|
|
140 * Menus::
|
|
|
141 * Subprocesses::
|
|
446
|
142 * Interface to the X Window System::
|
|
442
|
143 * Index::
|
|
|
144
|
|
|
145 @detailmenu
|
|
|
146
|
|
|
147 --- The Detailed Node Listing ---
|
|
428
|
148
|
|
|
149 A History of Emacs
|
|
|
150
|
|
|
151 * Through Version 18:: Unification prevails.
|
|
|
152 * Lucid Emacs:: One version 19 Emacs.
|
|
|
153 * GNU Emacs 19:: The other version 19 Emacs.
|
|
442
|
154 * GNU Emacs 20:: The other version 20 Emacs.
|
|
428
|
155 * XEmacs:: The continuation of Lucid Emacs.
|
|
|
156
|
|
|
157 Rules When Writing New C Code
|
|
|
158
|
|
|
159 * General Coding Rules::
|
|
|
160 * Writing Lisp Primitives::
|
|
802
|
161 * Writing Good Comments::
|
|
428
|
162 * Adding Global Lisp Variables::
|
|
802
|
163 * Proper Use of Unsigned Types::
|
|
442
|
164 * Coding for Mule::
|
|
428
|
165 * Techniques for XEmacs Developers::
|
|
|
166
|
|
442
|
167 Coding for Mule
|
|
|
168
|
|
|
169 * Character-Related Data Types::
|
|
|
170 * Working With Character and Byte Positions::
|
|
|
171 * Conversion to and from External Data::
|
|
|
172 * General Guidelines for Writing Mule-Aware Code::
|
|
|
173 * An Example of Mule-Aware Code::
|
|
|
174
|
|
802
|
175 CVS Techniques
|
|
|
176
|
|
|
177 * Merging a Branch into the Trunk::
|
|
|
178
|
|
965
|
179 Regression Testing XEmacs
|
|
|
180
|
|
428
|
181 A Summary of the Various XEmacs Modules
|
|
|
182
|
|
|
183 * Low-Level Modules::
|
|
|
184 * Basic Lisp Modules::
|
|
|
185 * Modules for Standard Editing Operations::
|
|
|
186 * Editor-Level Control Flow Modules::
|
|
|
187 * Modules for the Basic Displayable Lisp Objects::
|
|
|
188 * Modules for other Display-Related Lisp Objects::
|
|
|
189 * Modules for the Redisplay Mechanism::
|
|
|
190 * Modules for Interfacing with the File System::
|
|
|
191 * Modules for Other Aspects of the Lisp Interpreter and Object System::
|
|
|
192 * Modules for Interfacing with the Operating System::
|
|
|
193 * Modules for Interfacing with X Windows::
|
|
|
194 * Modules for Internationalization::
|
|
965
|
195 * Modules for Regression Testing::
|
|
428
|
196
|
|
|
197 Allocation of Objects in XEmacs Lisp
|
|
|
198
|
|
|
199 * Introduction to Allocation::
|
|
|
200 * Garbage Collection::
|
|
|
201 * GCPROing::
|
|
|
202 * Garbage Collection - Step by Step::
|
|
|
203 * Integers and Characters::
|
|
|
204 * Allocation from Frob Blocks::
|
|
|
205 * lrecords::
|
|
|
206 * Low-level allocation::
|
|
|
207 * Cons::
|
|
|
208 * Vector::
|
|
|
209 * Bit Vector::
|
|
|
210 * Symbol::
|
|
|
211 * Marker::
|
|
|
212 * String::
|
|
|
213 * Compiled Function::
|
|
|
214
|
|
442
|
215 Garbage Collection - Step by Step
|
|
|
216
|
|
|
217 * Invocation::
|
|
|
218 * garbage_collect_1::
|
|
|
219 * mark_object::
|
|
|
220 * gc_sweep::
|
|
|
221 * sweep_lcrecords_1::
|
|
|
222 * compact_string_chars::
|
|
|
223 * sweep_strings::
|
|
|
224 * sweep_bit_vectors_1::
|
|
|
225
|
|
|
226 Dumping
|
|
|
227
|
|
|
228 * Overview::
|
|
|
229 * Data descriptions::
|
|
|
230 * Dumping phase::
|
|
|
231 * Reloading phase::
|
|
|
232
|
|
|
233 Dumping phase
|
|
|
234
|
|
|
235 * Object inventory::
|
|
|
236 * Address allocation::
|
|
|
237 * The header::
|
|
|
238 * Data dumping::
|
|
|
239 * Pointers dumping::
|
|
|
240
|
|
428
|
241 Events and the Event Loop
|
|
|
242
|
|
|
243 * Introduction to Events::
|
|
|
244 * Main Loop::
|
|
|
245 * Specifics of the Event Gathering Mechanism::
|
|
|
246 * Specifics About the Emacs Event::
|
|
|
247 * The Event Stream Callback Routines::
|
|
|
248 * Other Event Loop Functions::
|
|
|
249 * Converting Events::
|
|
|
250 * Dispatching Events; The Command Builder::
|
|
|
251
|
|
|
252 Evaluation; Stack Frames; Bindings
|
|
|
253
|
|
|
254 * Evaluation::
|
|
|
255 * Dynamic Binding; The specbinding Stack; Unwind-Protects::
|
|
|
256 * Simple Special Forms::
|
|
|
257 * Catch and Throw::
|
|
|
258
|
|
|
259 Symbols and Variables
|
|
|
260
|
|
|
261 * Introduction to Symbols::
|
|
|
262 * Obarrays::
|
|
|
263 * Symbol Values::
|
|
|
264
|
|
|
265 Buffers and Textual Representation
|
|
|
266
|
|
|
267 * Introduction to Buffers:: A buffer holds a block of text such as a file.
|
|
|
268 * The Text in a Buffer:: Representation of the text in a buffer.
|
|
|
269 * Buffer Lists:: Keeping track of all buffers.
|
|
|
270 * Markers and Extents:: Tagging locations within a buffer.
|
|
1263
|
271 * Ibytes and Ichars:: Representation of individual characters.
|
|
428
|
272 * The Buffer Object:: The Lisp object corresponding to a buffer.
|
|
1496
|
273 * Searching and Matching:: Higher-level algorithms.
|
|
428
|
274
|
|
|
275 MULE Character Sets and Encodings
|
|
|
276
|
|
|
277 * Character Sets::
|
|
|
278 * Encodings::
|
|
|
279 * Internal Mule Encodings::
|
|
442
|
280 * CCL::
|
|
428
|
281
|
|
|
282 Encodings
|
|
|
283
|
|
|
284 * Japanese EUC (Extended Unix Code)::
|
|
|
285 * JIS7::
|
|
|
286
|
|
|
287 Internal Mule Encodings
|
|
|
288
|
|
|
289 * Internal String Encoding::
|
|
|
290 * Internal Character Encoding::
|
|
|
291
|
|
|
292 Lstreams
|
|
|
293
|
|
442
|
294 * Creating an Lstream:: Creating an lstream object.
|
|
|
295 * Lstream Types:: Different sorts of things that are streamed.
|
|
|
296 * Lstream Functions:: Functions for working with lstreams.
|
|
|
297 * Lstream Methods:: Creating new lstream types.
|
|
|
298
|
|
428
|
299 Consoles; Devices; Frames; Windows
|
|
|
300
|
|
|
301 * Introduction to Consoles; Devices; Frames; Windows::
|
|
|
302 * Point::
|
|
|
303 * Window Hierarchy::
|
|
442
|
304 * The Window Object::
|
|
428
|
305
|
|
|
306 The Redisplay Mechanism
|
|
|
307
|
|
|
308 * Critical Redisplay Sections::
|
|
|
309 * Line Start Cache::
|
|
442
|
310 * Redisplay Piece by Piece::
|
|
428
|
311
|
|
|
312 Extents
|
|
|
313
|
|
|
314 * Introduction to Extents:: Extents are ranges over text, with properties.
|
|
|
315 * Extent Ordering:: How extents are ordered internally.
|
|
|
316 * Format of the Extent Info:: The extent information in a buffer or string.
|
|
|
317 * Zero-Length Extents:: A weird special case.
|
|
442
|
318 * Mathematics of Extent Ordering:: A rigorous foundation.
|
|
428
|
319 * Extent Fragments:: Cached information useful for redisplay.
|
|
|
320
|
|
442
|
321 @end detailmenu
|
|
428
|
322 @end menu
|
|
|
323
|
|
|
324 @node A History of Emacs, XEmacs From the Outside, Top, Top
|
|
|
325 @chapter A History of Emacs
|
|
462
|
326 @cindex history of Emacs, a
|
|
|
327 @cindex Emacs, a history of
|
|
428
|
328 @cindex Hackers (Steven Levy)
|
|
|
329 @cindex Levy, Steven
|
|
|
330 @cindex ITS (Incompatible Timesharing System)
|
|
|
331 @cindex Stallman, Richard
|
|
|
332 @cindex RMS
|
|
|
333 @cindex MIT
|
|
|
334 @cindex TECO
|
|
|
335 @cindex FSF
|
|
|
336 @cindex Free Software Foundation
|
|
|
337
|
|
|
338 XEmacs is a powerful, customizable text editor and development
|
|
|
339 environment. It began as Lucid Emacs, which was in turn derived from
|
|
|
340 GNU Emacs, a program written by Richard Stallman of the Free Software
|
|
|
341 Foundation. GNU Emacs dates back to the 1970's, and was modelled
|
|
|
342 after a package called ``Emacs'', written in 1976, that was a set of
|
|
|
343 macros on top of TECO, an old, old text editor written at MIT on the
|
|
|
344 DEC PDP 10 under one of the earliest time-sharing operating systems,
|
|
|
345 ITS (Incompatible Timesharing System). (ITS dates back well before
|
|
|
346 Unix.) ITS, TECO, and Emacs were products of a group of people at MIT
|
|
|
347 who called themselves ``hackers'', who shared an idealistic belief
|
|
|
348 system about the free exchange of information and were fanatical in
|
|
|
349 their devotion to and time spent with computers. (The hacker
|
|
|
350 subculture dates back to the late 1950's at MIT and is described in
|
|
|
351 detail in Steven Levy's book @cite{Hackers}. This book also includes
|
|
|
352 a lot of information about Stallman himself and the development of
|
|
|
353 Lisp, a programming language developed at MIT that underlies Emacs.)
|
|
|
354
|
|
|
355 @menu
|
|
|
356 * Through Version 18:: Unification prevails.
|
|
|
357 * Lucid Emacs:: One version 19 Emacs.
|
|
|
358 * GNU Emacs 19:: The other version 19 Emacs.
|
|
|
359 * GNU Emacs 20:: The other version 20 Emacs.
|
|
|
360 * XEmacs:: The continuation of Lucid Emacs.
|
|
|
361 @end menu
|
|
|
362
|
|
462
|
363 @node Through Version 18
|
|
428
|
364 @section Through Version 18
|
|
462
|
365 @cindex version 18, through
|
|
428
|
366 @cindex Gosling, James
|
|
|
367 @cindex Great Usenet Renaming
|
|
|
368
|
|
|
369 Although the history of the early versions of GNU Emacs is unclear,
|
|
|
370 the history is well-known from the middle of 1985. A time line is:
|
|
|
371
|
|
|
372 @itemize @bullet
|
|
|
373 @item
|
|
|
374 GNU Emacs version 15 (15.34) was released sometime in 1984 or 1985 and
|
|
|
375 shared some code with a version of Emacs written by James Gosling (the
|
|
|
376 same James Gosling who later created the Java language).
|
|
|
377 @item
|
|
|
378 GNU Emacs version 16 (first released version was 16.56) was released on
|
|
|
379 July 15, 1985. All Gosling code was removed due to potential copyright
|
|
|
380 problems with the code.
|
|
|
381 @item
|
|
|
382 version 16.57: released on September 16, 1985.
|
|
|
383 @item
|
|
|
384 versions 16.58, 16.59: released on September 17, 1985.
|
|
|
385 @item
|
|
|
386 version 16.60: released on September 19, 1985. These later version 16's
|
|
|
387 incorporated patches from the net, esp. for getting Emacs to work under
|
|
|
388 System V.
|
|
|
389 @item
|
|
|
390 version 17.36 (first official v17 release) released on December 20,
|
|
|
391 1985. Included a TeX-able user manual. First official unpatched
|
|
|
392 version that worked on vanilla System V machines.
|
|
|
393 @item
|
|
|
394 version 17.43 (second official v17 release) released on January 25,
|
|
|
395 1986.
|
|
|
396 @item
|
|
|
397 version 17.45 released on January 30, 1986.
|
|
|
398 @item
|
|
|
399 version 17.46 released on February 4, 1986.
|
|
|
400 @item
|
|
|
401 version 17.48 released on February 10, 1986.
|
|
|
402 @item
|
|
|
403 version 17.49 released on February 12, 1986.
|
|
|
404 @item
|
|
|
405 version 17.55 released on March 18, 1986.
|
|
|
406 @item
|
|
|
407 version 17.57 released on March 27, 1986.
|
|
|
408 @item
|
|
|
409 version 17.58 released on April 4, 1986.
|
|
|
410 @item
|
|
|
411 version 17.61 released on April 12, 1986.
|
|
|
412 @item
|
|
|
413 version 17.63 released on May 7, 1986.
|
|
|
414 @item
|
|
|
415 version 17.64 released on May 12, 1986.
|
|
|
416 @item
|
|
|
417 version 18.24 (a beta version) released on October 2, 1986.
|
|
|
418 @item
|
|
|
419 version 18.30 (a beta version) released on November 15, 1986.
|
|
|
420 @item
|
|
|
421 version 18.31 (a beta version) released on November 23, 1986.
|
|
|
422 @item
|
|
|
423 version 18.32 (a beta version) released on December 7, 1986.
|
|
|
424 @item
|
|
|
425 version 18.33 (a beta version) released on December 12, 1986.
|
|
|
426 @item
|
|
|
427 version 18.35 (a beta version) released on January 5, 1987.
|
|
|
428 @item
|
|
|
429 version 18.36 (a beta version) released on January 21, 1987.
|
|
|
430 @item
|
|
|
431 January 27, 1987: The Great Usenet Renaming. net.emacs is now
|
|
|
432 comp.emacs.
|
|
|
433 @item
|
|
|
434 version 18.37 (a beta version) released on February 12, 1987.
|
|
|
435 @item
|
|
|
436 version 18.38 (a beta version) released on March 3, 1987.
|
|
|
437 @item
|
|
|
438 version 18.39 (a beta version) released on March 14, 1987.
|
|
|
439 @item
|
|
|
440 version 18.40 (a beta version) released on March 18, 1987.
|
|
|
441 @item
|
|
|
442 version 18.41 (the first ``official'' release) released on March 22,
|
|
|
443 1987.
|
|
|
444 @item
|
|
|
445 version 18.45 released on June 2, 1987.
|
|
|
446 @item
|
|
|
447 version 18.46 released on June 9, 1987.
|
|
|
448 @item
|
|
|
449 version 18.47 released on June 18, 1987.
|
|
|
450 @item
|
|
|
451 version 18.48 released on September 3, 1987.
|
|
|
452 @item
|
|
|
453 version 18.49 released on September 18, 1987.
|
|
|
454 @item
|
|
|
455 version 18.50 released on February 13, 1988.
|
|
|
456 @item
|
|
|
457 version 18.51 released on May 7, 1988.
|
|
|
458 @item
|
|
|
459 version 18.52 released on September 1, 1988.
|
|
|
460 @item
|
|
|
461 version 18.53 released on February 24, 1989.
|
|
|
462 @item
|
|
|
463 version 18.54 released on April 26, 1989.
|
|
|
464 @item
|
|
|
465 version 18.55 released on August 23, 1989. This is the earliest version
|
|
|
466 that is still available by FTP.
|
|
|
467 @item
|
|
|
468 version 18.56 released on January 17, 1991.
|
|
|
469 @item
|
|
|
470 version 18.57 released late January, 1991.
|
|
|
471 @item
|
|
|
472 version 18.58 released ?????.
|
|
|
473 @item
|
|
|
474 version 18.59 released October 31, 1992.
|
|
|
475 @end itemize
|
|
|
476
|
|
462
|
477 @node Lucid Emacs
|
|
428
|
478 @section Lucid Emacs
|
|
|
479 @cindex Lucid Emacs
|
|
|
480 @cindex Lucid Inc.
|
|
|
481 @cindex Energize
|
|
|
482 @cindex Epoch
|
|
|
483
|
|
|
484 Lucid Emacs was developed by the (now-defunct) Lucid Inc., a maker of
|
|
|
485 C++ and Lisp development environments. It began when Lucid decided they
|
|
|
486 wanted to use Emacs as the editor and cornerstone of their C++
|
|
|
487 development environment (called ``Energize''). They needed many features
|
|
|
488 that were not available in the existing version of GNU Emacs (version
|
|
|
489 18.5something), in particular good and integrated support for GUI
|
|
|
490 elements such as mouse support, multiple fonts, multiple window-system
|
|
|
491 windows, etc. A branch of GNU Emacs called Epoch, written at the
|
|
|
492 University of Illinois, existed that supplied many of these features;
|
|
|
493 however, Lucid needed more than what existed in Epoch. At the time, the
|
|
|
494 Free Software Foundation was working on version 19 of Emacs (this was
|
|
|
495 sometime around 1991), which was planned to have similar features, and
|
|
|
496 so Lucid decided to work with the Free Software Foundation. Their plan
|
|
|
497 was to add features that they needed, and coordinate with the FSF so
|
|
|
498 that the features would get included back into Emacs version 19.
|
|
|
499
|
|
|
500 Delays in the release of version 19 occurred, however (resulting in it
|
|
|
501 finally being released more than a year after what was initially
|
|
|
502 planned), and Lucid encountered unexpected technical resistance in
|
|
|
503 getting their changes merged back into version 19, so they decided to
|
|
|
504 release their own version of Emacs, which became Lucid Emacs 19.0.
|
|
|
505
|
|
|
506 @cindex Zawinski, Jamie
|
|
|
507 @cindex Sexton, Harlan
|
|
|
508 @cindex Benson, Eric
|
|
|
509 @cindex Devin, Matthieu
|
|
|
510 The initial authors of Lucid Emacs were Matthieu Devin, Harlan Sexton,
|
|
|
511 and Eric Benson, and the work was later taken over by Jamie Zawinski,
|
|
|
512 who became ``Mr. Lucid Emacs'' for many releases.
|
|
|
513
|
|
464
|
514 A time line for Lucid Emacs is
|
|
428
|
515
|
|
|
516 @itemize @bullet
|
|
|
517 @item
|
|
|
518 version 19.0 shipped with Energize 1.0, April 1992.
|
|
|
519 @item
|
|
|
520 version 19.1 released June 4, 1992.
|
|
|
521 @item
|
|
|
522 version 19.2 released June 19, 1992.
|
|
|
523 @item
|
|
|
524 version 19.3 released September 9, 1992.
|
|
|
525 @item
|
|
|
526 version 19.4 released January 21, 1993.
|
|
|
527 @item
|
|
|
528 version 19.5 was a repackaging of 19.4 with a few bug fixes and
|
|
|
529 shipped with Energize 2.0. Never released to the net.
|
|
|
530 @item
|
|
|
531 version 19.6 released April 9, 1993.
|
|
|
532 @item
|
|
|
533 version 19.7 was a repackaging of 19.6 with a few bug fixes and
|
|
|
534 shipped with Energize 2.1. Never released to the net.
|
|
|
535 @item
|
|
|
536 version 19.8 released September 6, 1993.
|
|
|
537 @item
|
|
|
538 version 19.9 released January 12, 1994.
|
|
|
539 @item
|
|
|
540 version 19.10 released May 27, 1994.
|
|
|
541 @end itemize
|
|
|
542
|
|
462
|
543 @node GNU Emacs 19
|
|
428
|
544 @section GNU Emacs 19
|
|
|
545 @cindex GNU Emacs 19
|
|
462
|
546 @cindex Emacs 19, GNU
|
|
|
547 @cindex version 19, GNU Emacs
|
|
428
|
548 @cindex FSF Emacs
|
|
|
549
|
|
|
550 About a year after the initial release of Lucid Emacs, the FSF
|
|
|
551 released a beta of their version of Emacs 19 (referred to here as ``GNU
|
|
|
552 Emacs''). By this time, the current version of Lucid Emacs was
|
|
|
553 19.6. (Strangely, the first released beta from the FSF was GNU Emacs
|
|
|
554 19.7.) A time line for GNU Emacs version 19 is
|
|
|
555
|
|
|
556 @itemize @bullet
|
|
|
557 @item
|
|
|
558 version 19.8 (beta) released May 27, 1993.
|
|
|
559 @item
|
|
|
560 version 19.9 (beta) released May 27, 1993.
|
|
|
561 @item
|
|
|
562 version 19.10 (beta) released May 30, 1993.
|
|
|
563 @item
|
|
|
564 version 19.11 (beta) released June 1, 1993.
|
|
|
565 @item
|
|
|
566 version 19.12 (beta) released June 2, 1993.
|
|
|
567 @item
|
|
|
568 version 19.13 (beta) released June 8, 1993.
|
|
|
569 @item
|
|
|
570 version 19.14 (beta) released June 17, 1993.
|
|
|
571 @item
|
|
|
572 version 19.15 (beta) released June 19, 1993.
|
|
|
573 @item
|
|
|
574 version 19.16 (beta) released July 6, 1993.
|
|
|
575 @item
|
|
|
576 version 19.17 (beta) released late July, 1993.
|
|
|
577 @item
|
|
|
578 version 19.18 (beta) released August 9, 1993.
|
|
|
579 @item
|
|
|
580 version 19.19 (beta) released August 15, 1993.
|
|
|
581 @item
|
|
|
582 version 19.20 (beta) released November 17, 1993.
|
|
|
583 @item
|
|
|
584 version 19.21 (beta) released November 17, 1993.
|
|
|
585 @item
|
|
|
586 version 19.22 (beta) released November 28, 1993.
|
|
|
587 @item
|
|
|
588 version 19.23 (beta) released May 17, 1994.
|
|
|
589 @item
|
|
|
590 version 19.24 (beta) released May 16, 1994.
|
|
|
591 @item
|
|
|
592 version 19.25 (beta) released June 3, 1994.
|
|
|
593 @item
|
|
|
594 version 19.26 (beta) released September 11, 1994.
|
|
|
595 @item
|
|
|
596 version 19.27 (beta) released September 14, 1994.
|
|
|
597 @item
|
|
|
598 version 19.28 (first ``official'' release) released November 1, 1994.
|
|
|
599 @item
|
|
|
600 version 19.29 released June 21, 1995.
|
|
|
601 @item
|
|
|
602 version 19.30 released November 24, 1995.
|
|
|
603 @item
|
|
|
604 version 19.31 released May 25, 1996.
|
|
|
605 @item
|
|
|
606 version 19.32 released July 31, 1996.
|
|
|
607 @item
|
|
|
608 version 19.33 released August 11, 1996.
|
|
|
609 @item
|
|
|
610 version 19.34 released August 21, 1996.
|
|
|
611 @item
|
|
|
612 version 19.34b released September 6, 1996.
|
|
|
613 @end itemize
|
|
|
614
|
|
|
615 @cindex Mlynarik, Richard
|
|
|
616 In some ways, GNU Emacs 19 was better than Lucid Emacs; in some ways,
|
|
|
617 worse. Lucid soon began incorporating features from GNU Emacs 19 into
|
|
|
618 Lucid Emacs; the work was mostly done by Richard Mlynarik, who had been
|
|
|
619 working on and using GNU Emacs for a long time (back as far as version
|
|
|
620 16 or 17).
|
|
|
621
|
|
462
|
622 @node GNU Emacs 20
|
|
428
|
623 @section GNU Emacs 20
|
|
|
624 @cindex GNU Emacs 20
|
|
462
|
625 @cindex Emacs 20, GNU
|
|
|
626 @cindex version 20, GNU Emacs
|
|
428
|
627 @cindex FSF Emacs
|
|
|
628
|
|
|
629 On February 2, 1997 work began on GNU Emacs to integrate Mule. The first
|
|
|
630 release was made in September of that year.
|
|
|
631
|
|
|
632 A timeline for Emacs 20 is
|
|
|
633
|
|
|
634 @itemize @bullet
|
|
|
635 @item
|
|
|
636 version 20.1 released September 17, 1997.
|
|
|
637 @item
|
|
|
638 version 20.2 released September 20, 1997.
|
|
|
639 @item
|
|
|
640 version 20.3 released August 19, 1998.
|
|
|
641 @end itemize
|
|
|
642
|
|
462
|
643 @node XEmacs
|
|
428
|
644 @section XEmacs
|
|
|
645 @cindex XEmacs
|
|
|
646
|
|
|
647 @cindex Sun Microsystems
|
|
|
648 @cindex University of Illinois
|
|
|
649 @cindex Illinois, University of
|
|
|
650 @cindex SPARCWorks
|
|
|
651 @cindex Andreessen, Marc
|
|
|
652 @cindex Baur, Steve
|
|
|
653 @cindex Buchholz, Martin
|
|
|
654 @cindex Kaplan, Simon
|
|
|
655 @cindex Wing, Ben
|
|
|
656 @cindex Thompson, Chuck
|
|
|
657 @cindex Win-Emacs
|
|
|
658 @cindex Epoch
|
|
|
659 @cindex Amdahl Corporation
|
|
|
660 Around the time that Lucid was developing Energize, Sun Microsystems
|
|
|
661 was developing their own development environment (called ``SPARCWorks'')
|
|
|
662 and also decided to use Emacs. They joined forces with the Epoch team
|
|
|
663 at the University of Illinois and later with Lucid. The maintainer of
|
|
|
664 the last-released version of Epoch was Marc Andreessen, but he dropped
|
|
|
665 out and the Epoch project, headed by Simon Kaplan, lured Chuck Thompson
|
|
|
666 away from a system administration job to become the primary Lucid Emacs
|
|
|
667 author for Epoch and Sun. Chuck's area of specialty became the
|
|
|
668 redisplay engine (he replaced the old Lucid Emacs redisplay engine with
|
|
|
669 a ported version from Epoch and then later rewrote it from scratch).
|
|
|
670 Sun also hired Ben Wing (the author of Win-Emacs, a port of Lucid Emacs
|
|
|
671 to Microsoft Windows 3.1) in 1993, for what was initially a one-month
|
|
|
672 contract to fix some event problems but later became a many-year
|
|
|
673 involvement, punctuated by a six-month contract with Amdahl Corporation.
|
|
|
674
|
|
|
675 @cindex rename to XEmacs
|
|
|
676 In 1994, Sun and Lucid agreed to rename Lucid Emacs to XEmacs (a name
|
|
|
677 not favorable to either company); the first release called XEmacs was
|
|
|
678 version 19.11. In June 1994, Lucid folded and Jamie quit to work for
|
|
|
679 the newly formed Mosaic Communications Corp., later Netscape
|
|
|
680 Communications Corp. (co-founded by the same Marc Andreessen, who had
|
|
|
681 quit his Epoch job to work on a graphical browser for the World Wide
|
|
|
682 Web). Chuck then become the primary maintainer of XEmacs, and put out
|
|
|
683 versions 19.11 through 19.14 in conjunction with Ben. For 19.12 and
|
|
|
684 19.13, Chuck added the new redisplay and many other display improvements
|
|
|
685 and Ben added MULE support (support for Asian and other languages) and
|
|
|
686 redesigned most of the internal Lisp subsystems to better support the
|
|
|
687 MULE work and the various other features being added to XEmacs. After
|
|
|
688 19.14 Chuck retired as primary maintainer and Steve Baur stepped in.
|
|
|
689
|
|
|
690 @cindex MULE merged XEmacs appears
|
|
|
691 Soon after 19.13 was released, work began in earnest on the MULE
|
|
|
692 internationalization code and the source tree was divided into two
|
|
|
693 development paths. The MULE version was initially called 19.20, but was
|
|
|
694 soon renamed to 20.0. In 1996 Martin Buchholz of Sun Microsystems took
|
|
|
695 over the care and feeding of it and worked on it in parallel with the
|
|
|
696 19.14 development that was occurring at the same time. After much work
|
|
|
697 by Martin, it was decided to release 20.0 ahead of 19.15 in February
|
|
|
698 1997. The source tree remained divided until 20.2 when the version 19
|
|
|
699 source was finally retired at version 19.16.
|
|
|
700
|
|
|
701 @cindex Baur, Steve
|
|
|
702 @cindex Buchholz, Martin
|
|
|
703 @cindex Jones, Kyle
|
|
|
704 @cindex Niksic, Hrvoje
|
|
|
705 @cindex XEmacs goes it alone
|
|
|
706 In 1997, Sun finally dropped all pretense of support for XEmacs and
|
|
|
707 Martin Buchholz left the company in November. Since then, and mostly
|
|
|
708 for the previous year, because Steve Baur was never paid to work on
|
|
|
709 XEmacs, XEmacs has existed solely on the contributions of volunteers
|
|
|
710 from the Free Software Community. Starting from 1997, Hrvoje Niksic and
|
|
|
711 Kyle Jones have figured prominently in XEmacs development.
|
|
|
712
|
|
|
713 @cindex merging attempts
|
|
|
714 Many attempts have been made to merge XEmacs and GNU Emacs, but they
|
|
|
715 have consistently failed.
|
|
|
716
|
|
|
717 A more detailed history is contained in the XEmacs About page.
|
|
|
718
|
|
464
|
719 A time line for XEmacs is
|
|
|
720
|
|
|
721 @itemize @bullet
|
|
|
722 @item
|
|
|
723 version 19.11 (first XEmacs) released September 13, 1994.
|
|
|
724 @item
|
|
|
725 version 19.12 released June 23, 1995.
|
|
|
726 @item
|
|
|
727 version 19.13 released September 1, 1995.
|
|
|
728 @item
|
|
|
729 version 19.14 released June 23, 1996.
|
|
|
730 @item
|
|
|
731 version 20.0 released February 9, 1997.
|
|
|
732 @item
|
|
|
733 version 19.15 released March 28, 1997.
|
|
|
734 @item
|
|
|
735 version 20.1 (not released to the net) April 15, 1997.
|
|
|
736 @item
|
|
|
737 version 20.2 released May 16, 1997.
|
|
|
738 @item
|
|
|
739 version 19.16 released October 31, 1997.
|
|
|
740 @item
|
|
|
741 version 20.3 (the first stable version of XEmacs 20.x) released November 30,
|
|
|
742 1997.
|
|
|
743 @item
|
|
|
744 version 20.4 released February 28, 1998.
|
|
|
745 @item
|
|
|
746 version 21.0.60 released December 10, 1998. (The version naming scheme was
|
|
|
747 changed at this point: [a] the second version number is odd for stable
|
|
|
748 versions, even for beta versions; [b] a third version number is added,
|
|
|
749 replacing the "beta xxx" ending for beta versions and allowing for
|
|
|
750 periodic maintenance releases for stable versions. Therefore, 21.0 was
|
|
|
751 never "officially" released; similarly for 21.2, etc.)
|
|
|
752 @item
|
|
|
753 version 21.0.61 released January 4, 1999.
|
|
|
754 @item
|
|
|
755 version 21.0.63 released February 3, 1999.
|
|
|
756 @item
|
|
|
757 version 21.0.64 released March 1, 1999.
|
|
|
758 @item
|
|
|
759 version 21.0.65 released March 5, 1999.
|
|
|
760 @item
|
|
|
761 version 21.0.66 released March 12, 1999.
|
|
|
762 @item
|
|
|
763 version 21.0.67 released March 25, 1999.
|
|
|
764 @item
|
|
|
765 version 21.1.2 released May 14, 1999. (This is the followup to 21.0.67.
|
|
|
766 The second version number was bumped to indicate the beginning of the
|
|
|
767 "stable" series.)
|
|
|
768 @item
|
|
|
769 version 21.1.3 released June 26, 1999.
|
|
|
770 @item
|
|
|
771 version 21.1.4 released July 8, 1999.
|
|
|
772 @item
|
|
|
773 version 21.1.6 released August 14, 1999. (There was no 21.1.5.)
|
|
|
774 @item
|
|
|
775 version 21.1.7 released September 26, 1999.
|
|
|
776 @item
|
|
|
777 version 21.1.8 released November 2, 1999.
|
|
|
778 @item
|
|
|
779 version 21.1.9 released February 13, 2000.
|
|
|
780 @item
|
|
|
781 version 21.1.10 released May 7, 2000.
|
|
|
782 @item
|
|
|
783 version 21.1.10a released June 24, 2000.
|
|
|
784 @item
|
|
|
785 version 21.1.11 released July 18, 2000.
|
|
|
786 @item
|
|
|
787 version 21.1.12 released August 5, 2000.
|
|
|
788 @item
|
|
|
789 version 21.1.13 released January 7, 2001.
|
|
|
790 @item
|
|
|
791 version 21.1.14 released January 27, 2001.
|
|
|
792 @item
|
|
|
793 version 21.2.9 released February 3, 1999.
|
|
|
794 @item
|
|
|
795 version 21.2.10 released February 5, 1999.
|
|
|
796 @item
|
|
|
797 version 21.2.11 released March 1, 1999.
|
|
|
798 @item
|
|
|
799 version 21.2.12 released March 5, 1999.
|
|
|
800 @item
|
|
|
801 version 21.2.13 released March 12, 1999.
|
|
|
802 @item
|
|
|
803 version 21.2.14 released May 14, 1999.
|
|
|
804 @item
|
|
|
805 version 21.2.15 released June 4, 1999.
|
|
|
806 @item
|
|
|
807 version 21.2.16 released June 11, 1999.
|
|
|
808 @item
|
|
|
809 version 21.2.17 released June 22, 1999.
|
|
|
810 @item
|
|
|
811 version 21.2.18 released July 14, 1999.
|
|
|
812 @item
|
|
|
813 version 21.2.19 released July 30, 1999.
|
|
|
814 @item
|
|
|
815 version 21.2.20 released November 10, 1999.
|
|
|
816 @item
|
|
|
817 version 21.2.21 released November 28, 1999.
|
|
|
818 @item
|
|
|
819 version 21.2.22 released November 29, 1999.
|
|
|
820 @item
|
|
|
821 version 21.2.23 released December 7, 1999.
|
|
|
822 @item
|
|
|
823 version 21.2.24 released December 14, 1999.
|
|
|
824 @item
|
|
|
825 version 21.2.25 released December 24, 1999.
|
|
|
826 @item
|
|
|
827 version 21.2.26 released December 31, 1999.
|
|
|
828 @item
|
|
|
829 version 21.2.27 released January 18, 2000.
|
|
|
830 @item
|
|
|
831 version 21.2.28 released February 7, 2000.
|
|
|
832 @item
|
|
|
833 version 21.2.29 released February 16, 2000.
|
|
|
834 @item
|
|
|
835 version 21.2.30 released February 21, 2000.
|
|
|
836 @item
|
|
|
837 version 21.2.31 released February 23, 2000.
|
|
|
838 @item
|
|
|
839 version 21.2.32 released March 20, 2000.
|
|
|
840 @item
|
|
|
841 version 21.2.33 released May 1, 2000.
|
|
|
842 @item
|
|
|
843 version 21.2.34 released May 28, 2000.
|
|
|
844 @item
|
|
|
845 version 21.2.35 released July 19, 2000.
|
|
|
846 @item
|
|
|
847 version 21.2.36 released October 4, 2000.
|
|
|
848 @item
|
|
|
849 version 21.2.37 released November 14, 2000.
|
|
|
850 @item
|
|
|
851 version 21.2.38 released December 5, 2000.
|
|
|
852 @item
|
|
|
853 version 21.2.39 released December 31, 2000.
|
|
|
854 @item
|
|
|
855 version 21.2.40 released January 8, 2001.
|
|
|
856 @item
|
|
|
857 version 21.2.41 released January 17, 2001.
|
|
|
858 @item
|
|
|
859 version 21.2.42 released January 20, 2001.
|
|
|
860 @item
|
|
|
861 version 21.2.43 released January 26, 2001.
|
|
|
862 @item
|
|
|
863 version 21.2.44 released February 8, 2001.
|
|
|
864 @item
|
|
|
865 version 21.2.45 released February 23, 2001.
|
|
|
866 @item
|
|
|
867 version 21.2.46 released March 21, 2001.
|
|
|
868 @end itemize
|
|
|
869
|
|
428
|
870 @node XEmacs From the Outside, The Lisp Language, A History of Emacs, Top
|
|
|
871 @chapter XEmacs From the Outside
|
|
462
|
872 @cindex XEmacs from the outside
|
|
|
873 @cindex outside, XEmacs from the
|
|
428
|
874 @cindex read-eval-print
|
|
|
875
|
|
|
876 XEmacs appears to the outside world as an editor, but it is really a
|
|
|
877 Lisp environment. At its heart is a Lisp interpreter; it also
|
|
|
878 ``happens'' to contain many specialized object types (e.g. buffers,
|
|
|
879 windows, frames, events) that are useful for implementing an editor.
|
|
|
880 Some of these objects (in particular windows and frames) have
|
|
|
881 displayable representations, and XEmacs provides a function
|
|
|
882 @code{redisplay()} that ensures that the display of all such objects
|
|
|
883 matches their internal state. Most of the time, a standard Lisp
|
|
440
|
884 environment is in a @dfn{read-eval-print} loop---i.e. ``read some Lisp
|
|
428
|
885 code, execute it, and print the results''. XEmacs has a similar loop:
|
|
|
886
|
|
|
887 @itemize @bullet
|
|
|
888 @item
|
|
|
889 read an event
|
|
|
890 @item
|
|
|
891 dispatch the event (i.e. ``do it'')
|
|
|
892 @item
|
|
|
893 redisplay
|
|
|
894 @end itemize
|
|
|
895
|
|
|
896 Reading an event is done using the Lisp function @code{next-event},
|
|
|
897 which waits for something to happen (typically, the user presses a key
|
|
|
898 or moves the mouse) and returns an event object describing this.
|
|
|
899 Dispatching an event is done using the Lisp function
|
|
|
900 @code{dispatch-event}, which looks up the event in a keymap object (a
|
|
|
901 particular kind of object that associates an event with a Lisp function)
|
|
|
902 and calls that function. The function ``does'' what the user has
|
|
|
903 requested by changing the state of particular frame objects, buffer
|
|
|
904 objects, etc. Finally, @code{redisplay()} is called, which updates the
|
|
|
905 display to reflect those changes just made. Thus is an ``editor'' born.
|
|
|
906
|
|
|
907 @cindex bridge, playing
|
|
|
908 @cindex taxes, doing
|
|
|
909 @cindex pi, calculating
|
|
|
910 Note that you do not have to use XEmacs as an editor; you could just
|
|
|
911 as well make it do your taxes, compute pi, play bridge, etc. You'd just
|
|
|
912 have to write functions to do those operations in Lisp.
|
|
|
913
|
|
|
914 @node The Lisp Language, XEmacs From the Perspective of Building, XEmacs From the Outside, Top
|
|
|
915 @chapter The Lisp Language
|
|
462
|
916 @cindex Lisp language, the
|
|
428
|
917 @cindex Lisp vs. C
|
|
|
918 @cindex C vs. Lisp
|
|
|
919 @cindex Lisp vs. Java
|
|
|
920 @cindex Java vs. Lisp
|
|
|
921 @cindex dynamic scoping
|
|
|
922 @cindex scoping, dynamic
|
|
|
923 @cindex dynamic types
|
|
|
924 @cindex types, dynamic
|
|
|
925 @cindex Java
|
|
|
926 @cindex Common Lisp
|
|
|
927 @cindex Gosling, James
|
|
|
928
|
|
|
929 Lisp is a general-purpose language that is higher-level than C and in
|
|
|
930 many ways more powerful than C. Powerful dialects of Lisp such as
|
|
|
931 Common Lisp are probably much better languages for writing very large
|
|
|
932 applications than is C. (Unfortunately, for many non-technical
|
|
|
933 reasons C and its successor C++ have become the dominant languages for
|
|
|
934 application development. These languages are both inadequate for
|
|
|
935 extremely large applications, which is evidenced by the fact that newer,
|
|
|
936 larger programs are becoming ever harder to write and are requiring ever
|
|
|
937 more programmers despite great increases in C development environments;
|
|
|
938 and by the fact that, although hardware speeds and reliability have been
|
|
|
939 growing at an exponential rate, most software is still generally
|
|
|
940 considered to be slow and buggy.)
|
|
|
941
|
|
|
942 The new Java language holds promise as a better general-purpose
|
|
|
943 development language than C. Java has many features in common with
|
|
|
944 Lisp that are not shared by C (this is not a coincidence, since
|
|
|
945 Java was designed by James Gosling, a former Lisp hacker). This
|
|
|
946 will be discussed more later.
|
|
|
947
|
|
|
948 For those used to C, here is a summary of the basic differences between
|
|
|
949 C and Lisp:
|
|
|
950
|
|
|
951 @enumerate
|
|
|
952 @item
|
|
|
953 Lisp has an extremely regular syntax. Every function, expression,
|
|
|
954 and control statement is written in the form
|
|
|
955
|
|
|
956 @example
|
|
|
957 (@var{func} @var{arg1} @var{arg2} ...)
|
|
|
958 @end example
|
|
|
959
|
|
|
960 This is as opposed to C, which writes functions as
|
|
|
961
|
|
|
962 @example
|
|
|
963 func(@var{arg1}, @var{arg2}, ...)
|
|
|
964 @end example
|
|
|
965
|
|
|
966 but writes expressions involving operators as (e.g.)
|
|
|
967
|
|
|
968 @example
|
|
|
969 @var{arg1} + @var{arg2}
|
|
|
970 @end example
|
|
|
971
|
|
|
972 and writes control statements as (e.g.)
|
|
|
973
|
|
|
974 @example
|
|
|
975 while (@var{expr}) @{ @var{statement1}; @var{statement2}; ... @}
|
|
|
976 @end example
|
|
|
977
|
|
|
978 Lisp equivalents of the latter two would be
|
|
|
979
|
|
|
980 @example
|
|
|
981 (+ @var{arg1} @var{arg2} ...)
|
|
|
982 @end example
|
|
|
983
|
|
|
984 and
|
|
|
985
|
|
|
986 @example
|
|
|
987 (while @var{expr} @var{statement1} @var{statement2} ...)
|
|
|
988 @end example
|
|
|
989
|
|
|
990 @item
|
|
|
991 Lisp is a safe language. Assuming there are no bugs in the Lisp
|
|
|
992 interpreter/compiler, it is impossible to write a program that ``core
|
|
|
993 dumps'' or otherwise causes the machine to execute an illegal
|
|
|
994 instruction. This is very different from C, where perhaps the most
|
|
|
995 common outcome of a bug is exactly such a crash. A corollary of this is that
|
|
|
996 the C operation of casting a pointer is impossible (and unnecessary) in
|
|
|
997 Lisp, and that it is impossible to access memory outside the bounds of
|
|
|
998 an array.
|
|
|
999
|
|
|
1000 @item
|
|
|
1001 Programs and data are written in the same form. The
|
|
|
1002 parenthesis-enclosing form described above for statements is the same
|
|
|
1003 form used for the most common data type in Lisp, the list. Thus, it is
|
|
|
1004 possible to represent any Lisp program using Lisp data types, and for
|
|
|
1005 one program to construct Lisp statements and then dynamically
|
|
|
1006 @dfn{evaluate} them, or cause them to execute.
|
|
|
1007
|
|
|
1008 @item
|
|
|
1009 All objects are @dfn{dynamically typed}. This means that part of every
|
|
|
1010 object is an indication of what type it is. A Lisp program can
|
|
|
1011 manipulate an object without knowing what type it is, and can query an
|
|
|
1012 object to determine its type. This means that, correspondingly,
|
|
|
1013 variables and function parameters can hold objects of any type and are
|
|
|
1014 not normally declared as being of any particular type. This is opposed
|
|
|
1015 to the @dfn{static typing} of C, where variables can hold exactly one
|
|
|
1016 type of object and must be declared as such, and objects do not contain
|
|
|
1017 an indication of their type because it's implicit in the variables they
|
|
|
1018 are stored in. It is possible in C to have a variable hold different
|
|
|
1019 types of objects (e.g. through the use of @code{void *} pointers or
|
|
|
1020 variable-argument functions), but the type information must then be
|
|
|
1021 passed explicitly in some other fashion, leading to additional program
|
|
|
1022 complexity.
|
|
|
1023
|
|
|
1024 @item
|
|
|
1025 Allocated memory is automatically reclaimed when it is no longer in use.
|
|
|
1026 This operation is called @dfn{garbage collection} and involves looking
|
|
|
1027 through all variables to see what memory is being pointed to, and
|
|
|
1028 reclaiming any memory that is not pointed to and is thus
|
|
|
1029 ``inaccessible'' and out of use. This is as opposed to C, in which
|
|
|
1030 allocated memory must be explicitly reclaimed using @code{free()}. If
|
|
|
1031 you simply drop all pointers to memory without freeing it, it becomes
|
|
|
1032 ``leaked'' memory that still takes up space. Over a long period of
|
|
|
1033 time, this can cause your program to grow and grow until it runs out of
|
|
|
1034 memory.
|
|
|
1035
|
|
|
1036 @item
|
|
|
1037 Lisp has built-in facilities for handling errors and exceptions. In C,
|
|
|
1038 when an error occurs, usually either the program exits entirely or the
|
|
|
1039 routine in which the error occurs returns a value indicating this. If
|
|
|
1040 an error occurs in a deeply-nested routine, then every routine currently
|
|
|
1041 called must unwind itself normally and return an error value back up to
|
|
|
1042 the next routine. This means that every routine must explicitly check
|
|
|
1043 for an error in all the routines it calls; if it does not do so,
|
|
|
1044 unexpected and often random behavior results. This is an extremely
|
|
|
1045 common source of bugs in C programs. An alternative would be to do a
|
|
|
1046 non-local exit using @code{longjmp()}, but that is often very dangerous
|
|
|
1047 because the routines that were exited past had no opportunity to clean
|
|
|
1048 up after themselves and may leave things in an inconsistent state,
|
|
|
1049 causing a crash shortly afterwards.
|
|
|
1050
|
|
|
1051 Lisp provides mechanisms to make such non-local exits safe. When an
|
|
|
1052 error occurs, a routine simply signals that an error of a particular
|
|
|
1053 class has occurred, and a non-local exit takes place. Any routine can
|
|
|
1054 trap errors occurring in routines it calls by registering an error
|
|
|
1055 handler for some or all classes of errors. (If no handler is registered,
|
|
|
1056 a default handler, generally installed by the top-level event loop, is
|
|
|
1057 executed; this prints out the error and continues.) Routines can also
|
|
|
1058 specify cleanup code (called an @dfn{unwind-protect}) that will be
|
|
|
1059 called when control exits from a block of code, no matter how that exit
|
|
440
|
1060 occurs---i.e. even if a function deeply nested below it causes a
|
|
428
|
1061 non-local exit back to the top level.
|
|
|
1062
|
|
|
1063 Note that this facility has appeared in some recent vintages of C, in
|
|
|
1064 particular Visual C++ and other PC compilers written for the Microsoft
|
|
|
1065 Win32 API.
|
|
|
1066
|
|
|
1067 @item
|
|
|
1068 In Emacs Lisp, local variables are @dfn{dynamically scoped}. This means
|
|
|
1069 that if you declare a local variable in a particular function, and then
|
|
|
1070 call another function, that subfunction can ``see'' the local variable
|
|
|
1071 you declared. This is actually considered a bug in Emacs Lisp and in
|
|
|
1072 all other early dialects of Lisp, and was corrected in Common Lisp. (In
|
|
|
1073 Common Lisp, you can still declare dynamically scoped variables if you
|
|
440
|
1074 want to---they are sometimes useful---but variables by default are
|
|
428
|
1075 @dfn{lexically scoped} as in C.)
|
|
|
1076 @end enumerate
|
|
|
1077
|
|
|
1078 For those familiar with Lisp, Emacs Lisp is modelled after MacLisp, an
|
|
|
1079 early dialect of Lisp developed at MIT (no relation to the Macintosh
|
|
|
1080 computer). There is a Common Lisp compatibility package available for
|
|
|
1081 Emacs that provides many of the features of Common Lisp.
|
|
|
1082
|
|
|
1083 The Java language is derived in many ways from C, and shares a similar
|
|
|
1084 syntax, but has the following features in common with Lisp (and different
|
|
|
1085 from C):
|
|
|
1086
|
|
|
1087 @enumerate
|
|
|
1088 @item
|
|
|
1089 Java is a safe language, like Lisp.
|
|
|
1090 @item
|
|
|
1091 Java provides garbage collection, like Lisp.
|
|
|
1092 @item
|
|
|
1093 Java has built-in facilities for handling errors and exceptions, like
|
|
|
1094 Lisp.
|
|
|
1095 @item
|
|
|
1096 Java has a type system that combines the best advantages of both static
|
|
|
1097 and dynamic typing. Objects (except very simple types) are explicitly
|
|
|
1098 marked with their type, as in dynamic typing; but there is a hierarchy
|
|
|
1099 of types and functions are declared to accept only certain types, thus
|
|
|
1100 providing the increased compile-time error-checking of static typing.
|
|
|
1101 @end enumerate
|
|
|
1102
|
|
|
1103 The Java language also has some negative attributes:
|
|
|
1104
|
|
|
1105 @enumerate
|
|
|
1106 @item
|
|
|
1107 Java uses the edit/compile/run model of software development. This
|
|
|
1108 makes it hard to use interactively. For example, to use Java like
|
|
|
1109 @code{bc} it is necessary to write a special purpose, albeit tiny,
|
|
|
1110 application. In Emacs Lisp, a calculator comes built-in without any
|
|
|
1111 effort - one can always just type an expression in the @code{*scratch*}
|
|
|
1112 buffer.
|
|
|
1113 @item
|
|
|
1114 Java tries too hard to enforce, not merely enable, portability, making
|
|
|
1115 ordinary access to standard OS facilities painful. Java has an
|
|
|
1116 @dfn{agenda}. I think this is why @code{chdir} is not part of standard
|
|
|
1117 Java, which is inexcusable.
|
|
|
1118 @end enumerate
|
|
|
1119
|
|
|
1120 Unfortunately, there is no perfect language. Static typing allows a
|
|
|
1121 compiler to catch programmer errors and produce more efficient code, but
|
|
442
|
1122 makes programming more tedious and less fun. For the foreseeable future,
|
|
428
|
1123 an Ideal Editing and Programming Environment (and that is what XEmacs
|
|
|
1124 aspires to) will be programmable in multiple languages: high level ones
|
|
|
1125 like Lisp for user customization and prototyping, and lower level ones
|
|
|
1126 for infrastructure and industrial strength applications. If I had my
|
|
|
1127 way, XEmacs would be friendly towards the Python, Scheme, C++, ML,
|
|
|
1128 etc... communities. But there are serious technical difficulties to
|
|
|
1129 achieving that goal.
|
|
|
1130
|
|
|
1131 The word @dfn{application} in the previous paragraph was used
|
|
|
1132 intentionally. XEmacs implements an API for programs written in Lisp
|
|
|
1133 that makes it a full-fledged application platform, very much like an OS
|
|
|
1134 inside the real OS.
|
|
|
1135
|
|
1333
|
1136 @node XEmacs From the Perspective of Building, Build-Time Dependencies, The Lisp Language, Top
|
|
428
|
1137 @chapter XEmacs From the Perspective of Building
|
|
462
|
1138 @cindex XEmacs from the perspective of building
|
|
|
1139 @cindex building, XEmacs from the perspective of
|
|
428
|
1140
|
|
|
1141 The heart of XEmacs is the Lisp environment, which is written in C.
|
|
|
1142 This is contained in the @file{src/} subdirectory. Underneath
|
|
|
1143 @file{src/} are two subdirectories of header files: @file{s/} (header
|
|
|
1144 files for particular operating systems) and @file{m/} (header files for
|
|
|
1145 particular machine types). In practice the distinction between the two
|
|
|
1146 types of header files is blurred. These header files define or undefine
|
|
|
1147 certain preprocessor constants and macros to indicate particular
|
|
|
1148 characteristics of the associated machine or operating system. As part
|
|
|
1149 of the configure process, one @file{s/} file and one @file{m/} file is
|
|
|
1150 identified for the particular environment in which XEmacs is being
|
|
|
1151 built.
|
|
|
1152
|
|
|
1153 XEmacs also contains a great deal of Lisp code. This implements the
|
|
|
1154 operations that make XEmacs useful as an editor as well as just a Lisp
|
|
|
1155 environment, and also contains many add-on packages that allow XEmacs to
|
|
|
1156 browse directories, act as a mail and Usenet news reader, compile Lisp
|
|
|
1157 code, etc. There is actually more Lisp code than C code associated with
|
|
|
1158 XEmacs, but much of the Lisp code is peripheral to the actual operation
|
|
|
1159 of the editor. The Lisp code all lies in subdirectories underneath the
|
|
|
1160 @file{lisp/} directory.
|
|
|
1161
|
|
|
1162 The @file{lwlib/} directory contains C code that implements a
|
|
|
1163 generalized interface onto different X widget toolkits and also
|
|
|
1164 implements some widgets of its own that behave like Motif widgets but
|
|
|
1165 are faster, free, and in some cases more powerful. The code in this
|
|
|
1166 directory compiles into a library and is mostly independent from XEmacs.
|
|
|
1167
|
|
|
1168 The @file{etc/} directory contains various data files associated with
|
|
|
1169 XEmacs. Some of them are actually read by XEmacs at startup; others
|
|
|
1170 merely contain useful information of various sorts.
|
|
|
1171
|
|
|
1172 The @file{lib-src/} directory contains C code for various auxiliary
|
|
|
1173 programs that are used in connection with XEmacs. Some of them are used
|
|
|
1174 during the build process; others are used to perform certain functions
|
|
|
1175 that cannot conveniently be placed in the XEmacs executable (e.g. the
|
|
|
1176 @file{movemail} program for fetching mail out of @file{/var/spool/mail},
|
|
|
1177 which must be setgid to @file{mail} on many systems; and the
|
|
|
1178 @file{gnuclient} program, which allows an external script to communicate
|
|
|
1179 with a running XEmacs process).
|
|
|
1180
|
|
|
1181 The @file{man/} directory contains the sources for the XEmacs
|
|
|
1182 documentation. It is mostly in a form called Texinfo, which can be
|
|
|
1183 converted into either a printed document (by passing it through @TeX{})
|
|
|
1184 or into on-line documentation called @dfn{info files}.
|
|
|
1185
|
|
|
1186 The @file{info/} directory contains the results of formatting the XEmacs
|
|
|
1187 documentation as @dfn{info files}, for on-line use. These files are
|
|
|
1188 used when you enter the Info system using @kbd{C-h i} or through the
|
|
|
1189 Help menu.
|
|
|
1190
|
|
|
1191 The @file{dynodump/} directory contains auxiliary code used to build
|
|
|
1192 XEmacs on Solaris platforms.
|
|
|
1193
|
|
|
1194 The other directories contain various miscellaneous code and information
|
|
|
1195 that is not normally used or needed.
|
|
|
1196
|
|
|
1197 The first step of building involves running the @file{configure} program
|
|
|
1198 and passing it various parameters to specify any optional features you
|
|
|
1199 want and compiler arguments and such, as described in the @file{INSTALL}
|
|
|
1200 file. This determines what the build environment is, chooses the
|
|
|
1201 appropriate @file{s/} and @file{m/} file, and runs a series of tests to
|
|
|
1202 determine many details about your environment, such as which library
|
|
|
1203 functions are available and exactly how they work. The reason for
|
|
|
1204 running these tests is that it allows XEmacs to be compiled on a much
|
|
|
1205 wider variety of platforms than those that the XEmacs developers happen
|
|
|
1206 to be familiar with, including various sorts of hybrid platforms. This
|
|
|
1207 is especially important now that many operating systems give you a great
|
|
|
1208 deal of control over exactly what features you want installed, and allow
|
|
|
1209 for easy upgrading of parts of a system without upgrading the rest. It
|
|
|
1210 would be impossible to pre-determine and pre-specify the information for
|
|
|
1211 all possible configurations.
|
|
|
1212
|
|
|
1213 In fact, the @file{s/} and @file{m/} files are basically @emph{evil},
|
|
|
1214 since they contain unmaintainable platform-specific hard-coded
|
|
|
1215 information. XEmacs has been moving in the direction of having all
|
|
|
1216 system-specific information be determined dynamically by
|
|
|
1217 @file{configure}. Perhaps someday we can @code{rm -rf src/s src/m}.
|
|
|
1218
|
|
|
1219 When configure is done running, it generates @file{Makefile}s and
|
|
|
1220 @file{GNUmakefile}s and the file @file{src/config.h} (which describes
|
|
|
1221 the features of your system) from template files. You then run
|
|
|
1222 @file{make}, which compiles the auxiliary code and programs in
|
|
|
1223 @file{lib-src/} and @file{lwlib/} and the main XEmacs executable in
|
|
|
1224 @file{src/}. The result of compiling and linking is an executable
|
|
|
1225 called @file{temacs}, which is @emph{not} the final XEmacs executable.
|
|
|
1226 @file{temacs} by itself is not intended to function as an editor or even
|
|
|
1227 display any windows on the screen, and if you simply run it, it will
|
|
|
1228 exit immediately. The @file{Makefile} runs @file{temacs} with certain
|
|
|
1229 options that cause it to initialize itself, read in a number of basic
|
|
|
1230 Lisp files, and then dump itself out into a new executable called
|
|
|
1231 @file{xemacs}. This new executable has been pre-initialized and
|
|
|
1232 contains pre-digested Lisp code that is necessary for the editor to
|
|
|
1233 function (this includes most basic editing functions,
|
|
|
1234 e.g. @code{kill-line}, that can be defined in terms of other Lisp
|
|
|
1235 primitives; some initialization code that is called when certain
|
|
|
1236 objects, such as frames, are created; and all of the standard
|
|
|
1237 keybindings and code for the actions they result in). This executable,
|
|
|
1238 @file{xemacs}, is the executable that you run to use the XEmacs editor.
|
|
|
1239
|
|
|
1240 Although @file{temacs} is not intended to be run as an editor, it can,
|
|
|
1241 by using the incantation @code{temacs -batch -l loadup.el run-temacs}.
|
|
|
1242 This is useful when the dumping procedure described above is broken, or
|
|
|
1243 when using certain program debugging tools such as Purify. These tools
|
|
|
1244 get mighty confused by the tricks played by the XEmacs build process,
|
|
1333
|
1245 such as allocating memory in one process, and freeing it in the next.
|
|
|
1246
|
|
|
1247 @node Build-Time Dependencies, XEmacs From the Inside, XEmacs From the Perspective of Building, Top
|
|
|
1248 @chapter Build-Time Dependencies
|
|
|
1249 @cindex build-time dependencies
|
|
|
1250 @cindex dependencies, build-time
|
|
|
1251
|
|
|
1252 This is a collection of random notes on build-time dependencies as of
|
|
|
1253 about XEmacs 21.5.11. Of course we use @file{make} to manage most
|
|
|
1254 dependencies, especially for the C code. The main thing here is for the
|
|
|
1255 Release Engineer to run the @file{src/make-src-depend} script every so
|
|
|
1256 often, at least at every release.
|
|
|
1257
|
|
|
1258 However, since most of XEmacs is written in Lisp, and we compile and
|
|
|
1259 preload the Lisp for efficiency, managing Lisp compilation using
|
|
|
1260 @file{make} would imply running XEmacs hundreds of times. This would
|
|
|
1261 make the build process unbearably long. Thus those processes that
|
|
|
1262 require running the same Lisp programs on many files are managed using
|
|
|
1263 Lisp driver functions rather than @file{make}. The situation is further
|
|
|
1264 complicated by the fact that documentation strings are kept in an
|
|
|
1265 external database, and referenced in the dumped XEmacs by file offset.
|
|
|
1266 Finally, the Lisp files are processed to collect autoloaded function
|
|
|
1267 information and customize dependencies, which are then written into
|
|
|
1268 generated Lisp files.
|
|
|
1269
|
|
|
1270 About this, Ben sez:
|
|
|
1271
|
|
|
1272 @quotation
|
|
|
1273 @enumerate 1
|
|
|
1274 @item
|
|
|
1275 Redumping depends on up-to-date dumped @file{.elc} files and @file{DOC}
|
|
|
1276 but not directly on auto-autoloads.
|
|
|
1277
|
|
|
1278 @item
|
|
|
1279 Rebuilding dumped @file{.elc} files depends on auto-autoloads being
|
|
|
1280 up-to-date.
|
|
|
1281
|
|
|
1282 @item
|
|
|
1283 Building the @file{DOC} file depends on up-to-date dumped @file{.elc}
|
|
|
1284 files but not directly on auto-autoloads.
|
|
|
1285
|
|
|
1286 @item
|
|
|
1287 Recompiling anything depends on @file{bytecomp.elc} and
|
|
|
1288 @file{byte-optimize.elc} being up-to-date.
|
|
|
1289 @end enumerate
|
|
|
1290
|
|
|
1291 Put these together and you'll see it's perfectly acceptable to build
|
|
|
1292 auto-autoloads *after* dumping if no @file{.elc} files are out-of-date.
|
|
|
1293 @end quotation
|
|
|
1294
|
|
|
1295 These Lisp driver programs typically run from temacs, not a dumped
|
|
|
1296 XEmacs. The simplest (but time-consuming) way to achieve a sane
|
|
|
1297 environment for running Lisp is to load @file{loadup.el} or
|
|
|
1298 @file{loadup-el.el}. (The latter is used to avoid loading possibly
|
|
|
1299 out-of-date compiled Lisp files.) If this is not done, you have to
|
|
|
1300 construct the environment yourself. See @file{dumped-lisp.el} to see
|
|
|
1301 how it is done in the dumped XEmacs.
|
|
|
1302
|
|
|
1303 One potential gotcha is that very early customizations are now handled
|
|
|
1304 by adding the definitions to the special variable
|
|
|
1305 @code{custom-declare-variable-list}, defined in @file{subr.el}. If you
|
|
|
1306 use any higher-level functionality that might load @file{custom.el}, but
|
|
|
1307 you do not need @file{subr.el}, you should @samp{defvar}
|
|
|
1308 @code{custom-declare-variable-list} to prevent the @samp{void-variable}
|
|
|
1309 error. (Currently this is only needed for @file{make-docfile.el}.)
|
|
|
1310
|
|
|
1311 @node XEmacs From the Inside, The XEmacs Object System (Abstractly Speaking), Build-Time Dependencies, Top
|
|
428
|
1312 @chapter XEmacs From the Inside
|
|
462
|
1313 @cindex XEmacs from the inside
|
|
|
1314 @cindex inside, XEmacs from the
|
|
428
|
1315
|
|
|
1316 Internally, XEmacs is quite complex, and can be very confusing. To
|
|
|
1317 simplify things, it can be useful to think of XEmacs as containing an
|
|
|
1318 event loop that ``drives'' everything, and a number of other subsystems,
|
|
|
1319 such as a Lisp engine and a redisplay mechanism. Each of these other
|
|
|
1320 subsystems exists simultaneously in XEmacs, and each has a certain
|
|
|
1321 state. The flow of control continually passes in and out of these
|
|
|
1322 different subsystems in the course of normal operation of the editor.
|
|
|
1323
|
|
|
1324 It is important to keep in mind that, most of the time, the editor is
|
|
|
1325 ``driven'' by the event loop. Except during initialization and batch
|
|
|
1326 mode, all subsystems are entered directly or indirectly through the
|
|
|
1327 event loop, and ultimately, control exits out of all subsystems back up
|
|
|
1328 to the event loop. This cycle of entering a subsystem, exiting back out
|
|
|
1329 to the event loop, and starting another iteration of the event loop
|
|
|
1330 occurs once each keystroke, mouse motion, etc.
|
|
|
1331
|
|
|
1332 If you're trying to understand a particular subsystem (other than the
|
|
|
1333 event loop), think of it as a ``daemon'' process or ``servant'' that is
|
|
|
1334 responsible for one particular aspect of a larger system, and
|
|
|
1335 periodically receives commands or environment changes that cause it to
|
|
|
1336 do something. Ultimately, these commands and environment changes are
|
|
|
1337 always triggered by the event loop. For example:
|
|
|
1338
|
|
|
1339 @itemize @bullet
|
|
|
1340 @item
|
|
|
1341 The window and frame mechanism is responsible for keeping track of what
|
|
|
1342 windows and frames exist, what buffers are in them, etc. It is
|
|
|
1343 periodically given commands (usually from the user) to make a change to
|
|
|
1344 the current window/frame state: i.e. create a new frame, delete a
|
|
|
1345 window, etc.
|
|
|
1346
|
|
|
1347 @item
|
|
|
1348 The buffer mechanism is responsible for keeping track of what buffers
|
|
|
1349 exist and what text is in them. It is periodically given commands
|
|
|
1350 (usually from the user) to insert or delete text, create a buffer, etc.
|
|
|
1351 When it receives a text-change command, it notifies the redisplay
|
|
|
1352 mechanism.
|
|
|
1353
|
|
|
1354 @item
|
|
|
1355 The redisplay mechanism is responsible for making sure that windows and
|
|
|
1356 frames are displayed correctly. It is periodically told (by the event
|
|
|
1357 loop) to actually ``do its job'', i.e. snoop around and see what the
|
|
|
1358 current state of the environment (mostly of the currently-existing
|
|
625
|
1359 windows, frames, and buffers) is, and make sure that state matches
|
|
428
|
1360 what's actually displayed. It keeps lots and lots of information around
|
|
|
1361 (such as what is actually being displayed currently, and what the
|
|
|
1362 environment was last time it checked) so that it can minimize the work
|
|
|
1363 it has to do. It is also helped along in that whenever a relevant
|
|
|
1364 change to the environment occurs, the redisplay mechanism is told about
|
|
|
1365 this, so it has a pretty good idea of where it has to look to find
|
|
|
1366 possible changes and doesn't have to look everywhere.
|
|
|
1367
|
|
|
1368 @item
|
|
|
1369 The Lisp engine is responsible for executing the Lisp code in which most
|
|
|
1370 user commands are written. It is entered through a call to @code{eval}
|
|
|
1371 or @code{funcall}, which occurs as a result of dispatching an event from
|
|
|
1372 the event loop. The functions it calls issue commands to the buffer
|
|
|
1373 mechanism, the window/frame subsystem, etc.
|
|
|
1374
|
|
|
1375 @item
|
|
|
1376 The Lisp allocation subsystem is responsible for keeping track of Lisp
|
|
|
1377 objects. It is given commands from the Lisp engine to allocate objects,
|
|
|
1378 garbage collect, etc.
|
|
|
1379 @end itemize
|
|
|
1380
|
|
|
1381 etc.
|
|
|
1382
|
|
|
1383 The important idea here is that there are a number of independent
|
|
|
1384 subsystems each with its own responsibility and persistent state, just
|
|
|
1385 like different employees in a company, and each subsystem is
|
|
|
1386 periodically given commands from other subsystems. Commands can flow
|
|
|
1387 from any one subsystem to any other, but there is usually some sort of
|
|
|
1388 hierarchy, with all commands originating from the event subsystem.
|
|
|
1389
|
|
|
1390 XEmacs is entered in @code{main()}, which is in @file{emacs.c}. When
|
|
|
1391 this is called the first time (in a properly-invoked @file{temacs}), it
|
|
|
1392 does the following:
|
|
|
1393
|
|
|
1394 @enumerate
|
|
|
1395 @item
|
|
|
1396 It does some very basic environment initializations, such as determining
|
|
|
1397 where it and its directories (e.g. @file{lisp/} and @file{etc/}) reside
|
|
|
1398 and setting up signal handlers.
|
|
|
1399 @item
|
|
|
1400 It initializes the entire Lisp interpreter.
|
|
|
1401 @item
|
|
|
1402 It sets the initial values of many built-in variables (including many
|
|
|
1403 variables that are visible to Lisp programs), such as the global keymap
|
|
|
1404 object and the built-in faces (a face is an object that describes the
|
|
|
1405 display characteristics of text). This involves creating Lisp objects
|
|
|
1406 and thus is dependent on step (2).
|
|
|
1407 @item
|
|
|
1408 It performs various other initializations that are relevant to the
|
|
|
1409 particular environment it is running in, such as retrieving environment
|
|
|
1410 variables, determining the current date and the user who is running the
|
|
|
1411 program, examining its standard input, creating any necessary file
|
|
|
1412 descriptors, etc.
|
|
|
1413 @item
|
|
|
1414 At this point, the C initialization is complete. A Lisp program that
|
|
|
1415 was specified on the command line (usually @file{loadup.el}) is called
|
|
|
1416 (temacs is normally invoked as @code{temacs -batch -l loadup.el dump}).
|
|
|
1417 @file{loadup.el} loads all of the other Lisp files that are needed for
|
|
|
1418 the operation of the editor, calls the @code{dump-emacs} function to
|
|
|
1419 write out @file{xemacs}, and then kills the temacs process.
|
|
|
1420 @end enumerate
|
|
|
1421
|
|
|
1422 When @file{xemacs} is then run, it only redoes steps (1) and (4)
|
|
|
1423 above; all variables already contain the values they were set to when
|
|
|
1424 the executable was dumped, and all memory that was allocated with
|
|
|
1425 @code{malloc()} is still around. (XEmacs knows whether it is being run
|
|
|
1426 as @file{xemacs} or @file{temacs} because it sets the global variable
|
|
|
1427 @code{initialized} to 1 after step (4) above.) At this point,
|
|
|
1428 @file{xemacs} calls a Lisp function to do any further initialization,
|
|
|
1429 which includes parsing the command-line (the C code can only do limited
|
|
|
1430 command-line parsing, which includes looking for the @samp{-batch} and
|
|
|
1431 @samp{-l} flags and a few other flags that it needs to know about before
|
|
|
1432 initialization is complete), creating the first frame (or @dfn{window}
|
|
|
1433 in standard window-system parlance), running the user's init file
|
|
|
1434 (usually the file @file{.emacs} in the user's home directory), etc. The
|
|
|
1435 function to do this is usually called @code{normal-top-level};
|
|
|
1436 @file{loadup.el} tells the C code about this function by setting its
|
|
|
1437 name as the value of the Lisp variable @code{top-level}.
|
|
|
1438
|
|
|
1439 When the Lisp initialization code is done, the C code enters the event
|
|
|
1440 loop, and stays there for the duration of the XEmacs process. The code
|
|
442
|
1441 for the event loop is contained in @file{cmdloop.c}, and is called
|
|
428
|
1442 @code{Fcommand_loop_1()}. Note that this event loop could very well be
|
|
|
1443 written in Lisp, and in fact a Lisp version exists; but apparently,
|
|
|
1444 doing this makes XEmacs run noticeably slower.
|
|
|
1445
|
|
|
1446 Notice how much of the initialization is done in Lisp, not in C.
|
|
|
1447 In general, XEmacs tries to move as much code as is possible
|
|
|
1448 into Lisp. Code that remains in C is code that implements the
|
|
|
1449 Lisp interpreter itself, or code that needs to be very fast, or
|
|
|
1450 code that needs to do system calls or other such stuff that
|
|
|
1451 needs to be done in C, or code that needs to have access to
|
|
|
1452 ``forbidden'' structures. (One conscious aspect of the design of
|
|
|
1453 Lisp under XEmacs is a clean separation between the external
|
|
|
1454 interface to a Lisp object's functionality and its internal
|
|
|
1455 implementation. Part of this design is that Lisp programs
|
|
|
1456 are forbidden from accessing the contents of the object other
|
|
|
1457 than through using a standard API. In this respect, XEmacs Lisp
|
|
|
1458 is similar to modern Lisp dialects but differs from GNU Emacs,
|
|
|
1459 which tends to expose the implementation and allow Lisp
|
|
|
1460 programs to look at it directly. The major advantage of
|
|
|
1461 hiding the implementation is that it allows the implementation
|
|
|
1462 to be redesigned without affecting any Lisp programs, including
|
|
|
1463 those that might want to be ``clever'' by looking directly at
|
|
|
1464 the object's contents and possibly manipulating them.)
|
|
|
1465
|
|
|
1466 Moving code into Lisp makes the code easier to debug and maintain and
|
|
|
1467 makes it much easier for people who are not XEmacs developers to
|
|
|
1468 customize XEmacs, because they can make a change with much less chance
|
|
|
1469 of obscure and unwanted interactions occurring than if they were to
|
|
|
1470 change the C code.
|
|
|
1471
|
|
|
1472 @node The XEmacs Object System (Abstractly Speaking), How Lisp Objects Are Represented in C, XEmacs From the Inside, Top
|
|
|
1473 @chapter The XEmacs Object System (Abstractly Speaking)
|
|
462
|
1474 @cindex XEmacs object system (abstractly speaking), the
|
|
|
1475 @cindex object system (abstractly speaking), the XEmacs
|
|
428
|
1476
|
|
|
1477 At the heart of the Lisp interpreter is its management of objects.
|
|
|
1478 XEmacs Lisp contains many built-in objects, some of which are
|
|
|
1479 simple and others of which can be very complex; and some of which
|
|
|
1480 are very common, and others of which are rarely used or are only
|
|
|
1481 used internally. (Since the Lisp allocation system, with its
|
|
|
1482 automatic reclamation of unused storage, is so much more convenient
|
|
|
1483 than @code{malloc()} and @code{free()}, the C code makes extensive use of it
|
|
|
1484 in its internal operations.)
|
|
|
1485
|
|
|
1486 The basic Lisp objects are
|
|
|
1487
|
|
|
1488 @table @code
|
|
|
1489 @item integer
|
|
|
1490 28 or 31 bits of precision, or 60 or 63 bits on 64-bit machines; the
|
|
|
1491 reason for this is described below when the internal Lisp object
|
|
|
1492 representation is described.
|
|
|
1493 @item float
|
|
|
1494 Same precision as a double in C.
|
|
|
1495 @item cons
|
|
|
1496 A simple container for two Lisp objects, used to implement lists and
|
|
|
1497 most other data structures in Lisp.
|
|
|
1498 @item char
|
|
|
1499 An object representing a single character of text; chars behave like
|
|
|
1500 integers in many ways but are logically considered text rather than
|
|
|
1501 numbers and have a different read syntax. (the read syntax for a char
|
|
440
|
1502 contains the char itself or some textual encoding of it---for example,
|
|
428
|
1503 a Japanese Kanji character might be encoded as @samp{^[$(B#&^[(B} using the
|
|
440
|
1504 ISO-2022 encoding standard---rather than the numerical representation
|
|
428
|
1505 of the char; this way, if the mapping between chars and integers
|
|
|
1506 changes, which is quite possible for Kanji characters and other extended
|
|
|
1507 characters, the same character will still be created. Note that some
|
|
|
1508 primitives confuse chars and integers. The worst culprit is @code{eq},
|
|
|
1509 which makes a special exception and considers a char to be @code{eq} to
|
|
|
1510 its integer equivalent, even though in no other case are objects of two
|
|
|
1511 different types @code{eq}. The reason for this monstrosity is
|
|
|
1512 compatibility with existing code; the separation of char from integer
|
|
|
1513 came fairly recently.)
|
|
|
1514 @item symbol
|
|
|
1515 An object that contains Lisp objects and is referred to by name;
|
|
|
1516 symbols are used to implement variables and named functions
|
|
|
1517 and to provide the equivalent of preprocessor constants in C.
|
|
|
1518 @item vector
|
|
|
1519 A one-dimensional array of Lisp objects providing constant-time access
|
|
|
1520 to any of the objects; access to an arbitrary object in a vector is
|
|
|
1521 faster than for lists, but the operations that can be done on a vector
|
|
|
1522 are more limited.
|
|
|
1523 @item string
|
|
|
1524 Self-explanatory; behaves much like a vector of chars
|
|
|
1525 but has a different read syntax and is stored and manipulated
|
|
|
1526 more compactly.
|
|
|
1527 @item bit-vector
|
|
|
1528 A vector of bits; similar to a string in spirit.
|
|
|
1529 @item compiled-function
|
|
|
1530 An object containing compiled Lisp code, known as @dfn{byte code}.
|
|
|
1531 @item subr
|
|
|
1532 A Lisp primitive, i.e. a Lisp-callable function implemented in C.
|
|
|
1533 @end table
|
|
|
1534
|
|
|
1535 @cindex closure
|
|
|
1536 Note that there is no basic ``function'' type, as in more powerful
|
|
|
1537 versions of Lisp (where it's called a @dfn{closure}). XEmacs Lisp does
|
|
|
1538 not provide the closure semantics implemented by Common Lisp and Scheme.
|
|
|
1539 The guts of a function in XEmacs Lisp are represented in one of four
|
|
|
1540 ways: a symbol specifying another function (when one function is an
|
|
|
1541 alias for another), a list (whose first element must be the symbol
|
|
|
1542 @code{lambda}) containing the function's source code, a
|
|
|
1543 compiled-function object, or a subr object. (In other words, given a
|
|
|
1544 symbol specifying the name of a function, calling @code{symbol-function}
|
|
|
1545 to retrieve the contents of the symbol's function cell will return one
|
|
|
1546 of these types of objects.)
|
|
|
1547
|
|
|
1548 XEmacs Lisp also contains numerous specialized objects used to implement
|
|
|
1549 the editor:
|
|
|
1550
|
|
|
1551 @table @code
|
|
|
1552 @item buffer
|
|
|
1553 Stores text like a string, but is optimized for insertion and deletion
|
|
|
1554 and has certain other properties that can be set.
|
|
|
1555 @item frame
|
|
|
1556 An object with various properties whose displayable representation is a
|
|
|
1557 @dfn{window} in window-system parlance.
|
|
|
1558 @item window
|
|
|
1559 A section of a frame that displays the contents of a buffer;
|
|
|
1560 often called a @dfn{pane} in window-system parlance.
|
|
|
1561 @item window-configuration
|
|
|
1562 An object that represents a saved configuration of windows in a frame.
|
|
|
1563 @item device
|
|
|
1564 An object representing a screen on which frames can be displayed;
|
|
|
1565 equivalent to a @dfn{display} in the X Window System and a @dfn{TTY} in
|
|
|
1566 character mode.
|
|
|
1567 @item face
|
|
|
1568 An object specifying the appearance of text or graphics; it has
|
|
|
1569 properties such as font, foreground color, and background color.
|
|
|
1570 @item marker
|
|
|
1571 An object that refers to a particular position in a buffer and moves
|
|
|
1572 around as text is inserted and deleted to stay in the same relative
|
|
|
1573 position to the text around it.
|
|
|
1574 @item extent
|
|
|
1575 Similar to a marker but covers a range of text in a buffer; can also
|
|
|
1576 specify properties of the text, such as a face in which the text is to
|
|
|
1577 be displayed, whether the text is invisible or unmodifiable, etc.
|
|
|
1578 @item event
|
|
|
1579 Generated by calling @code{next-event} and contains information
|
|
|
1580 describing a particular event happening in the system, such as the user
|
|
|
1581 pressing a key or a process terminating.
|
|
|
1582 @item keymap
|
|
|
1583 An object that maps from events (described using lists, vectors, and
|
|
|
1584 symbols rather than with an event object because the mapping is for
|
|
|
1585 classes of events, rather than individual events) to functions to
|
|
|
1586 execute or other events to recursively look up; the functions are
|
|
|
1587 described by name, using a symbol, or using lists to specify the
|
|
|
1588 function's code.
|
|
|
1589 @item glyph
|
|
|
1590 An object that describes the appearance of an image (e.g. pixmap) on
|
|
|
1591 the screen; glyphs can be attached to the beginning or end of extents
|
|
|
1592 and in some future version of XEmacs will be able to be inserted
|
|
|
1593 directly into a buffer.
|
|
|
1594 @item process
|
|
|
1595 An object that describes a connection to an externally-running process.
|
|
|
1596 @end table
|
|
|
1597
|
|
|
1598 There are some other, less-commonly-encountered general objects:
|
|
|
1599
|
|
|
1600 @table @code
|
|
|
1601 @item hash-table
|
|
|
1602 An object that maps from an arbitrary Lisp object to another arbitrary
|
|
|
1603 Lisp object, using hashing for fast lookup.
|
|
|
1604 @item obarray
|
|
|
1605 A limited form of hash-table that maps from strings to symbols; obarrays
|
|
|
1606 are used to look up a symbol given its name and are not actually their
|
|
|
1607 own object type but are kludgily represented using vectors with hidden
|
|
|
1608 fields (this representation derives from GNU Emacs).
|
|
|
1609 @item specifier
|
|
|
1610 A complex object used to specify the value of a display property; a
|
|
|
1611 default value is given and different values can be specified for
|
|
|
1612 particular frames, buffers, windows, devices, or classes of device.
|
|
|
1613 @item char-table
|
|
|
1614 An object that maps from chars or classes of chars to arbitrary Lisp
|
|
|
1615 objects; internally char tables use a complex nested-vector
|
|
|
1616 representation that is optimized to the way characters are represented
|
|
|
1617 as integers.
|
|
|
1618 @item range-table
|
|
|
1619 An object that maps from ranges of integers to arbitrary Lisp objects.
|
|
|
1620 @end table
|
|
|
1621
|
|
|
1622 And some strange special-purpose objects:
|
|
|
1623
|
|
|
1624 @table @code
|
|
|
1625 @item charset
|
|
|
1626 @itemx coding-system
|
|
|
1627 Objects used when MULE, or multi-lingual/Asian-language, support is
|
|
|
1628 enabled.
|
|
|
1629 @item color-instance
|
|
|
1630 @itemx font-instance
|
|
|
1631 @itemx image-instance
|
|
|
1632 An object that encapsulates a window-system resource; instances are
|
|
|
1633 mostly used internally but are exposed on the Lisp level for cleanness
|
|
|
1634 of the specifier model and because it's occasionally useful for Lisp
|
|
|
1635 program to create or query the properties of instances.
|
|
|
1636 @item subwindow
|
|
|
1637 An object that encapsulate a @dfn{subwindow} resource, i.e. a
|
|
|
1638 window-system child window that is drawn into by an external process;
|
|
|
1639 this object should be integrated into the glyph system but isn't yet,
|
|
|
1640 and may change form when this is done.
|
|
|
1641 @item tooltalk-message
|
|
|
1642 @itemx tooltalk-pattern
|
|
|
1643 Objects that represent resources used in the ToolTalk interprocess
|
|
|
1644 communication protocol.
|
|
|
1645 @item toolbar-button
|
|
|
1646 An object used in conjunction with the toolbar.
|
|
|
1647 @end table
|
|
|
1648
|
|
|
1649 And objects that are only used internally:
|
|
|
1650
|
|
|
1651 @table @code
|
|
|
1652 @item opaque
|
|
|
1653 A generic object for encapsulating arbitrary memory; this allows you the
|
|
|
1654 generality of @code{malloc()} and the convenience of the Lisp object
|
|
|
1655 system.
|
|
|
1656 @item lstream
|
|
|
1657 A buffering I/O stream, used to provide a unified interface to anything
|
|
|
1658 that can accept output or provide input, such as a file descriptor, a
|
|
|
1659 stdio stream, a chunk of memory, a Lisp buffer, a Lisp string, etc.;
|
|
|
1660 it's a Lisp object to make its memory management more convenient.
|
|
|
1661 @item char-table-entry
|
|
|
1662 Subsidiary objects in the internal char-table representation.
|
|
|
1663 @item extent-auxiliary
|
|
|
1664 @itemx menubar-data
|
|
|
1665 @itemx toolbar-data
|
|
|
1666 Various special-purpose objects that are basically just used to
|
|
|
1667 encapsulate memory for particular subsystems, similar to the more
|
|
|
1668 general ``opaque'' object.
|
|
|
1669 @item symbol-value-forward
|
|
|
1670 @itemx symbol-value-buffer-local
|
|
|
1671 @itemx symbol-value-varalias
|
|
|
1672 @itemx symbol-value-lisp-magic
|
|
|
1673 Special internal-only objects that are placed in the value cell of a
|
|
|
1674 symbol to indicate that there is something special with this variable --
|
|
|
1675 e.g. it has no value, it mirrors another variable, or it mirrors some C
|
|
|
1676 variable; there is really only one kind of object, called a
|
|
|
1677 @dfn{symbol-value-magic}, but it is sort-of halfway kludged into
|
|
|
1678 semi-different object types.
|
|
|
1679 @end table
|
|
|
1680
|
|
|
1681 @cindex permanent objects
|
|
|
1682 @cindex temporary objects
|
|
|
1683 Some types of objects are @dfn{permanent}, meaning that once created,
|
|
|
1684 they do not disappear until explicitly destroyed, using a function such
|
|
|
1685 as @code{delete-buffer}, @code{delete-window}, @code{delete-frame}, etc.
|
|
|
1686 Others will disappear once they are not longer used, through the garbage
|
|
|
1687 collection mechanism. Buffers, frames, windows, devices, and processes
|
|
|
1688 are among the objects that are permanent. Note that some objects can go
|
|
|
1689 both ways: Faces can be created either way; extents are normally
|
|
|
1690 permanent, but detached extents (extents not referring to any text, as
|
|
|
1691 happens to some extents when the text they are referring to is deleted)
|
|
|
1692 are temporary. Note that some permanent objects, such as faces and
|
|
|
1693 coding systems, cannot be deleted. Note also that windows are unique in
|
|
|
1694 that they can be @emph{undeleted} after having previously been
|
|
|
1695 deleted. (This happens as a result of restoring a window configuration.)
|
|
|
1696
|
|
|
1697 @cindex read syntax
|
|
|
1698 Note that many types of objects have a @dfn{read syntax}, i.e. a way of
|
|
|
1699 specifying an object of that type in Lisp code. When you load a Lisp
|
|
|
1700 file, or type in code to be evaluated, what really happens is that the
|
|
|
1701 function @code{read} is called, which reads some text and creates an object
|
|
|
1702 based on the syntax of that text; then @code{eval} is called, which
|
|
|
1703 possibly does something special; then this loop repeats until there's
|
|
|
1704 no more text to read. (@code{eval} only actually does something special
|
|
|
1705 with symbols, which causes the symbol's value to be returned,
|
|
|
1706 similar to referencing a variable; and with conses [i.e. lists],
|
|
|
1707 which cause a function invocation. All other values are returned
|
|
|
1708 unchanged.)
|
|
|
1709
|
|
|
1710 The read syntax
|
|
|
1711
|
|
|
1712 @example
|
|
|
1713 17297
|
|
|
1714 @end example
|
|
|
1715
|
|
|
1716 converts to an integer whose value is 17297.
|
|
|
1717
|
|
|
1718 @example
|
|
|
1719 1.983e-4
|
|
|
1720 @end example
|
|
|
1721
|
|
|
1722 converts to a float whose value is 1.983e-4, or .0001983.
|
|
|
1723
|
|
|
1724 @example
|
|
|
1725 ?b
|
|
|
1726 @end example
|
|
|
1727
|
|
|
1728 converts to a char that represents the lowercase letter b.
|
|
|
1729
|
|
|
1730 @example
|
|
|
1731 ?^[$(B#&^[(B
|
|
|
1732 @end example
|
|
|
1733
|
|
|
1734 (where @samp{^[} actually is an @samp{ESC} character) converts to a
|
|
|
1735 particular Kanji character when using an ISO2022-based coding system for
|
|
|
1736 input. (To decode this goo: @samp{ESC} begins an escape sequence;
|
|
|
1737 @samp{ESC $ (} is a class of escape sequences meaning ``switch to a
|
|
|
1738 94x94 character set''; @samp{ESC $ ( B} means ``switch to Japanese
|
|
|
1739 Kanji''; @samp{#} and @samp{&} collectively index into a 94-by-94 array
|
|
|
1740 of characters [subtract 33 from the ASCII value of each character to get
|
|
|
1741 the corresponding index]; @samp{ESC (} is a class of escape sequences
|
|
|
1742 meaning ``switch to a 94 character set''; @samp{ESC (B} means ``switch
|
|
|
1743 to US ASCII''. It is a coincidence that the letter @samp{B} is used to
|
|
|
1744 denote both Japanese Kanji and US ASCII. If the first @samp{B} were
|
|
|
1745 replaced with an @samp{A}, you'd be requesting a Chinese Hanzi character
|
|
|
1746 from the GB2312 character set.)
|
|
|
1747
|
|
|
1748 @example
|
|
|
1749 "foobar"
|
|
|
1750 @end example
|
|
|
1751
|
|
|
1752 converts to a string.
|
|
|
1753
|
|
|
1754 @example
|
|
|
1755 foobar
|
|
|
1756 @end example
|
|
|
1757
|
|
|
1758 converts to a symbol whose name is @code{"foobar"}. This is done by
|
|
|
1759 looking up the string equivalent in the global variable
|
|
|
1760 @code{obarray}, whose contents should be an obarray. If no symbol
|
|
|
1761 is found, a new symbol with the name @code{"foobar"} is automatically
|
|
|
1762 created and added to @code{obarray}; this process is called
|
|
|
1763 @dfn{interning} the symbol.
|
|
|
1764 @cindex interning
|
|
|
1765
|
|
|
1766 @example
|
|
|
1767 (foo . bar)
|
|
|
1768 @end example
|
|
|
1769
|
|
|
1770 converts to a cons cell containing the symbols @code{foo} and @code{bar}.
|
|
|
1771
|
|
|
1772 @example
|
|
|
1773 (1 a 2.5)
|
|
|
1774 @end example
|
|
|
1775
|
|
|
1776 converts to a three-element list containing the specified objects
|
|
|
1777 (note that a list is actually a set of nested conses; see the
|
|
|
1778 XEmacs Lisp Reference).
|
|
|
1779
|
|
|
1780 @example
|
|
|
1781 [1 a 2.5]
|
|
|
1782 @end example
|
|
|
1783
|
|
|
1784 converts to a three-element vector containing the specified objects.
|
|
|
1785
|
|
|
1786 @example
|
|
|
1787 #[... ... ... ...]
|
|
|
1788 @end example
|
|
|
1789
|
|
|
1790 converts to a compiled-function object (the actual contents are not
|
|
|
1791 shown since they are not relevant here; look at a file that ends with
|
|
|
1792 @file{.elc} for examples).
|
|
|
1793
|
|
|
1794 @example
|
|
|
1795 #*01110110
|
|
|
1796 @end example
|
|
|
1797
|
|
|
1798 converts to a bit-vector.
|
|
|
1799
|
|
|
1800 @example
|
|
|
1801 #s(hash-table ... ...)
|
|
|
1802 @end example
|
|
|
1803
|
|
|
1804 converts to a hash table (the actual contents are not shown).
|
|
|
1805
|
|
|
1806 @example
|
|
|
1807 #s(range-table ... ...)
|
|
|
1808 @end example
|
|
|
1809
|
|
|
1810 converts to a range table (the actual contents are not shown).
|
|
|
1811
|
|
|
1812 @example
|
|
|
1813 #s(char-table ... ...)
|
|
|
1814 @end example
|
|
|
1815
|
|
|
1816 converts to a char table (the actual contents are not shown).
|
|
|
1817
|
|
|
1818 Note that the @code{#s()} syntax is the general syntax for structures,
|
|
|
1819 which are not really implemented in XEmacs Lisp but should be.
|
|
|
1820
|
|
|
1821 When an object is printed out (using @code{print} or a related
|
|
|
1822 function), the read syntax is used, so that the same object can be read
|
|
|
1823 in again.
|
|
|
1824
|
|
|
1825 The other objects do not have read syntaxes, usually because it does not
|
|
|
1826 really make sense to create them in this fashion (i.e. processes, where
|
|
|
1827 it doesn't make sense to have a subprocess created as a side effect of
|
|
|
1828 reading some Lisp code), or because they can't be created at all
|
|
|
1829 (e.g. subrs). Permanent objects, as a rule, do not have a read syntax;
|
|
|
1830 nor do most complex objects, which contain too much state to be easily
|
|
|
1831 initialized through a read syntax.
|
|
|
1832
|
|
868
|
1833 @node How Lisp Objects Are Represented in C, Major Textual Changes, The XEmacs Object System (Abstractly Speaking), Top
|
|
428
|
1834 @chapter How Lisp Objects Are Represented in C
|
|
462
|
1835 @cindex Lisp objects are represented in C, how
|
|
|
1836 @cindex objects are represented in C, how Lisp
|
|
|
1837 @cindex represented in C, how Lisp objects are
|
|
428
|
1838
|
|
|
1839 Lisp objects are represented in C using a 32-bit or 64-bit machine word
|
|
|
1840 (depending on the processor; i.e. DEC Alphas use 64-bit Lisp objects and
|
|
|
1841 most other processors use 32-bit Lisp objects). The representation
|
|
|
1842 stuffs a pointer together with a tag, as follows:
|
|
|
1843
|
|
|
1844 @example
|
|
|
1845 [ 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 ]
|
|
|
1846 [ 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 ]
|
|
|
1847
|
|
442
|
1848 <---------------------------------------------------------> <->
|
|
|
1849 a pointer to a structure, or an integer tag
|
|
|
1850 @end example
|
|
|
1851
|
|
|
1852 A tag of 00 is used for all pointer object types, a tag of 10 is used
|
|
|
1853 for characters, and the other two tags 01 and 11 are joined together to
|
|
|
1854 form the integer object type. This representation gives us 31 bit
|
|
|
1855 integers and 30 bit characters, while pointers are represented directly
|
|
|
1856 without any bit masking or shifting. This representation, though,
|
|
|
1857 assumes that pointers to structs are always aligned to multiples of 4,
|
|
|
1858 so the lower 2 bits are always zero.
|
|
428
|
1859
|
|
|
1860 Lisp objects use the typedef @code{Lisp_Object}, but the actual C type
|
|
|
1861 used for the Lisp object can vary. It can be either a simple type
|
|
|
1862 (@code{long} on the DEC Alpha, @code{int} on other machines) or a
|
|
|
1863 structure whose fields are bit fields that line up properly (actually, a
|
|
|
1864 union of structures is used). Generally the simple integral type is
|
|
|
1865 preferable because it ensures that the compiler will actually use a
|
|
|
1866 machine word to represent the object (some compilers will use more
|
|
|
1867 general and less efficient code for unions and structs even if they can
|
|
|
1868 fit in a machine word). The union type, however, has the advantage of
|
|
442
|
1869 stricter type checking. If you accidentally pass an integer where a Lisp
|
|
|
1870 object is desired, you get a compile error. The choice of which type
|
|
|
1871 to use is determined by the preprocessor constant @code{USE_UNION_TYPE}
|
|
|
1872 which is defined via the @code{--use-union-type} option to
|
|
|
1873 @code{configure}.
|
|
|
1874
|
|
|
1875 Various macros are used to convert between Lisp_Objects and the
|
|
|
1876 corresponding C type. Macros of the form @code{XINT()}, @code{XCHAR()},
|
|
|
1877 @code{XSTRING()}, @code{XSYMBOL()}, do any required bit shifting and/or
|
|
|
1878 masking and cast it to the appropriate type. @code{XINT()} needs to be
|
|
|
1879 a bit tricky so that negative numbers are properly sign-extended. Since
|
|
|
1880 integers are stored left-shifted, if the right-shift operator does an
|
|
|
1881 arithmetic shift (i.e. it leaves the most-significant bit as-is rather
|
|
|
1882 than shifting in a zero, so that it mimics a divide-by-two even for
|
|
|
1883 negative numbers) the shift to remove the tag bit is enough. This is
|
|
|
1884 the case on all the systems we support.
|
|
|
1885
|
|
|
1886 Note that when @code{ERROR_CHECK_TYPECHECK} is defined, the converter
|
|
440
|
1887 macros become more complicated---they check the tag bits and/or the
|
|
428
|
1888 type field in the first four bytes of a record type to ensure that the
|
|
|
1889 object is really of the correct type. This is great for catching places
|
|
440
|
1890 where an incorrect type is being dereferenced---this typically results
|
|
428
|
1891 in a pointer being dereferenced as the wrong type of structure, with
|
|
|
1892 unpredictable (and sometimes not easily traceable) results.
|
|
|
1893
|
|
|
1894 There are similar @code{XSET@var{TYPE}()} macros that construct a Lisp
|
|
|
1895 object. These macros are of the form @code{XSET@var{TYPE}
|
|
442
|
1896 (@var{lvalue}, @var{result})}, i.e. they have to be a statement rather
|
|
|
1897 than just used in an expression. The reason for this is that standard C
|
|
|
1898 doesn't let you ``construct'' a structure (but GCC does). Granted, this
|
|
|
1899 sometimes isn't too convenient; for the case of integers, at least, you
|
|
|
1900 can use the function @code{make_int()}, which constructs and
|
|
|
1901 @emph{returns} an integer Lisp object. Note that the
|
|
|
1902 @code{XSET@var{TYPE}()} macros are also affected by
|
|
|
1903 @code{ERROR_CHECK_TYPECHECK} and make sure that the structure is of the
|
|
|
1904 right type in the case of record types, where the type is contained in
|
|
|
1905 the structure.
|
|
428
|
1906
|
|
|
1907 The C programmer is responsible for @strong{guaranteeing} that a
|
|
442
|
1908 Lisp_Object is the correct type before using the @code{X@var{TYPE}}
|
|
428
|
1909 macros. This is especially important in the case of lists. Use
|
|
|
1910 @code{XCAR} and @code{XCDR} if a Lisp_Object is certainly a cons cell,
|
|
|
1911 else use @code{Fcar()} and @code{Fcdr()}. Trust other C code, but not
|
|
|
1912 Lisp code. On the other hand, if XEmacs has an internal logic error,
|
|
442
|
1913 it's better to crash immediately, so sprinkle @code{assert()}s and
|
|
|
1914 ``unreachable'' @code{abort()}s liberally about the source code. Where
|
|
|
1915 performance is an issue, use @code{type_checking_assert},
|
|
|
1916 @code{bufpos_checking_assert}, and @code{gc_checking_assert}, which do
|
|
|
1917 nothing unless the corresponding configure error checking flag was
|
|
|
1918 specified.
|
|
428
|
1919
|
|
868
|
1920 @node Major Textual Changes, Rules When Writing New C Code, How Lisp Objects Are Represented in C, Top
|
|
|
1921 @chapter Major Textual Changes
|
|
|
1922 @cindex textual changes, major
|
|
|
1923 @cindex major textual changes
|
|
|
1924
|
|
|
1925 Sometimes major textual changes are made to the source. This means that
|
|
|
1926 a search-and-replace is done to change type names and such. Some people
|
|
|
1927 disagree with such changes, and certainly if done without good reason
|
|
|
1928 will just lead to headaches. But it's important to keep the code clean
|
|
|
1929 and understable, and consistent naming goes a long way towards this.
|
|
|
1930
|
|
|
1931 An example of the right way to do this was the so-called "great integral
|
|
|
1932 type renaming".
|
|
|
1933
|
|
|
1934 @menu
|
|
|
1935 * Great Integral Type Renaming::
|
|
|
1936 * Text/Char Type Renaming::
|
|
|
1937 @end menu
|
|
|
1938
|
|
|
1939 @node Great Integral Type Renaming
|
|
|
1940 @section Great Integral Type Renaming
|
|
|
1941 @cindex Great Integral Type Renaming
|
|
|
1942 @cindex integral type renaming, great
|
|
|
1943 @cindex type renaming, integral
|
|
|
1944 @cindex renaming, integral types
|
|
|
1945
|
|
|
1946 The purpose of this is to rationalize the names used for various
|
|
|
1947 integral types, so that they match their intended uses and follow
|
|
|
1948 consist conventions, and eliminate types that were not semantically
|
|
|
1949 different from each other.
|
|
|
1950
|
|
|
1951 The conventions are:
|
|
|
1952
|
|
|
1953 @itemize @bullet
|
|
|
1954 @item
|
|
|
1955 All integral types that measure quantities of anything are signed. Some
|
|
|
1956 people disagree vociferously with this, but their arguments are mostly
|
|
|
1957 theoretical, and are vastly outweighed by the practical headaches of
|
|
|
1958 mixing signed and unsigned values, and more importantly by the far
|
|
|
1959 increased likelihood of inadvertent bugs: Because of the broken "viral"
|
|
|
1960 nature of unsigned quantities in C (operations involving mixed
|
|
|
1961 signed/unsigned are done unsigned, when exactly the opposite is nearly
|
|
|
1962 always wanted), even a single error in declaring a quantity unsigned
|
|
|
1963 that should be signed, or even the even more subtle error of comparing
|
|
|
1964 signed and unsigned values and forgetting the necessary cast, can be
|
|
|
1965 catastrophic, as comparisons will yield wrong results. -Wsign-compare
|
|
|
1966 is turned on specifically to catch this, but this tends to result in a
|
|
|
1967 great number of warnings when mixing signed and unsigned, and the casts
|
|
|
1968 are annoying. More has been written on this elsewhere.
|
|
|
1969
|
|
|
1970 @item
|
|
|
1971 All such quantity types just mentioned boil down to EMACS_INT, which is
|
|
|
1972 32 bits on 32-bit machines and 64 bits on 64-bit machines. This is
|
|
|
1973 guaranteed to be the same size as Lisp objects of type `int', and (as
|
|
|
1974 far as I can tell) of size_t (unsigned!) and ssize_t. The only type
|
|
|
1975 below that is not an EMACS_INT is Hashcode, which is an unsigned value
|
|
|
1976 of the same size as EMACS_INT.
|
|
|
1977
|
|
|
1978 @item
|
|
|
1979 Type names should be relatively short (no more than 10 characters or
|
|
|
1980 so), with the first letter capitalized and no underscores if they can at
|
|
|
1981 all be avoided.
|
|
|
1982
|
|
|
1983 @item
|
|
|
1984 "count" == a zero-based measurement of some quantity. Includes sizes,
|
|
|
1985 offsets, and indexes.
|
|
|
1986
|
|
|
1987 @item
|
|
|
1988 "bpos" == a one-based measurement of a position in a buffer. "Charbpos"
|
|
|
1989 and "Bytebpos" count text in the buffer, rather than bytes in memory;
|
|
|
1990 thus Bytebpos does not directly correspond to the memory representation.
|
|
|
1991 Use "Membpos" for this.
|
|
|
1992
|
|
|
1993 @item
|
|
|
1994 "Char" refers to internal-format characters, not to the C type "char",
|
|
|
1995 which is really a byte.
|
|
|
1996 @end itemize
|
|
|
1997
|
|
|
1998 For the actual name changes, see the script below.
|
|
|
1999
|
|
|
2000 I ran the following script to do the conversion. (NOTE: This script is
|
|
|
2001 idempotent. You can safely run it multiple times and it will not screw
|
|
|
2002 up previous results -- in fact, it will do nothing if nothing has
|
|
|
2003 changed. Thus, it can be run repeatedly as necessary to handle patches
|
|
|
2004 coming in from old workspaces, or old branches.) There are two tags,
|
|
|
2005 just before and just after the change: @samp{pre-integral-type-rename}
|
|
|
2006 and @samp{post-integral-type-rename}. When merging code from the main
|
|
|
2007 trunk into a branch, the best thing to do is first merge up to
|
|
|
2008 @samp{pre-integral-type-rename}, then apply the script and associated
|
|
|
2009 changes, then merge from @samp{post-integral-type-change} to the
|
|
|
2010 present. (Alternatively, just do the merging in one operation; but you
|
|
|
2011 may then have a lot of conflicts needing to be resolved by hand.)
|
|
|
2012
|
|
|
2013 Script @samp{fixtypes.sh} follows:
|
|
|
2014
|
|
|
2015 @example
|
|
|
2016 ----------------------------------- cut ------------------------------------
|
|
|
2017 files="*.[ch] s/*.h m/*.h config.h.in ../configure.in Makefile.in.in ../lib-src/*.[ch] ../lwlib/*.[ch]"
|
|
|
2018 gr Memory_Count Bytecount $files
|
|
|
2019 gr Lstream_Data_Count Bytecount $files
|
|
|
2020 gr Element_Count Elemcount $files
|
|
|
2021 gr Hash_Code Hashcode $files
|
|
|
2022 gr extcount bytecount $files
|
|
|
2023 gr bufpos charbpos $files
|
|
|
2024 gr bytind bytebpos $files
|
|
|
2025 gr memind membpos $files
|
|
|
2026 gr bufbyte intbyte $files
|
|
|
2027 gr Extcount Bytecount $files
|
|
|
2028 gr Bufpos Charbpos $files
|
|
|
2029 gr Bytind Bytebpos $files
|
|
|
2030 gr Memind Membpos $files
|
|
|
2031 gr Bufbyte Intbyte $files
|
|
|
2032 gr EXTCOUNT BYTECOUNT $files
|
|
|
2033 gr BUFPOS CHARBPOS $files
|
|
|
2034 gr BYTIND BYTEBPOS $files
|
|
|
2035 gr MEMIND MEMBPOS $files
|
|
|
2036 gr BUFBYTE INTBYTE $files
|
|
|
2037 gr MEMORY_COUNT BYTECOUNT $files
|
|
|
2038 gr LSTREAM_DATA_COUNT BYTECOUNT $files
|
|
|
2039 gr ELEMENT_COUNT ELEMCOUNT $files
|
|
|
2040 gr HASH_CODE HASHCODE $files
|
|
|
2041 ----------------------------------- cut ------------------------------------
|
|
|
2042 @end example
|
|
|
2043
|
|
|
2044 The @samp{gr} script, and the scripts it uses, are documented in
|
|
|
2045 @file{README.global-renaming}, because if placed in this file they would
|
|
|
2046 need to have their @@ characters doubled, meaning you couldn't easily
|
|
|
2047 cut and paste from the source.
|
|
|
2048
|
|
|
2049 In addition to those programs, I needed to fix up a few other
|
|
|
2050 things, particularly relating to the duplicate definitions of
|
|
|
2051 types, now that some types merged with others. Specifically:
|
|
|
2052
|
|
|
2053 @enumerate
|
|
|
2054 @item
|
|
|
2055 in lisp.h, removed duplicate declarations of Bytecount. The changed
|
|
|
2056 code should now look like this: (In each code snippet below, the first
|
|
|
2057 and last lines are the same as the original, as are all lines outside of
|
|
|
2058 those lines. That allows you to locate the section to be replaced, and
|
|
|
2059 replace the stuff in that section, verifying that there isn't anything
|
|
|
2060 new added that would need to be kept.)
|
|
|
2061
|
|
|
2062 @example
|
|
|
2063 --------------------------------- snip -------------------------------------
|
|
|
2064 /* Counts of bytes or chars */
|
|
|
2065 typedef EMACS_INT Bytecount;
|
|
|
2066 typedef EMACS_INT Charcount;
|
|
|
2067
|
|
|
2068 /* Counts of elements */
|
|
|
2069 typedef EMACS_INT Elemcount;
|
|
|
2070
|
|
|
2071 /* Hash codes */
|
|
|
2072 typedef unsigned long Hashcode;
|
|
|
2073
|
|
|
2074 /* ------------------------ dynamic arrays ------------------- */
|
|
|
2075 --------------------------------- snip -------------------------------------
|
|
|
2076 @end example
|
|
|
2077
|
|
|
2078 @item
|
|
|
2079 in lstream.h, removed duplicate declaration of Bytecount. Rewrote the
|
|
|
2080 comment about this type. The changed code should now look like this:
|
|
|
2081
|
|
|
2082 @example
|
|
|
2083 --------------------------------- snip -------------------------------------
|
|
|
2084 #endif
|
|
|
2085
|
|
|
2086 /* The have been some arguments over the what the type should be that
|
|
|
2087 specifies a count of bytes in a data block to be written out or read in,
|
|
|
2088 using Lstream_read(), Lstream_write(), and related functions.
|
|
|
2089 Originally it was long, which worked fine; Martin "corrected" these to
|
|
|
2090 size_t and ssize_t on the grounds that this is theoretically cleaner and
|
|
|
2091 is in keeping with the C standards. Unfortunately, this practice is
|
|
|
2092 horribly error-prone due to design flaws in the way that mixed
|
|
|
2093 signed/unsigned arithmetic happens. In fact, by doing this change,
|
|
|
2094 Martin introduced a subtle but fatal error that caused the operation of
|
|
|
2095 sending large mail messages to the SMTP server under Windows to fail.
|
|
|
2096 By putting all values back to be signed, avoiding any signed/unsigned
|
|
|
2097 mixing, the bug immediately went away. The type then in use was
|
|
|
2098 Lstream_Data_Count, so that it be reverted cleanly if a vote came to
|
|
|
2099 that. Now it is Bytecount.
|
|
|
2100
|
|
|
2101 Some earlier comments about why the type must be signed: This MUST BE
|
|
|
2102 SIGNED, since it also is used in functions that return the number of
|
|
|
2103 bytes actually read to or written from in an operation, and these
|
|
|
2104 functions can return -1 to signal error.
|
|
|
2105
|
|
|
2106 Note that the standard Unix read() and write() functions define the
|
|
|
2107 count going in as a size_t, which is UNSIGNED, and the count going
|
|
|
2108 out as an ssize_t, which is SIGNED. This is a horrible design
|
|
|
2109 flaw. Not only is it highly likely to lead to logic errors when a
|
|
|
2110 -1 gets interpreted as a large positive number, but operations are
|
|
|
2111 bound to fail in all sorts of horrible ways when a number in the
|
|
|
2112 upper-half of the size_t range is passed in -- this number is
|
|
|
2113 unrepresentable as an ssize_t, so code that checks to see how many
|
|
|
2114 bytes are actually written (which is mandatory if you are dealing
|
|
|
2115 with certain types of devices) will get completely screwed up.
|
|
|
2116
|
|
|
2117 --ben
|
|
|
2118 */
|
|
|
2119
|
|
|
2120 typedef enum lstream_buffering
|
|
|
2121 --------------------------------- snip -------------------------------------
|
|
|
2122 @end example
|
|
|
2123
|
|
|
2124 @item
|
|
|
2125 in dumper.c, there are four places, all inside of switch() statements,
|
|
|
2126 where XD_BYTECOUNT appears twice as a case tag. In each case, the two
|
|
|
2127 case blocks contain identical code, and you should *REMOVE THE SECOND*
|
|
|
2128 and leave the first.
|
|
|
2129 @end enumerate
|
|
|
2130
|
|
|
2131 @node Text/Char Type Renaming
|
|
|
2132 @section Text/Char Type Renaming
|
|
|
2133 @cindex Text/Char Type Renaming
|
|
|
2134 @cindex type renaming, text/char
|
|
|
2135 @cindex renaming, text/char types
|
|
|
2136
|
|
|
2137 The purpose of this was
|
|
|
2138
|
|
|
2139 @enumerate
|
|
|
2140 @item
|
|
|
2141 To distinguish between ``charptr'' when it refers to operations on
|
|
|
2142 the pointer itself and when it refers to operations on text
|
|
|
2143 @item
|
|
|
2144 To use consistent naming for everything referring to internal format, i.e.
|
|
|
2145 @end enumerate
|
|
|
2146
|
|
|
2147 @example
|
|
|
2148 Itext == text in internal format
|
|
|
2149 Ibyte == a byte in such text
|
|
|
2150 Ichar == a char as represented in internal character format
|
|
|
2151 @end example
|
|
|
2152
|
|
|
2153 Thus e.g.
|
|
|
2154
|
|
|
2155 @example
|
|
|
2156 set_charptr_emchar -> set_itext_ichar
|
|
|
2157 @end example
|
|
|
2158
|
|
|
2159 This was done using a script like this:
|
|
|
2160
|
|
|
2161 @example
|
|
|
2162 files="*.[ch] s/*.h m/*.h config.h.in ../configure.in Makefile.in.in ../lib-src/*.[ch] ../lwlib/*.[ch]"
|
|
|
2163 gr Intbyte Ibyte $files
|
|
|
2164 gr INTBYTE IBYTE $files
|
|
|
2165 gr intbyte ibyte $files
|
|
|
2166 gr EMCHAR ICHAR $files
|
|
|
2167 gr emchar ichar $files
|
|
|
2168 gr Emchar Ichar $files
|
|
|
2169 gr INC_CHARPTR INC_IBYTEPTR $files
|
|
|
2170 gr DEC_CHARPTR DEC_IBYTEPTR $files
|
|
|
2171 gr VALIDATE_CHARPTR VALIDATE_IBYTEPTR $files
|
|
|
2172 gr valid_charptr valid_ibyteptr $files
|
|
|
2173 gr CHARPTR ITEXT $files
|
|
|
2174 gr charptr itext $files
|
|
|
2175 gr Charptr Itext $files
|
|
|
2176 @end example
|
|
|
2177
|
|
|
2178 See above for the source to @samp{gr}.
|
|
|
2179
|
|
|
2180 As in the integral-types change, there are pre and post tags before and
|
|
|
2181 after the change:
|
|
|
2182
|
|
|
2183 @example
|
|
|
2184 pre-internal-format-textual-renaming
|
|
|
2185 post-internal-format-textual-renaming
|
|
|
2186 @end example
|
|
|
2187
|
|
|
2188 When merging a large branch, follow the same sort of procedure
|
|
|
2189 documented above, using these tags -- essentially sync up to the pre
|
|
|
2190 tag, then apply the script yourself, then sync from the post tag to the
|
|
|
2191 present. You can probably do the same if you don't have a separate
|
|
|
2192 workspace, but do have lots of outstanding changes and you'd rather not
|
|
|
2193 just merge all the textual changes directly. Use something like this:
|
|
|
2194
|
|
|
2195 (WARNING: I'm not a CVS guru; before trying this, or any large operation
|
|
|
2196 that might potentially mess things up, *DEFINITELY* make a backup of
|
|
|
2197 your existing workspace.)
|
|
|
2198
|
|
|
2199 @example
|
|
|
2200 cup -r pre-internal-format-textual-renaming
|
|
|
2201 <apply script>
|
|
|
2202 cup -A -j post-internal-format-textual-renaming -j HEAD
|
|
|
2203 @end example
|
|
|
2204
|
|
|
2205 This might also work:
|
|
|
2206
|
|
|
2207 @example
|
|
|
2208 cup -j pre-internal-format-textual-renaming
|
|
|
2209 <apply script>
|
|
|
2210 cup -j post-internal-format-textual-renaming -j HEAD
|
|
|
2211 @end example
|
|
|
2212
|
|
|
2213 ben
|
|
|
2214
|
|
|
2215 The following is a script to go in the opposite direction:
|
|
|
2216
|
|
|
2217 @example
|
|
|
2218 files="*.[ch] s/*.h m/*.h config.h.in ../configure.in Makefile.in.in ../lib-src/*.[ch] ../lwlib/*.[ch]"
|
|
|
2219
|
|
|
2220 # Evidently Perl considers _ to be a word char ala \b, even though XEmacs
|
|
|
2221 # doesn't. We need to be careful here with ibyte/ichar because of words
|
|
|
2222 # like Richard, eicharlen(), multibyte, HIBYTE, etc.
|
|
|
2223
|
|
|
2224 gr Ibyte Intbyte $files
|
|
|
2225 gr '\bIBYTE' INTBYTE $files
|
|
|
2226 gr '\bibyte' intbyte $files
|
|
|
2227 gr '\bICHAR' EMCHAR $files
|
|
|
2228 gr '\bichar' emchar $files
|
|
|
2229 gr '\bIchar' Emchar $files
|
|
|
2230 gr '\bIBYTEPTR' CHARPTR $files
|
|
|
2231 gr '\bibyteptr' charptr $files
|
|
|
2232 gr '\bITEXT' CHARPTR $files
|
|
|
2233 gr '\bitext' charptr $files
|
|
|
2234 gr '\bItext' CHARPTR $files
|
|
|
2235
|
|
|
2236 gr '_IBYTE' _INTBYTE $files
|
|
|
2237 gr '_ibyte' _intbyte $files
|
|
|
2238 gr '_ICHAR' _EMCHAR $files
|
|
|
2239 gr '_ichar' _emchar $files
|
|
|
2240 gr '_Ichar' _Emchar $files
|
|
|
2241 gr '_IBYTEPTR' _CHARPTR $files
|
|
|
2242 gr '_ibyteptr' _charptr $files
|
|
|
2243 gr '_ITEXT' _CHARPTR $files
|
|
|
2244 gr '_itext' _charptr $files
|
|
|
2245 gr '_Itext' _CHARPTR $files
|
|
|
2246 @end example
|
|
|
2247
|
|
965
|
2248 @node Rules When Writing New C Code, Regression Testing XEmacs, Major Textual Changes, Top
|
|
428
|
2249 @chapter Rules When Writing New C Code
|
|
462
|
2250 @cindex writing new C code, rules when
|
|
|
2251 @cindex C code, rules when writing new
|
|
|
2252 @cindex code, rules when writing new C
|
|
428
|
2253
|
|
|
2254 The XEmacs C Code is extremely complex and intricate, and there are many
|
|
|
2255 rules that are more or less consistently followed throughout the code.
|
|
|
2256 Many of these rules are not obvious, so they are explained here. It is
|
|
|
2257 of the utmost importance that you follow them. If you don't, you may
|
|
|
2258 get something that appears to work, but which will crash in odd
|
|
|
2259 situations, often in code far away from where the actual breakage is.
|
|
|
2260
|
|
|
2261 @menu
|
|
1709
|
2262 * A Reader's Guide to XEmacs Coding Conventions::
|
|
428
|
2263 * General Coding Rules::
|
|
|
2264 * Writing Lisp Primitives::
|
|
462
|
2265 * Writing Good Comments::
|
|
428
|
2266 * Adding Global Lisp Variables::
|
|
462
|
2267 * Proper Use of Unsigned Types::
|
|
428
|
2268 * Coding for Mule::
|
|
|
2269 * Techniques for XEmacs Developers::
|
|
|
2270 @end menu
|
|
|
2271
|
|
1709
|
2272 @node A Reader's Guide to XEmacs Coding Conventions
|
|
|
2273 @section A Reader's Guide to XEmacs Coding Conventions
|
|
|
2274 @cindex coding conventions
|
|
|
2275 @cindex reader's guide
|
|
|
2276 @cindex coding rules, naming
|
|
|
2277
|
|
|
2278 Of course the low-level implementation language of XEmacs is C, but much
|
|
|
2279 of that uses the Lisp engine to do its work. However, because the code
|
|
|
2280 is ``inside'' of the protective containment shell around the ``reactor
|
|
|
2281 core,'' you'll see lots of complex ``plumbing'' needed to do the work
|
|
|
2282 and ``safety mechanisms,'' whose failure results in a meltdown. This
|
|
|
2283 section provides a quick overview (or review) of the various components
|
|
|
2284 of the implementation of Lisp objects.
|
|
|
2285
|
|
|
2286 Two typographic conventions help to identify C objects that implement
|
|
|
2287 Lisp objects. The first is that capitalized identifiers, especially
|
|
|
2288 beginning with the letters @samp{Q}, @samp{V}, @samp{F}, and @samp{S},
|
|
|
2289 for C variables and functions, and C macros with beginning with the
|
|
|
2290 letter @samp{X}, are used to implement Lisp. The second is that where
|
|
|
2291 Lisp uses the hyphen @samp{-} in symbol names, the corresponding C
|
|
|
2292 identifiers use the underscore @samp{_}. Of course, since XEmacs Lisp
|
|
|
2293 contains interfaces to many external libraries, those external names
|
|
|
2294 will follow the coding conventions their authors chose, and may overlap
|
|
|
2295 the ``XEmacs name space.'' However these cases are usually pretty
|
|
|
2296 obvious.
|
|
|
2297
|
|
|
2298 All Lisp objects are handled indirectly. The @code{Lisp_Object}
|
|
|
2299 type is usually a pointer to a structure, except for a very small number
|
|
|
2300 of types with immediate representations (currently characters and
|
|
|
2301 integers). However, these types cannot be directly operated on in C
|
|
|
2302 code, either, so they can also be considered indirect. Types that do
|
|
|
2303 not have an immediate representation always have a C typedef
|
|
|
2304 @code{Lisp_@var{type}} for a corresponding structure.
|
|
|
2305 @c #### mention l(c)records here?
|
|
|
2306
|
|
|
2307 In older code, it was common practice to pass around pointers to
|
|
|
2308 @code{Lisp_@var{type}}, but this is now deprecated in favor of using
|
|
|
2309 @code{Lisp_Object} for all function arguments and return values that are
|
|
|
2310 Lisp objects. The @code{X@var{type}} macro is used to extract the
|
|
|
2311 pointer and cast it to @code{(Lisp_@var{type} *)} for the desired type.
|
|
|
2312
|
|
|
2313 @strong{Convention}: macros whose names begin with @samp{X} operate on
|
|
|
2314 @code{Lisp_Object}s and do no type-checking. Many such macros are type
|
|
|
2315 extractors, but others implement Lisp operations in C (@emph{e.g.},
|
|
|
2316 @code{XCAR} implements the Lisp @code{car} function). These are unsafe,
|
|
|
2317 and must only be used where types of all data have already been checked.
|
|
|
2318 Such macros are only applied to @code{Lisp_Object}s. In internal
|
|
|
2319 implementations where the pointer has already been converted, the
|
|
|
2320 structure is operated on directly using the C @code{->} member access
|
|
|
2321 operator.
|
|
|
2322
|
|
|
2323 The @code{@var{type}P}, @code{CHECK_@var{type}}, and
|
|
|
2324 @code{CONCHECK_@var{type}} macros are used to test types. The first
|
|
|
2325 returns a Boolean value, and the latter signal errors. (The
|
|
|
2326 @samp{CONCHECK} variety allows execution to be CONtinued under some
|
|
|
2327 circumstances, thus the name.) Functions which expect to be passed user
|
|
|
2328 data invariably call @samp{CHECK} macros on arguments.
|
|
|
2329
|
|
|
2330 There are many types of specialized Lisp objects implemented in C, but
|
|
|
2331 the most pervasive type is the @dfn{symbol}. Symbols are used as
|
|
|
2332 identifiers, variables, and functions.
|
|
|
2333
|
|
|
2334 @strong{Convention}: Global variables whose names begin with @samp{Q}
|
|
|
2335 are constants whose value is a symbol. The name of the variable should
|
|
|
2336 be derived from the name of the symbol using the same rules as for Lisp
|
|
|
2337 primitives. Such variables allow the C code to check whether a
|
|
|
2338 particular @code{Lisp_Object} is equal to a given symbol. Symbols are
|
|
|
2339 Lisp objects, so these variables may be passed to Lisp primitives. (An
|
|
|
2340 alternative to the use of @samp{Q...} variables is to call the
|
|
|
2341 @code{intern} function at initialization in the
|
|
|
2342 @code{vars_of_@var{module}} function, which is hardly less efficient.)
|
|
|
2343
|
|
|
2344 @strong{Convention}: Global variables whose names begin with @samp{V}
|
|
|
2345 are variables that contain Lisp objects. The convention here is that
|
|
|
2346 all global variables of type @code{Lisp_Object} begin with @samp{V}, and
|
|
|
2347 no others do (not even integer and boolean variables that have Lisp
|
|
|
2348 equivalents). Most of the time, these variables have equivalents in
|
|
|
2349 Lisp, which are defined via the @samp{DEFVAR} family of macros, but some
|
|
|
2350 don't. Since the variable's value is a @code{Lisp_Object}, it can be
|
|
|
2351 passed to Lisp primitives.
|
|
|
2352
|
|
|
2353 The implementation of Lisp primitives is more complex.
|
|
|
2354 @strong{Convention}: Global variables with names beginning with @samp{S}
|
|
|
2355 contain a structure that allows the Lisp engine to identify and call a C
|
|
|
2356 function. In modern versions of XEmacs, these identifiers are almost
|
|
|
2357 always completely hidden in the @code{DEFUN} and @code{SUBR} macros, but
|
|
|
2358 you will encounter them if you look at very old versions of XEmacs or at
|
|
|
2359 GNU Emacs. @strong{Convention}: Functions with names beginning with
|
|
|
2360 @samp{F} implement Lisp primitives. Of course all their arguments and
|
|
|
2361 their return values must be Lisp_Objects. (This is hidden in the
|
|
|
2362 @code{DEFUN} macro.)
|
|
|
2363
|
|
|
2364
|
|
462
|
2365 @node General Coding Rules
|
|
428
|
2366 @section General Coding Rules
|
|
462
|
2367 @cindex coding rules, general
|
|
428
|
2368
|
|
|
2369 The C code is actually written in a dialect of C called @dfn{Clean C},
|
|
|
2370 meaning that it can be compiled, mostly warning-free, with either a C or
|
|
|
2371 C++ compiler. Coding in Clean C has several advantages over plain C.
|
|
|
2372 C++ compilers are more nit-picking, and a number of coding errors have
|
|
|
2373 been found by compiling with C++. The ability to use both C and C++
|
|
|
2374 tools means that a greater variety of development tools are available to
|
|
|
2375 the developer.
|
|
|
2376
|
|
|
2377 Every module includes @file{<config.h>} (angle brackets so that
|
|
|
2378 @samp{--srcdir} works correctly; @file{config.h} may or may not be in
|
|
|
2379 the same directory as the C sources) and @file{lisp.h}. @file{config.h}
|
|
|
2380 must always be included before any other header files (including
|
|
|
2381 system header files) to ensure that certain tricks played by various
|
|
|
2382 @file{s/} and @file{m/} files work out correctly.
|
|
|
2383
|
|
440
|
2384 When including header files, always use angle brackets, not double
|
|
442
|
2385 quotes, except when the file to be included is always in the same
|
|
|
2386 directory as the including file. If either file is a generated file,
|
|
|
2387 then that is not likely to be the case. In order to understand why we
|
|
|
2388 have this rule, imagine what happens when you do a build in the source
|
|
|
2389 directory using @samp{./configure} and another build in another
|
|
|
2390 directory using @samp{../work/configure}. There will be two different
|
|
|
2391 @file{config.h} files. Which one will be used if you @samp{#include
|
|
|
2392 "config.h"}?
|
|
440
|
2393
|
|
448
|
2394 Almost every module contains a @code{syms_of_*()} function and a
|
|
|
2395 @code{vars_of_*()} function. The former declares any Lisp primitives
|
|
|
2396 you have defined and defines any symbols you will be using. The latter
|
|
|
2397 declares any global Lisp variables you have added and initializes global
|
|
|
2398 C variables in the module. @strong{Important}: There are stringent
|
|
|
2399 requirements on exactly what can go into these functions. See the
|
|
|
2400 comment in @file{emacs.c}. The reason for this is to avoid obscure
|
|
|
2401 unwanted interactions during initialization. If you don't follow these
|
|
|
2402 rules, you'll be sorry! If you want to do anything that isn't allowed,
|
|
|
2403 create a @code{complex_vars_of_*()} function for it. Doing this is
|
|
|
2404 tricky, though: you have to make sure your function is called at the
|
|
|
2405 right time so that all the initialization dependencies work out.
|
|
|
2406
|
|
|
2407 Declare each function of these kinds in @file{symsinit.h}. Make sure
|
|
|
2408 it's called in the appropriate place in @file{emacs.c}. You never need
|
|
|
2409 to include @file{symsinit.h} directly, because it is included by
|
|
|
2410 @file{lisp.h}.
|
|
|
2411
|
|
428
|
2412 @strong{All global and static variables that are to be modifiable must
|
|
|
2413 be declared uninitialized.} This means that you may not use the
|
|
|
2414 ``declare with initializer'' form for these variables, such as @code{int
|
|
|
2415 some_variable = 0;}. The reason for this has to do with some kludges
|
|
|
2416 done during the dumping process: If possible, the initialized data
|
|
|
2417 segment is re-mapped so that it becomes part of the (unmodifiable) code
|
|
|
2418 segment in the dumped executable. This allows this memory to be shared
|
|
|
2419 among multiple running XEmacs processes. XEmacs is careful to place as
|
|
442
|
2420 much constant data as possible into initialized variables during the
|
|
|
2421 @file{temacs} phase.
|
|
428
|
2422
|
|
|
2423 @cindex copy-on-write
|
|
|
2424 @strong{Please note:} This kludge only works on a few systems nowadays,
|
|
|
2425 and is rapidly becoming irrelevant because most modern operating systems
|
|
|
2426 provide @dfn{copy-on-write} semantics. All data is initially shared
|
|
|
2427 between processes, and a private copy is automatically made (on a
|
|
|
2428 page-by-page basis) when a process first attempts to write to a page of
|
|
|
2429 memory.
|
|
|
2430
|
|
|
2431 Formerly, there was a requirement that static variables not be declared
|
|
|
2432 inside of functions. This had to do with another hack along the same
|
|
|
2433 vein as what was just described: old USG systems put statically-declared
|
|
|
2434 variables in the initialized data space, so those header files had a
|
|
|
2435 @code{#define static} declaration. (That way, the data-segment remapping
|
|
|
2436 described above could still work.) This fails badly on static variables
|
|
|
2437 inside of functions, which suddenly become automatic variables;
|
|
|
2438 therefore, you weren't supposed to have any of them. This awful kludge
|
|
|
2439 has been removed in XEmacs because
|
|
|
2440
|
|
|
2441 @enumerate
|
|
|
2442 @item
|
|
|
2443 almost all of the systems that used this kludge ended up having
|
|
|
2444 to disable the data-segment remapping anyway;
|
|
|
2445 @item
|
|
|
2446 the only systems that didn't were extremely outdated ones;
|
|
|
2447 @item
|
|
|
2448 this hack completely messed up inline functions.
|
|
|
2449 @end enumerate
|
|
|
2450
|
|
|
2451 The C source code makes heavy use of C preprocessor macros. One popular
|
|
|
2452 macro style is:
|
|
|
2453
|
|
|
2454 @example
|
|
442
|
2455 #define FOO(var, value) do @{ \
|
|
440
|
2456 Lisp_Object FOO_value = (value); \
|
|
|
2457 ... /* compute using FOO_value */ \
|
|
|
2458 (var) = bar; \
|
|
428
|
2459 @} while (0)
|
|
|
2460 @end example
|
|
|
2461
|
|
|
2462 The @code{do @{...@} while (0)} is a standard trick to allow FOO to have
|
|
|
2463 statement semantics, so that it can safely be used within an @code{if}
|
|
|
2464 statement in C, for example. Multiple evaluation is prevented by
|
|
|
2465 copying a supplied argument into a local variable, so that
|
|
|
2466 @code{FOO(var,fun(1))} only calls @code{fun} once.
|
|
|
2467
|
|
|
2468 Lisp lists are popular data structures in the C code as well as in
|
|
|
2469 Elisp. There are two sets of macros that iterate over lists.
|
|
|
2470 @code{EXTERNAL_LIST_LOOP_@var{n}} should be used when the list has been
|
|
|
2471 supplied by the user, and cannot be trusted to be acyclic and
|
|
444
|
2472 @code{nil}-terminated. A @code{malformed-list} or @code{circular-list} error
|
|
428
|
2473 will be generated if the list being iterated over is not entirely
|
|
|
2474 kosher. @code{LIST_LOOP_@var{n}}, on the other hand, is faster and less
|
|
|
2475 safe, and can be used only on trusted lists.
|
|
|
2476
|
|
|
2477 Related macros are @code{GET_EXTERNAL_LIST_LENGTH} and
|
|
|
2478 @code{GET_LIST_LENGTH}, which calculate the length of a list, and in the
|
|
|
2479 case of @code{GET_EXTERNAL_LIST_LENGTH}, validating the properness of
|
|
|
2480 the list. The macros @code{EXTERNAL_LIST_LOOP_DELETE_IF} and
|
|
|
2481 @code{LIST_LOOP_DELETE_IF} delete elements from a lisp list satisfying some
|
|
|
2482 predicate.
|
|
|
2483
|
|
462
|
2484 @node Writing Lisp Primitives
|
|
428
|
2485 @section Writing Lisp Primitives
|
|
462
|
2486 @cindex writing Lisp primitives
|
|
|
2487 @cindex Lisp primitives, writing
|
|
|
2488 @cindex primitives, writing Lisp
|
|
428
|
2489
|
|
|
2490 Lisp primitives are Lisp functions implemented in C. The details of
|
|
|
2491 interfacing the C function so that Lisp can call it are handled by a few
|
|
|
2492 C macros. The only way to really understand how to write new C code is
|
|
|
2493 to read the source, but we can explain some things here.
|
|
|
2494
|
|
|
2495 An example of a special form is the definition of @code{prog1}, from
|
|
|
2496 @file{eval.c}. (An ordinary function would have the same general
|
|
|
2497 appearance.)
|
|
|
2498
|
|
|
2499 @cindex garbage collection protection
|
|
|
2500 @smallexample
|
|
|
2501 @group
|
|
|
2502 DEFUN ("prog1", Fprog1, 1, UNEVALLED, 0, /*
|
|
|
2503 Similar to `progn', but the value of the first form is returned.
|
|
|
2504 \(prog1 FIRST BODY...): All the arguments are evaluated sequentially.
|
|
|
2505 The value of FIRST is saved during evaluation of the remaining args,
|
|
|
2506 whose values are discarded.
|
|
|
2507 */
|
|
|
2508 (args))
|
|
|
2509 @{
|
|
|
2510 /* This function can GC */
|
|
|
2511 REGISTER Lisp_Object val, form, tail;
|
|
|
2512 struct gcpro gcpro1;
|
|
|
2513
|
|
|
2514 val = Feval (XCAR (args));
|
|
|
2515
|
|
|
2516 GCPRO1 (val);
|
|
|
2517
|
|
|
2518 LIST_LOOP_3 (form, XCDR (args), tail)
|
|
|
2519 Feval (form);
|
|
|
2520
|
|
|
2521 UNGCPRO;
|
|
|
2522 return val;
|
|
|
2523 @}
|
|
|
2524 @end group
|
|
|
2525 @end smallexample
|
|
|
2526
|
|
|
2527 Let's start with a precise explanation of the arguments to the
|
|
|
2528 @code{DEFUN} macro. Here is a template for them:
|
|
|
2529
|
|
|
2530 @example
|
|
|
2531 @group
|
|
|
2532 DEFUN (@var{lname}, @var{fname}, @var{min_args}, @var{max_args}, @var{interactive}, /*
|
|
|
2533 @var{docstring}
|
|
|
2534 */
|
|
|
2535 (@var{arglist}))
|
|
|
2536 @end group
|
|
|
2537 @end example
|
|
|
2538
|
|
|
2539 @table @var
|
|
|
2540 @item lname
|
|
|
2541 This string is the name of the Lisp symbol to define as the function
|
|
|
2542 name; in the example above, it is @code{"prog1"}.
|
|
|
2543
|
|
|
2544 @item fname
|
|
|
2545 This is the C function name for this function. This is the name that is
|
|
|
2546 used in C code for calling the function. The name is, by convention,
|
|
|
2547 @samp{F} prepended to the Lisp name, with all dashes (@samp{-}) in the
|
|
|
2548 Lisp name changed to underscores. Thus, to call this function from C
|
|
|
2549 code, call @code{Fprog1}. Remember that the arguments are of type
|
|
|
2550 @code{Lisp_Object}; various macros and functions for creating values of
|
|
|
2551 type @code{Lisp_Object} are declared in the file @file{lisp.h}.
|
|
|
2552
|
|
|
2553 Primitives whose names are special characters (e.g. @code{+} or
|
|
|
2554 @code{<}) are named by spelling out, in some fashion, the special
|
|
|
2555 character: e.g. @code{Fplus()} or @code{Flss()}. Primitives whose names
|
|
|
2556 begin with normal alphanumeric characters but also contain special
|
|
|
2557 characters are spelled out in some creative way, e.g. @code{let*}
|
|
|
2558 becomes @code{FletX()}.
|
|
|
2559
|
|
|
2560 Each function also has an associated structure that holds the data for
|
|
|
2561 the subr object that represents the function in Lisp. This structure
|
|
|
2562 conveys the Lisp symbol name to the initialization routine that will
|
|
|
2563 create the symbol and store the subr object as its definition. The C
|
|
|
2564 variable name of this structure is always @samp{S} prepended to the
|
|
|
2565 @var{fname}. You hardly ever need to be aware of the existence of this
|
|
|
2566 structure, since @code{DEFUN} plus @code{DEFSUBR} takes care of all the
|
|
|
2567 details.
|
|
|
2568
|
|
|
2569 @item min_args
|
|
|
2570 This is the minimum number of arguments that the function requires. The
|
|
|
2571 function @code{prog1} allows a minimum of one argument.
|
|
|
2572
|
|
|
2573 @item max_args
|
|
|
2574 This is the maximum number of arguments that the function accepts, if
|
|
|
2575 there is a fixed maximum. Alternatively, it can be @code{UNEVALLED},
|
|
|
2576 indicating a special form that receives unevaluated arguments, or
|
|
|
2577 @code{MANY}, indicating an unlimited number of evaluated arguments (the
|
|
|
2578 C equivalent of @code{&rest}). Both @code{UNEVALLED} and @code{MANY}
|
|
|
2579 are macros. If @var{max_args} is a number, it may not be less than
|
|
|
2580 @var{min_args} and it may not be greater than 8. (If you need to add a
|
|
|
2581 function with more than 8 arguments, use the @code{MANY} form. Resist
|
|
|
2582 the urge to edit the definition of @code{DEFUN} in @file{lisp.h}. If
|
|
|
2583 you do it anyways, make sure to also add another clause to the switch
|
|
|
2584 statement in @code{primitive_funcall().})
|
|
|
2585
|
|
|
2586 @item interactive
|
|
|
2587 This is an interactive specification, a string such as might be used as
|
|
|
2588 the argument of @code{interactive} in a Lisp function. In the case of
|
|
|
2589 @code{prog1}, it is 0 (a null pointer), indicating that @code{prog1}
|
|
|
2590 cannot be called interactively. A value of @code{""} indicates a
|
|
|
2591 function that should receive no arguments when called interactively.
|
|
|
2592
|
|
|
2593 @item docstring
|
|
|
2594 This is the documentation string. It is written just like a
|
|
|
2595 documentation string for a function defined in Lisp; in particular, the
|
|
|
2596 first line should be a single sentence. Note how the documentation
|
|
|
2597 string is enclosed in a comment, none of the documentation is placed on
|
|
|
2598 the same lines as the comment-start and comment-end characters, and the
|
|
|
2599 comment-start characters are on the same line as the interactive
|
|
|
2600 specification. @file{make-docfile}, which scans the C files for
|
|
|
2601 documentation strings, is very particular about what it looks for, and
|
|
|
2602 will not properly extract the doc string if it's not in this exact format.
|
|
|
2603
|
|
|
2604 In order to make both @file{etags} and @file{make-docfile} happy, make
|
|
|
2605 sure that the @code{DEFUN} line contains the @var{lname} and
|
|
|
2606 @var{fname}, and that the comment-start characters for the doc string
|
|
|
2607 are on the same line as the interactive specification, and put a newline
|
|
|
2608 directly after them (and before the comment-end characters).
|
|
|
2609
|
|
|
2610 @item arglist
|
|
|
2611 This is the comma-separated list of arguments to the C function. For a
|
|
|
2612 function with a fixed maximum number of arguments, provide a C argument
|
|
|
2613 for each Lisp argument. In this case, unlike regular C functions, the
|
|
|
2614 types of the arguments are not declared; they are simply always of type
|
|
|
2615 @code{Lisp_Object}.
|
|
|
2616
|
|
|
2617 The names of the C arguments will be used as the names of the arguments
|
|
|
2618 to the Lisp primitive as displayed in its documentation, modulo the same
|
|
|
2619 concerns described above for @code{F...} names (in particular,
|
|
|
2620 underscores in the C arguments become dashes in the Lisp arguments).
|
|
|
2621
|
|
|
2622 There is one additional kludge: A trailing `_' on the C argument is
|
|
|
2623 discarded when forming the Lisp argument. This allows C language
|
|
|
2624 reserved words (like @code{default}) or global symbols (like
|
|
|
2625 @code{dirname}) to be used as argument names without compiler warnings
|
|
|
2626 or errors.
|
|
|
2627
|
|
|
2628 A Lisp function with @w{@var{max_args} = @code{UNEVALLED}} is a
|
|
|
2629 @w{@dfn{special form}}; its arguments are not evaluated. Instead it
|
|
|
2630 receives one argument of type @code{Lisp_Object}, a (Lisp) list of the
|
|
|
2631 unevaluated arguments, conventionally named @code{(args)}.
|
|
|
2632
|
|
|
2633 When a Lisp function has no upper limit on the number of arguments,
|
|
|
2634 specify @w{@var{max_args} = @code{MANY}}. In this case its implementation in
|
|
|
2635 C actually receives exactly two arguments: the number of Lisp arguments
|
|
|
2636 (an @code{int}) and the address of a block containing their values (a
|
|
|
2637 @w{@code{Lisp_Object *}}). In this case only are the C types specified
|
|
|
2638 in the @var{arglist}: @w{@code{(int nargs, Lisp_Object *args)}}.
|
|
|
2639
|
|
|
2640 @end table
|
|
|
2641
|
|
|
2642 Within the function @code{Fprog1} itself, note the use of the macros
|
|
|
2643 @code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to ``protect''
|
|
|
2644 a variable from garbage collection---to inform the garbage collector
|
|
|
2645 that it must look in that variable and regard the object pointed at by
|
|
|
2646 its contents as an accessible object. This is necessary whenever you
|
|
|
2647 call @code{Feval} or anything that can directly or indirectly call
|
|
|
2648 @code{Feval} (this includes the @code{QUIT} macro!). At such a time,
|
|
|
2649 any Lisp object that you intend to refer to again must be protected
|
|
|
2650 somehow. @code{UNGCPRO} cancels the protection of the variables that
|
|
|
2651 are protected in the current function. It is necessary to do this
|
|
|
2652 explicitly.
|
|
|
2653
|
|
|
2654 The macro @code{GCPRO1} protects just one local variable. If you want
|
|
|
2655 to protect two, use @code{GCPRO2} instead; repeating @code{GCPRO1} will
|
|
|
2656 not work. Macros @code{GCPRO3} and @code{GCPRO4} also exist.
|
|
|
2657
|
|
|
2658 These macros implicitly use local variables such as @code{gcpro1}; you
|
|
|
2659 must declare these explicitly, with type @code{struct gcpro}. Thus, if
|
|
|
2660 you use @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
|
|
|
2661
|
|
|
2662 @cindex caller-protects (@code{GCPRO} rule)
|
|
|
2663 Note also that the general rule is @dfn{caller-protects}; i.e. you are
|
|
|
2664 only responsible for protecting those Lisp objects that you create. Any
|
|
|
2665 objects passed to you as arguments should have been protected by whoever
|
|
|
2666 created them, so you don't in general have to protect them.
|
|
|
2667
|
|
|
2668 In particular, the arguments to any Lisp primitive are always
|
|
|
2669 automatically @code{GCPRO}ed, when called ``normally'' from Lisp code or
|
|
|
2670 bytecode. So only a few Lisp primitives that are called frequently from
|
|
|
2671 C code, such as @code{Fprogn} protect their arguments as a service to
|
|
|
2672 their caller. You don't need to protect your arguments when writing a
|
|
|
2673 new @code{DEFUN}.
|
|
|
2674
|
|
|
2675 @code{GCPRO}ing is perhaps the trickiest and most error-prone part of
|
|
|
2676 XEmacs coding. It is @strong{extremely} important that you get this
|
|
|
2677 right and use a great deal of discipline when writing this code.
|
|
|
2678 @xref{GCPROing, ,@code{GCPRO}ing}, for full details on how to do this.
|
|
|
2679
|
|
|
2680 What @code{DEFUN} actually does is declare a global structure of type
|
|
|
2681 @code{Lisp_Subr} whose name begins with capital @samp{SF} and which
|
|
|
2682 contains information about the primitive (e.g. a pointer to the
|
|
|
2683 function, its minimum and maximum allowed arguments, a string describing
|
|
|
2684 its Lisp name); @code{DEFUN} then begins a normal C function declaration
|
|
|
2685 using the @code{F...} name. The Lisp subr object that is the function
|
|
|
2686 definition of a primitive (i.e. the object in the function slot of the
|
|
|
2687 symbol that names the primitive) actually points to this @samp{SF}
|
|
|
2688 structure; when @code{Feval} encounters a subr, it looks in the
|
|
|
2689 structure to find out how to call the C function.
|
|
|
2690
|
|
|
2691 Defining the C function is not enough to make a Lisp primitive
|
|
|
2692 available; you must also create the Lisp symbol for the primitive (the
|
|
|
2693 symbol is @dfn{interned}; @pxref{Obarrays}) and store a suitable subr
|
|
|
2694 object in its function cell. (If you don't do this, the primitive won't
|
|
|
2695 be seen by Lisp code.) The code looks like this:
|
|
|
2696
|
|
|
2697 @example
|
|
|
2698 DEFSUBR (@var{fname});
|
|
|
2699 @end example
|
|
|
2700
|
|
|
2701 @noindent
|
|
|
2702 Here @var{fname} is the same name you used as the second argument to
|
|
|
2703 @code{DEFUN}.
|
|
|
2704
|
|
|
2705 This call to @code{DEFSUBR} should go in the @code{syms_of_*()} function
|
|
|
2706 at the end of the module. If no such function exists, create it and
|
|
|
2707 make sure to also declare it in @file{symsinit.h} and call it from the
|
|
|
2708 appropriate spot in @code{main()}. @xref{General Coding Rules}.
|
|
|
2709
|
|
|
2710 Note that C code cannot call functions by name unless they are defined
|
|
|
2711 in C. The way to call a function written in Lisp from C is to use
|
|
|
2712 @code{Ffuncall}, which embodies the Lisp function @code{funcall}. Since
|
|
|
2713 the Lisp function @code{funcall} accepts an unlimited number of
|
|
|
2714 arguments, in C it takes two: the number of Lisp-level arguments, and a
|
|
|
2715 one-dimensional array containing their values. The first Lisp-level
|
|
|
2716 argument is the Lisp function to call, and the rest are the arguments to
|
|
|
2717 pass to it. Since @code{Ffuncall} can call the evaluator, you must
|
|
|
2718 protect pointers from garbage collection around the call to
|
|
|
2719 @code{Ffuncall}. (However, @code{Ffuncall} explicitly protects all of
|
|
|
2720 its parameters, so you don't have to protect any pointers passed as
|
|
|
2721 parameters to it.)
|
|
|
2722
|
|
|
2723 The C functions @code{call0}, @code{call1}, @code{call2}, and so on,
|
|
|
2724 provide handy ways to call a Lisp function conveniently with a fixed
|
|
|
2725 number of arguments. They work by calling @code{Ffuncall}.
|
|
|
2726
|
|
|
2727 @file{eval.c} is a very good file to look through for examples;
|
|
|
2728 @file{lisp.h} contains the definitions for important macros and
|
|
|
2729 functions.
|
|
|
2730
|
|
462
|
2731 @node Writing Good Comments
|
|
|
2732 @section Writing Good Comments
|
|
|
2733 @cindex writing good comments
|
|
|
2734 @cindex comments, writing good
|
|
|
2735
|
|
|
2736 Comments are a lifeline for programmers trying to understand tricky
|
|
|
2737 code. In general, the less obvious it is what you are doing, the more
|
|
|
2738 you need a comment, and the more detailed it needs to be. You should
|
|
|
2739 always be on guard when you're writing code for stuff that's tricky, and
|
|
|
2740 should constantly be putting yourself in someone else's shoes and asking
|
|
|
2741 if that person could figure out without much difficulty what's going
|
|
|
2742 on. (Assume they are a competent programmer who understands the
|
|
|
2743 essentials of how the XEmacs code is structured but doesn't know much
|
|
|
2744 about the module you're working on or any algorithms you're using.) If
|
|
|
2745 you're not sure whether they would be able to, add a comment. Always
|
|
|
2746 err on the side of more comments, rather than less.
|
|
|
2747
|
|
|
2748 Generally, when making comments, there is no need to attribute them with
|
|
|
2749 your name or initials. This especially goes for small,
|
|
|
2750 easy-to-understand, non-opinionated ones. Also, comments indicating
|
|
|
2751 where, when, and by whom a file was changed are @emph{strongly}
|
|
|
2752 discouraged, and in general will be removed as they are discovered.
|
|
|
2753 This is exactly what @file{ChangeLogs} are there for. However, it can
|
|
|
2754 occasionally be useful to mark exactly where (but not when or by whom)
|
|
|
2755 changes are made, particularly when making small changes to a file
|
|
|
2756 imported from elsewhere. These marks help when later on a newer version
|
|
|
2757 of the file is imported and the changes need to be merged. (If
|
|
|
2758 everything were always kept in CVS, there would be no need for this.
|
|
|
2759 But in practice, this often doesn't happen, or the CVS repository is
|
|
|
2760 later on lost or unavailable to the person doing the update.)
|
|
|
2761
|
|
|
2762 When putting in an explicit opinion in a comment, you should
|
|
|
2763 @emph{always} attribute it with your name, and optionally the date.
|
|
|
2764 This also goes for long, complex comments explaining in detail the
|
|
|
2765 workings of something -- by putting your name there, you make it
|
|
|
2766 possible for someone who has questions about how that thing works to
|
|
|
2767 determine who wrote the comment so they can write to them. Preferably,
|
|
|
2768 use your actual name and not your initials, unless your initials are
|
|
|
2769 generally recognized (e.g. @samp{jwz}). You can use only your first
|
|
|
2770 name if it's obvious who you are; otherwise, give first and last name.
|
|
|
2771 If you're not a regular contributor, you might consider putting your
|
|
|
2772 email address in -- it may be in the ChangeLog, but after awhile
|
|
|
2773 ChangeLogs have a tendency of disappearing or getting
|
|
|
2774 muddled. (E.g. your comment may get copied somewhere else or even into
|
|
|
2775 another program, and tracking down the proper ChangeLog may be very
|
|
|
2776 difficult.)
|
|
|
2777
|
|
|
2778 If you come across an opinion that is not or no longer valid, or you
|
|
|
2779 come across any comment that no longer applies but you want to keep it
|
|
|
2780 around, enclose it in @samp{[[ } and @samp{ ]]} marks and add a comment
|
|
|
2781 afterwards explaining why the preceding comment is no longer valid. Put
|
|
|
2782 your name on this comment, as explained above.
|
|
|
2783
|
|
|
2784 Just as comments are a lifeline to programmers, incorrect comments are
|
|
|
2785 death. If you come across an incorrect comment, @strong{immediately}
|
|
|
2786 correct it or flag it as incorrect, as described in the previous
|
|
|
2787 paragraph. Whenever you work on a section of code, @emph{always} make
|
|
|
2788 sure to update any comments to be correct -- or, at the very least, flag
|
|
|
2789 them as incorrect.
|
|
|
2790
|
|
|
2791 To indicate a "todo" or other problem, use four pound signs --
|
|
|
2792 i.e. @samp{####}.
|
|
|
2793
|
|
|
2794 @node Adding Global Lisp Variables
|
|
428
|
2795 @section Adding Global Lisp Variables
|
|
462
|
2796 @cindex global Lisp variables, adding
|
|
|
2797 @cindex variables, adding global Lisp
|
|
428
|
2798
|
|
|
2799 Global variables whose names begin with @samp{Q} are constants whose
|
|
|
2800 value is a symbol of a particular name. The name of the variable should
|
|
|
2801 be derived from the name of the symbol using the same rules as for Lisp
|
|
|
2802 primitives. These variables are initialized using a call to
|
|
|
2803 @code{defsymbol()} in the @code{syms_of_*()} function. (This call
|
|
|
2804 interns a symbol, sets the C variable to the resulting Lisp object, and
|
|
|
2805 calls @code{staticpro()} on the C variable to tell the
|
|
|
2806 garbage-collection mechanism about this variable. What
|
|
|
2807 @code{staticpro()} does is add a pointer to the variable to a large
|
|
|
2808 global array; when garbage-collection happens, all pointers listed in
|
|
|
2809 the array are used as starting points for marking Lisp objects. This is
|
|
|
2810 important because it's quite possible that the only current reference to
|
|
|
2811 the object is the C variable. In the case of symbols, the
|
|
|
2812 @code{staticpro()} doesn't matter all that much because the symbol is
|
|
|
2813 contained in @code{obarray}, which is itself @code{staticpro()}ed.
|
|
|
2814 However, it's possible that a naughty user could do something like
|
|
|
2815 uninterning the symbol out of @code{obarray} or even setting
|
|
|
2816 @code{obarray} to a different value [although this is likely to make
|
|
|
2817 XEmacs crash!].)
|
|
|
2818
|
|
|
2819 @strong{Please note:} It is potentially deadly if you declare a
|
|
|
2820 @samp{Q...} variable in two different modules. The two calls to
|
|
|
2821 @code{defsymbol()} are no problem, but some linkers will complain about
|
|
|
2822 multiply-defined symbols. The most insidious aspect of this is that
|
|
|
2823 often the link will succeed anyway, but then the resulting executable
|
|
1709
|
2824 will sometimes crash in obscure ways during certain operations!
|
|
|
2825
|
|
|
2826 To avoid this problem, declare any symbols with common names (such as
|
|
428
|
2827 @code{text}) that are not obviously associated with this particular
|
|
1709
|
2828 module in the file @file{general-slots.h}. The ``-slots'' suffix
|
|
|
2829 indicates that this is a file that is included multiple times in
|
|
|
2830 @file{general.c}. Redefinition of preprocessor macros allows the
|
|
|
2831 effects to be different in each context, so this is actually more
|
|
|
2832 convenient and less error-prone than doing it in your module.
|
|
428
|
2833
|
|
|
2834 Global variables whose names begin with @samp{V} are variables that
|
|
|
2835 contain Lisp objects. The convention here is that all global variables
|
|
|
2836 of type @code{Lisp_Object} begin with @samp{V}, and all others don't
|
|
|
2837 (including integer and boolean variables that have Lisp
|
|
|
2838 equivalents). Most of the time, these variables have equivalents in
|
|
|
2839 Lisp, but some don't. Those that do are declared this way by a call to
|
|
|
2840 @code{DEFVAR_LISP()} in the @code{vars_of_*()} initializer for the
|
|
|
2841 module. What this does is create a special @dfn{symbol-value-forward}
|
|
|
2842 Lisp object that contains a pointer to the C variable, intern a symbol
|
|
|
2843 whose name is as specified in the call to @code{DEFVAR_LISP()}, and set
|
|
|
2844 its value to the symbol-value-forward Lisp object; it also calls
|
|
|
2845 @code{staticpro()} on the C variable to tell the garbage-collection
|
|
|
2846 mechanism about the variable. When @code{eval} (or actually
|
|
|
2847 @code{symbol-value}) encounters this special object in the process of
|
|
|
2848 retrieving a variable's value, it follows the indirection to the C
|
|
|
2849 variable and gets its value. @code{setq} does similar things so that
|
|
|
2850 the C variable gets changed.
|
|
|
2851
|
|
|
2852 Whether or not you @code{DEFVAR_LISP()} a variable, you need to
|
|
|
2853 initialize it in the @code{vars_of_*()} function; otherwise it will end
|
|
|
2854 up as all zeroes, which is the integer 0 (@emph{not} @code{nil}), and
|
|
|
2855 this is probably not what you want. Also, if the variable is not
|
|
|
2856 @code{DEFVAR_LISP()}ed, @strong{you must call} @code{staticpro()} on the
|
|
|
2857 C variable in the @code{vars_of_*()} function. Otherwise, the
|
|
|
2858 garbage-collection mechanism won't know that the object in this variable
|
|
|
2859 is in use, and will happily collect it and reuse its storage for another
|
|
|
2860 Lisp object, and you will be the one who's unhappy when you can't figure
|
|
|
2861 out how your variable got overwritten.
|
|
|
2862
|
|
462
|
2863 @node Proper Use of Unsigned Types
|
|
|
2864 @section Proper Use of Unsigned Types
|
|
|
2865 @cindex unsigned types, proper use of
|
|
|
2866 @cindex types, proper use of unsigned
|
|
|
2867
|
|
|
2868 Avoid using @code{unsigned int} and @code{unsigned long} whenever
|
|
|
2869 possible. Unsigned types are viral -- any arithmetic or comparisons
|
|
|
2870 involving mixed signed and unsigned types are automatically converted to
|
|
|
2871 unsigned, which is almost certainly not what you want. Many subtle and
|
|
|
2872 hard-to-find bugs are created by careless use of unsigned types. In
|
|
|
2873 general, you should almost @emph{never} use an unsigned type to hold a
|
|
|
2874 regular quantity of any sort. The only exceptions are
|
|
|
2875
|
|
|
2876 @enumerate
|
|
|
2877 @item
|
|
|
2878 When there's a reasonable possibility you will actually need all 32 or
|
|
|
2879 64 bits to store the quantity.
|
|
|
2880 @item
|
|
|
2881 When calling existing API's that require unsigned types. In this case,
|
|
|
2882 you should still do all manipulation using signed types, and do the
|
|
|
2883 conversion at the very threshold of the API call.
|
|
|
2884 @item
|
|
|
2885 In existing code that you don't want to modify because you don't
|
|
|
2886 maintain it.
|
|
|
2887 @item
|
|
|
2888 In bit-field structures.
|
|
|
2889 @end enumerate
|
|
|
2890
|
|
|
2891 Other reasonable uses of @code{unsigned int} and @code{unsigned long}
|
|
|
2892 are representing non-quantities -- e.g. bit-oriented flags and such.
|
|
|
2893
|
|
|
2894 @node Coding for Mule
|
|
428
|
2895 @section Coding for Mule
|
|
462
|
2896 @cindex coding for Mule
|
|
|
2897 @cindex Mule, coding for
|
|
428
|
2898
|
|
|
2899 Although Mule support is not compiled by default in XEmacs, many people
|
|
|
2900 are using it, and we consider it crucial that new code works correctly
|
|
|
2901 with multibyte characters. This is not hard; it is only a matter of
|
|
|
2902 following several simple user-interface guidelines. Even if you never
|
|
|
2903 compile with Mule, with a little practice you will find it quite easy
|
|
|
2904 to code Mule-correctly.
|
|
|
2905
|
|
|
2906 Note that these guidelines are not necessarily tied to the current Mule
|
|
|
2907 implementation; they are also a good idea to follow on the grounds of
|
|
|
2908 code generalization for future I18N work.
|
|
|
2909
|
|
|
2910 @menu
|
|
|
2911 * Character-Related Data Types::
|
|
|
2912 * Working With Character and Byte Positions::
|
|
|
2913 * Conversion to and from External Data::
|
|
|
2914 * General Guidelines for Writing Mule-Aware Code::
|
|
|
2915 * An Example of Mule-Aware Code::
|
|
1261
|
2916 * Mule-izing Code::
|
|
428
|
2917 @end menu
|
|
|
2918
|
|
462
|
2919 @node Character-Related Data Types
|
|
428
|
2920 @subsection Character-Related Data Types
|
|
462
|
2921 @cindex character-related data types
|
|
|
2922 @cindex data types, character-related
|
|
428
|
2923
|
|
|
2924 First, let's review the basic character-related datatypes used by
|
|
1261
|
2925 XEmacs. Note that some of the separate @code{typedef}s are not
|
|
|
2926 mandatory, but they improve clarity of code a great deal, because one
|
|
428
|
2927 glance at the declaration can tell the intended use of the variable.
|
|
|
2928
|
|
|
2929 @table @code
|
|
1261
|
2930 @item Ichar
|
|
|
2931 @cindex Ichar
|
|
|
2932 An @code{Ichar} holds a single Emacs character.
|
|
428
|
2933
|
|
|
2934 Obviously, the equality between characters and bytes is lost in the Mule
|
|
|
2935 world. Characters can be represented by one or more bytes in the
|
|
1263
|
2936 buffer, and @code{Ichar} is a C type large enough to hold any
|
|
428
|
2937 character.
|
|
|
2938
|
|
1261
|
2939 Without Mule support, an @code{Ichar} is equivalent to an
|
|
428
|
2940 @code{unsigned char}.
|
|
|
2941
|
|
1261
|
2942 @item Ibyte
|
|
|
2943 @cindex Ibyte
|
|
428
|
2944 The data representing the text in a buffer or string is logically a set
|
|
1261
|
2945 of @code{Ibyte}s.
|
|
428
|
2946
|
|
442
|
2947 XEmacs does not work with the same character formats all the time; when
|
|
|
2948 reading characters from the outside, it decodes them to an internal
|
|
1261
|
2949 format, and likewise encodes them when writing. @code{Ibyte} (in fact
|
|
428
|
2950 @code{unsigned char}) is the basic unit of XEmacs internal buffers and
|
|
1263
|
2951 strings format. An @code{Ibyte *} is the type that points at text
|
|
442
|
2952 encoded in the variable-width internal encoding.
|
|
428
|
2953
|
|
1261
|
2954 One character can correspond to one or more @code{Ibyte}s. In the
|
|
442
|
2955 current Mule implementation, an ASCII character is represented by the
|
|
1261
|
2956 same @code{Ibyte}, and other characters are represented by a sequence
|
|
|
2957 of two or more @code{Ibyte}s.
|
|
442
|
2958
|
|
|
2959 Without Mule support, there are exactly 256 characters, implicitly
|
|
1261
|
2960 Latin-1, and each character is represented using one @code{Ibyte}, and
|
|
|
2961 there is a one-to-one correspondence between @code{Ibyte}s and
|
|
|
2962 @code{Ichar}s.
|
|
|
2963
|
|
|
2964 @item Charxpos
|
|
|
2965 @item Charbpos
|
|
428
|
2966 @itemx Charcount
|
|
1261
|
2967 @cindex Charxpos
|
|
|
2968 @cindex Charbpos
|
|
428
|
2969 @cindex Charcount
|
|
1261
|
2970 A @code{Charbpos} represents a character position in a buffer. A
|
|
|
2971 @code{Charcount} represents a number (count) of characters. Logically,
|
|
|
2972 subtracting two @code{Charbpos} values yields a @code{Charcount} value.
|
|
|
2973 When representing a character position in a string, we just use
|
|
|
2974 @code{Charcount} directly. The reason for having a separate typedef for
|
|
|
2975 buffer positions is that they are 1-based, whereas string positions are
|
|
|
2976 0-based and hence string counts and positions can be freely intermixed (a
|
|
|
2977 string position is equivalent to the count of characters from the
|
|
|
2978 beginning). When representing a character position that could be either
|
|
|
2979 in a buffer or string (for example, in the extent code), @code{Charxpos}
|
|
|
2980 is used. Although all of these are @code{typedef}ed to
|
|
442
|
2981 @code{EMACS_INT}, we use them in preference to @code{EMACS_INT} to make
|
|
|
2982 it clear what sort of position is being used.
|
|
428
|
2983
|
|
1261
|
2984 @code{Charxpos}, @code{Charbpos} and @code{Charcount} values are the
|
|
|
2985 only ones that are ever visible to Lisp.
|
|
|
2986
|
|
|
2987 @item Bytexpos
|
|
428
|
2988 @itemx Bytecount
|
|
1261
|
2989 @cindex Bytebpos
|
|
428
|
2990 @cindex Bytecount
|
|
1261
|
2991 A @code{Bytebpos} represents a byte position in a buffer. A
|
|
|
2992 @code{Bytecount} represents the distance between two positions, in
|
|
|
2993 bytes. Byte positions in strings use @code{Bytecount}, and for byte
|
|
|
2994 positions that can be either in a buffer or string, @code{Bytexpos} is
|
|
|
2995 used. The relationship between @code{Bytexpos}, @code{Bytebpos} and
|
|
|
2996 @code{Bytecount} is the same as the relationship between
|
|
|
2997 @code{Charxpos}, @code{Charbpos} and @code{Charcount}.
|
|
428
|
2998
|
|
|
2999 @item Extbyte
|
|
|
3000 @cindex Extbyte
|
|
|
3001 When dealing with the outside world, XEmacs works with @code{Extbyte}s,
|
|
1261
|
3002 which are equivalent to @code{char}. The distance between two
|
|
|
3003 @code{Extbyte}s is a @code{Bytecount}, since external text is a
|
|
|
3004 byte-by-byte encoding. Extbytes occur mainly at the transition point
|
|
|
3005 between internal text and external functions. XEmacs code should not,
|
|
|
3006 if it can possibly avoid it, do any actual manipulation using external
|
|
|
3007 text, since its format is completely unpredictable (it might not even be
|
|
|
3008 ASCII-compatible).
|
|
428
|
3009 @end table
|
|
|
3010
|
|
462
|
3011 @node Working With Character and Byte Positions
|
|
428
|
3012 @subsection Working With Character and Byte Positions
|
|
462
|
3013 @cindex character and byte positions, working with
|
|
|
3014 @cindex byte positions, working with character and
|
|
|
3015 @cindex positions, working with character and byte
|
|
428
|
3016
|
|
|
3017 Now that we have defined the basic character-related types, we can look
|
|
|
3018 at the macros and functions designed for work with them and for
|
|
|
3019 conversion between them. Most of these macros are defined in
|
|
|
3020 @file{buffer.h}, and we don't discuss all of them here, but only the
|
|
|
3021 most important ones. Examining the existing code is the best way to
|
|
|
3022 learn about them.
|
|
|
3023
|
|
|
3024 @table @code
|
|
1261
|
3025 @item MAX_ICHAR_LEN
|
|
|
3026 @cindex MAX_ICHAR_LEN
|
|
442
|
3027 This preprocessor constant is the maximum number of buffer bytes to
|
|
|
3028 represent an Emacs character in the variable width internal encoding.
|
|
|
3029 It is useful when allocating temporary strings to keep a known number of
|
|
|
3030 characters. For instance:
|
|
428
|
3031
|
|
|
3032 @example
|
|
|
3033 @group
|
|
|
3034 @{
|
|
|
3035 Charcount cclen;
|
|
|
3036 ...
|
|
|
3037 @{
|
|
|
3038 /* Allocate place for @var{cclen} characters. */
|
|
1261
|
3039 Ibyte *buf = (Ibyte *) alloca (cclen * MAX_ICHAR_LEN);
|
|
428
|
3040 ...
|
|
|
3041 @end group
|
|
|
3042 @end example
|
|
|
3043
|
|
|
3044 If you followed the previous section, you can guess that, logically,
|
|
1261
|
3045 multiplying a @code{Charcount} value with @code{MAX_ICHAR_LEN} produces
|
|
428
|
3046 a @code{Bytecount} value.
|
|
|
3047
|
|
1261
|
3048 In the current Mule implementation, @code{MAX_ICHAR_LEN} equals 4.
|
|
428
|
3049 Without Mule, it is 1.
|
|
|
3050
|
|
1261
|
3051 @item itext_ichar
|
|
|
3052 @itemx set_itext_ichar
|
|
|
3053 @cindex itext_ichar
|
|
|
3054 @cindex set_itext_ichar
|
|
|
3055 The @code{itext_ichar} macro takes a @code{Ibyte} pointer and
|
|
|
3056 returns the @code{Ichar} stored at that position. If it were a
|
|
428
|
3057 function, its prototype would be:
|
|
|
3058
|
|
|
3059 @example
|
|
1261
|
3060 Ichar itext_ichar (Ibyte *p);
|
|
|
3061 @end example
|
|
|
3062
|
|
|
3063 @code{set_itext_ichar} stores an @code{Ichar} to the specified byte
|
|
428
|
3064 position. It returns the number of bytes stored:
|
|
|
3065
|
|
|
3066 @example
|
|
1261
|
3067 Bytecount set_itext_ichar (Ibyte *p, Ichar c);
|
|
|
3068 @end example
|
|
|
3069
|
|
|
3070 It is important to note that @code{set_itext_ichar} is safe only for
|
|
428
|
3071 appending a character at the end of a buffer, not for overwriting a
|
|
|
3072 character in the middle. This is because the width of characters
|
|
1261
|
3073 varies, and @code{set_itext_ichar} cannot resize the string if it
|
|
428
|
3074 writes, say, a two-byte character where a single-byte character used to
|
|
|
3075 reside.
|
|
|
3076
|
|
1261
|
3077 A typical use of @code{set_itext_ichar} can be demonstrated by this
|
|
428
|
3078 example, which copies characters from buffer @var{buf} to a temporary
|
|
1261
|
3079 string of Ibytes.
|
|
428
|
3080
|
|
|
3081 @example
|
|
|
3082 @group
|
|
|
3083 @{
|
|
1261
|
3084 Charbpos pos;
|
|
428
|
3085 for (pos = beg; pos < end; pos++)
|
|
|
3086 @{
|
|
1261
|
3087 Ichar c = BUF_FETCH_CHAR (buf, pos);
|
|
|
3088 p += set_itext_ichar (buf, c);
|
|
428
|
3089 @}
|
|
|
3090 @}
|
|
|
3091 @end group
|
|
|
3092 @end example
|
|
|
3093
|
|
1261
|
3094 Note how @code{set_itext_ichar} is used to store the @code{Ichar}
|
|
428
|
3095 and increment the counter, at the same time.
|
|
|
3096
|
|
1261
|
3097 @item INC_IBYTEPTR
|
|
|
3098 @itemx DEC_IBYTEPTR
|
|
|
3099 @cindex INC_IBYTEPTR
|
|
|
3100 @cindex DEC_IBYTEPTR
|
|
|
3101 These two macros increment and decrement an @code{Ibyte} pointer,
|
|
428
|
3102 respectively. They will adjust the pointer by the appropriate number of
|
|
|
3103 bytes according to the byte length of the character stored there. Both
|
|
|
3104 macros assume that the memory address is located at the beginning of a
|
|
|
3105 valid character.
|
|
|
3106
|
|
1261
|
3107 Without Mule support, @code{INC_IBYTEPTR (p)} and @code{DEC_IBYTEPTR (p)}
|
|
428
|
3108 simply expand to @code{p++} and @code{p--}, respectively.
|
|
|
3109
|
|
|
3110 @item bytecount_to_charcount
|
|
|
3111 @cindex bytecount_to_charcount
|
|
|
3112 Given a pointer to a text string and a length in bytes, return the
|
|
|
3113 equivalent length in characters.
|
|
|
3114
|
|
|
3115 @example
|
|
1261
|
3116 Charcount bytecount_to_charcount (Ibyte *p, Bytecount bc);
|
|
428
|
3117 @end example
|
|
|
3118
|
|
|
3119 @item charcount_to_bytecount
|
|
|
3120 @cindex charcount_to_bytecount
|
|
|
3121 Given a pointer to a text string and a length in characters, return the
|
|
|
3122 equivalent length in bytes.
|
|
|
3123
|
|
|
3124 @example
|
|
1261
|
3125 Bytecount charcount_to_bytecount (Ibyte *p, Charcount cc);
|
|
|
3126 @end example
|
|
|
3127
|
|
|
3128 @item itext_n_addr
|
|
|
3129 @cindex itext_n_addr
|
|
428
|
3130 Return a pointer to the beginning of the character offset @var{cc} (in
|
|
|
3131 characters) from @var{p}.
|
|
|
3132
|
|
|
3133 @example
|
|
1261
|
3134 Ibyte *itext_n_addr (Ibyte *p, Charcount cc);
|
|
428
|
3135 @end example
|
|
|
3136 @end table
|
|
|
3137
|
|
462
|
3138 @node Conversion to and from External Data
|
|
428
|
3139 @subsection Conversion to and from External Data
|
|
462
|
3140 @cindex conversion to and from external data
|
|
|
3141 @cindex external data, conversion to and from
|
|
428
|
3142
|
|
|
3143 When an external function, such as a C library function, returns a
|
|
1261
|
3144 @code{char} pointer, you should almost never treat it as @code{Ibyte}.
|
|
428
|
3145 This is because these returned strings may contain 8bit characters which
|
|
|
3146 can be misinterpreted by XEmacs, and cause a crash. Likewise, when
|
|
|
3147 exporting a piece of internal text to the outside world, you should
|
|
|
3148 always convert it to an appropriate external encoding, lest the internal
|
|
|
3149 stuff (such as the infamous \201 characters) leak out.
|
|
|
3150
|
|
|
3151 The interface to conversion between the internal and external
|
|
|
3152 representations of text are the numerous conversion macros defined in
|
|
442
|
3153 @file{buffer.h}. There used to be a fixed set of external formats
|
|
|
3154 supported by these macros, but now any coding system can be used with
|
|
1263
|
3155 them. The coding system alias mechanism is used to create the
|
|
442
|
3156 following logical coding systems, which replace the fixed external
|
|
|
3157 formats. The (dontusethis-set-symbol-value-handler) mechanism was
|
|
1261
|
3158 enhanced to make this possible (more work on that is needed).
|
|
|
3159
|
|
1263
|
3160 Often useful coding systems:
|
|
428
|
3161
|
|
|
3162 @table @code
|
|
442
|
3163 @item Qbinary
|
|
|
3164 This is the simplest format and is what we use in the absence of a more
|
|
|
3165 appropriate format. This converts according to the @code{binary} coding
|
|
|
3166 system:
|
|
|
3167
|
|
|
3168 @enumerate a
|
|
|
3169 @item
|
|
|
3170 On input, bytes 0--255 are converted into (implicitly Latin-1)
|
|
|
3171 characters 0--255. A non-Mule xemacs doesn't really know about
|
|
|
3172 different character sets and the fonts to display them, so the bytes can
|
|
|
3173 be treated as text in different 1-byte encodings by simply setting the
|
|
|
3174 appropriate fonts. So in a sense, non-Mule xemacs is a multi-lingual
|
|
|
3175 editor if, for example, different fonts are used to display text in
|
|
|
3176 different buffers, faces, or windows. The specifier mechanism gives the
|
|
|
3177 user complete control over this kind of behavior.
|
|
|
3178 @item
|
|
|
3179 On output, characters 0--255 are converted into bytes 0--255 and other
|
|
|
3180 characters are converted into `~'.
|
|
|
3181 @end enumerate
|
|
|
3182
|
|
|
3183 @item Qnative
|
|
|
3184 Format used for the external Unix environment---@code{argv[]}, stuff
|
|
|
3185 from @code{getenv()}, stuff from the @file{/etc/passwd} file, etc.
|
|
1261
|
3186 This is encoded according to the encoding specified by the current locale.
|
|
|
3187
|
|
|
3188 @item Qfile_name
|
|
|
3189 Format used for filenames. This is normally the same as @code{Qnative},
|
|
|
3190 but the two should be distinguished for clarity and possible future
|
|
|
3191 separation -- and also because @code{Qfile_name} can be changed using either
|
|
|
3192 the @code{file-name-coding-system} or @code{pathname-coding-system} (now
|
|
|
3193 obsolete) variables.
|
|
442
|
3194
|
|
|
3195 @item Qctext
|
|
1261
|
3196 Compound-text format. This is the standard X11 format used for data
|
|
442
|
3197 stored in properties, selections, and the like. This is an 8-bit
|
|
|
3198 no-lock-shift ISO2022 coding system. This is a real coding system,
|
|
1261
|
3199 unlike @code{Qfile_name}, which is user-definable.
|
|
|
3200
|
|
|
3201 @item Qmswindows_tstr
|
|
|
3202 Used for external data in all MS Windows functions that are declared to
|
|
|
3203 accept data of type @code{LPTSTR} or @code{LPCSTR}. This maps to either
|
|
|
3204 @code{Qmswindows_multibyte} (a locale-specific encoding, same as
|
|
|
3205 @code{Qnative}) or @code{Qmswindows_unicode}, depending on whether
|
|
|
3206 XEmacs is being run under Windows 9X or Windows NT/2000/XP.
|
|
428
|
3207 @end table
|
|
|
3208
|
|
1263
|
3209 Many other coding systems are provided by default.
|
|
|
3210
|
|
442
|
3211 There are two fundamental macros to convert between external and
|
|
1261
|
3212 internal format, as well as various convenience macros to simplify the
|
|
|
3213 most common operations.
|
|
442
|
3214
|
|
|
3215 @code{TO_INTERNAL_FORMAT} converts external data to internal format, and
|
|
|
3216 @code{TO_EXTERNAL_FORMAT} converts the other way around. The arguments
|
|
|
3217 each of these receives are a source type, a source, a sink type, a sink,
|
|
|
3218 and a coding system (or a symbol naming a coding system).
|
|
|
3219
|
|
|
3220 A typical call looks like
|
|
|
3221 @example
|
|
|
3222 TO_EXTERNAL_FORMAT (LISP_STRING, str, C_STRING_MALLOC, ptr, Qfile_name);
|
|
|
3223 @end example
|
|
|
3224
|
|
|
3225 which means that the contents of the lisp string @code{str} are written
|
|
|
3226 to a malloc'ed memory area which will be pointed to by @code{ptr}, after
|
|
|
3227 the function returns. The conversion will be done using the
|
|
|
3228 @code{file-name} coding system, which will be controlled by the user
|
|
|
3229 indirectly by setting or binding the variable
|
|
|
3230 @code{file-name-coding-system}.
|
|
|
3231
|
|
|
3232 Some sources and sinks require two C variables to specify. We use some
|
|
|
3233 preprocessor magic to allow different source and sink types, and even
|
|
|
3234 different numbers of arguments to specify different types of sources and
|
|
|
3235 sinks.
|
|
|
3236
|
|
|
3237 So we can have a call that looks like
|
|
|
3238 @example
|
|
|
3239 TO_INTERNAL_FORMAT (DATA, (ptr, len),
|
|
|
3240 MALLOC, (ptr, len),
|
|
|
3241 coding_system);
|
|
|
3242 @end example
|
|
|
3243
|
|
|
3244 The parenthesized argument pairs are required to make the preprocessor
|
|
|
3245 magic work.
|
|
|
3246
|
|
|
3247 Here are the different source and sink types:
|
|
|
3248
|
|
|
3249 @table @code
|
|
|
3250 @item @code{DATA, (ptr, len),}
|
|
|
3251 input data is a fixed buffer of size @var{len} at address @var{ptr}
|
|
|
3252 @item @code{ALLOCA, (ptr, len),}
|
|
|
3253 output data is placed in an alloca()ed buffer of size @var{len} pointed to by @var{ptr}
|
|
|
3254 @item @code{MALLOC, (ptr, len),}
|
|
|
3255 output data is in a malloc()ed buffer of size @var{len} pointed to by @var{ptr}
|
|
|
3256 @item @code{C_STRING_ALLOCA, ptr,}
|
|
|
3257 equivalent to @code{ALLOCA (ptr, len_ignored)} on output.
|
|
|
3258 @item @code{C_STRING_MALLOC, ptr,}
|
|
|
3259 equivalent to @code{MALLOC (ptr, len_ignored)} on output
|
|
|
3260 @item @code{C_STRING, ptr,}
|
|
1261
|
3261 equivalent to @code{DATA, (ptr, strlen/wcslen (ptr))} on input
|
|
442
|
3262 @item @code{LISP_STRING, string,}
|
|
|
3263 input or output is a Lisp_Object of type string
|
|
|
3264 @item @code{LISP_BUFFER, buffer,}
|
|
|
3265 output is written to @code{(point)} in lisp buffer @var{buffer}
|
|
|
3266 @item @code{LISP_LSTREAM, lstream,}
|
|
|
3267 input or output is a Lisp_Object of type lstream
|
|
|
3268 @item @code{LISP_OPAQUE, object,}
|
|
|
3269 input or output is a Lisp_Object of type opaque
|
|
|
3270 @end table
|
|
|
3271
|
|
1261
|
3272 A source type of @code{C_STRING} or a sink type of
|
|
|
3273 @code{C_STRING_ALLOCA} or @code{C_STRING_MALLOC} is appropriate where
|
|
|
3274 the external API is not '\0'-byte-clean -- i.e. it expects strings to be
|
|
|
3275 terminated with a null byte. For external API's that are in fact
|
|
|
3276 '\0'-byte-clean, we should of course not use these.
|
|
442
|
3277
|
|
|
3278 The sinks to be specified must be lvalues, unless they are the lisp
|
|
|
3279 object types @code{LISP_LSTREAM} or @code{LISP_BUFFER}.
|
|
|
3280
|
|
1261
|
3281 There is no problem using the same lvalue for source and sink.
|
|
|
3282
|
|
|
3283 Garbage collection is inhibited during these conversion operations, so
|
|
|
3284 it is OK to pass in data from Lisp strings using @code{XSTRING_DATA}.
|
|
|
3285
|
|
442
|
3286 For the sink types @code{ALLOCA} and @code{C_STRING_ALLOCA}, the
|
|
|
3287 resulting text is stored in a stack-allocated buffer, which is
|
|
|
3288 automatically freed on returning from the function. However, the sink
|
|
|
3289 types @code{MALLOC} and @code{C_STRING_MALLOC} return @code{xmalloc()}ed
|
|
|
3290 memory. The caller is responsible for freeing this memory using
|
|
|
3291 @code{xfree()}.
|
|
|
3292
|
|
|
3293 Note that it doesn't make sense for @code{LISP_STRING} to be a source
|
|
|
3294 for @code{TO_INTERNAL_FORMAT} or a sink for @code{TO_EXTERNAL_FORMAT}.
|
|
|
3295 You'll get an assertion failure if you try.
|
|
|
3296
|
|
1261
|
3297 99% of conversions involve raw data or Lisp strings as both source and
|
|
|
3298 sink, and usually data is output as @code{alloca()}, or sometimes
|
|
|
3299 @code{xmalloc()}. For this reason, convenience macros are defined for
|
|
|
3300 many types of conversions involving raw data and/or Lisp strings,
|
|
|
3301 especially when the output is an @code{alloca()}ed string. (When the
|
|
|
3302 destination is a Lisp string, there are other functions that should be
|
|
|
3303 used instead -- @code{build_ext_string()} and @code{make_ext_string()},
|
|
|
3304 for example.) The convenience macros are of two types -- the older kind
|
|
|
3305 that store the result into a specified variable, and the newer kind that
|
|
|
3306 return the result. The newer kind of macros don't exist when the output
|
|
|
3307 is sized data, because that would have two return values. NOTE: All
|
|
|
3308 convenience macros are ultimately defined in terms of
|
|
|
3309 @code{TO_EXTERNAL_FORMAT} and @code{TO_INTERNAL_FORMAT}. Thus, any
|
|
|
3310 comments above about the workings of these macros also apply to all
|
|
|
3311 convenience macros.
|
|
|
3312
|
|
|
3313 A typical old-style convenience macro is
|
|
|
3314
|
|
|
3315 @example
|
|
|
3316 C_STRING_TO_EXTERNAL (in, out, codesys);
|
|
|
3317 @end example
|
|
|
3318
|
|
|
3319 This is equivalent to
|
|
|
3320
|
|
|
3321 @example
|
|
|
3322 TO_EXTERNAL_FORMAT (C_STRING, in, C_STRING_ALLOCA, out, codesys);
|
|
|
3323 @end example
|
|
|
3324
|
|
|
3325 but is easier to write and somewhat clearer, since it clearly identifies
|
|
|
3326 the arguments without the clutter of having the preprocessor types mixed
|
|
|
3327 in.
|
|
|
3328
|
|
|
3329 The new-style equivalent is @code{NEW_C_STRING_TO_EXTERNAL (src,
|
|
|
3330 codesys)}, which @emph{returns} the converted data (still in
|
|
|
3331 @code{alloca()} space). This is far more convenient for most
|
|
|
3332 operations.
|
|
442
|
3333
|
|
462
|
3334 @node General Guidelines for Writing Mule-Aware Code
|
|
428
|
3335 @subsection General Guidelines for Writing Mule-Aware Code
|
|
462
|
3336 @cindex writing Mule-aware code, general guidelines for
|
|
|
3337 @cindex Mule-aware code, general guidelines for writing
|
|
|
3338 @cindex code, general guidelines for writing Mule-aware
|
|
428
|
3339
|
|
|
3340 This section contains some general guidance on how to write Mule-aware
|
|
|
3341 code, as well as some pitfalls you should avoid.
|
|
|
3342
|
|
|
3343 @table @emph
|
|
|
3344 @item Never use @code{char} and @code{char *}.
|
|
|
3345 In XEmacs, the use of @code{char} and @code{char *} is almost always a
|
|
|
3346 mistake. If you want to manipulate an Emacs character from ``C'', use
|
|
1261
|
3347 @code{Ichar}. If you want to examine a specific octet in the internal
|
|
|
3348 format, use @code{Ibyte}. If you want a Lisp-visible character, use a
|
|
428
|
3349 @code{Lisp_Object} and @code{make_char}. If you want a pointer to move
|
|
1261
|
3350 through the internal text, use @code{Ibyte *}. Also note that you
|
|
|
3351 almost certainly do not need @code{Ichar *}. Other typedefs to clarify
|
|
|
3352 the use of @code{char} are @code{Char_ASCII}, @code{Char_Binary},
|
|
|
3353 @code{UChar_Binary}, and @code{CIbyte}.
|
|
|
3354
|
|
|
3355 @item Be careful not to confuse @code{Charcount}, @code{Bytecount}, @code{Charbpos} and @code{Bytebpos}.
|
|
428
|
3356 The whole point of using different types is to avoid confusion about the
|
|
|
3357 use of certain variables. Lest this effect be nullified, you need to be
|
|
|
3358 careful about using the right types.
|
|
|
3359
|
|
|
3360 @item Always convert external data
|
|
|
3361 It is extremely important to always convert external data, because
|
|
1261
|
3362 XEmacs can crash if unexpected 8-bit sequences are copied to its internal
|
|
428
|
3363 buffers literally.
|
|
|
3364
|
|
|
3365 This means that when a system function, such as @code{readdir}, returns
|
|
1263
|
3366 a string, you normally need to convert it using one of the conversion macros
|
|
428
|
3367 described in the previous chapter, before passing it further to Lisp.
|
|
442
|
3368
|
|
|
3369 Actually, most of the basic system functions that accept '\0'-terminated
|
|
1261
|
3370 string arguments, like @code{stat()} and @code{open()}, have
|
|
|
3371 @strong{encapsulated} equivalents that do the internal to external
|
|
|
3372 conversion themselves. The encapsulated equivalents have a @code{qxe_}
|
|
|
3373 prefix and have string arguments of type @code{Ibyte *}, and you can
|
|
|
3374 pass internally encoded data to them, often from a Lisp string using
|
|
|
3375 @code{XSTRING_DATA}. (A better design might be to provide versions that
|
|
|
3376 accept Lisp strings directly.)
|
|
428
|
3377
|
|
|
3378 Also note that many internal functions, such as @code{make_string},
|
|
1261
|
3379 accept Ibytes, which removes the need for them to convert the data they
|
|
|
3380 receive. This increases efficiency because that way external data needs
|
|
|
3381 to be decoded only once, when it is read. After that, it is passed
|
|
|
3382 around in internal format.
|
|
|
3383
|
|
|
3384 @item Do all work in internal format
|
|
|
3385 External-formatted data is completely unpredictable in its format. It
|
|
1263
|
3386 may be fixed-width Unicode (not even ASCII compatible); it may be a
|
|
|
3387 modal encoding, in
|
|
1261
|
3388 which case some occurrences of (e.g.) the slash character may be part of
|
|
|
3389 two-byte Asian-language characters, and a naive attempt to split apart a
|
|
|
3390 pathname by slashes will fail; etc. Internal-format text should be
|
|
|
3391 converted to external format only at the point where an external API is
|
|
|
3392 actually called, and the first thing done after receiving
|
|
|
3393 external-format text from an external API should be to convert it to
|
|
|
3394 internal text.
|
|
428
|
3395 @end table
|
|
|
3396
|
|
462
|
3397 @node An Example of Mule-Aware Code
|
|
428
|
3398 @subsection An Example of Mule-Aware Code
|
|
462
|
3399 @cindex code, an example of Mule-aware
|
|
|
3400 @cindex Mule-aware code, an example of
|
|
428
|
3401
|
|
442
|
3402 As an example of Mule-aware code, we will analyze the @code{string}
|
|
|
3403 function, which conses up a Lisp string from the character arguments it
|
|
|
3404 receives. Here is the definition, pasted from @code{alloc.c}:
|
|
428
|
3405
|
|
|
3406 @example
|
|
|
3407 @group
|
|
|
3408 DEFUN ("string", Fstring, 0, MANY, 0, /*
|
|
|
3409 Concatenate all the argument characters and make the result a string.
|
|
|
3410 */
|
|
|
3411 (int nargs, Lisp_Object *args))
|
|
|
3412 @{
|
|
1261
|
3413 Ibyte *storage = alloca_array (Ibyte, nargs * MAX_ICHAR_LEN);
|
|
|
3414 Ibyte *p = storage;
|
|
428
|
3415
|
|
|
3416 for (; nargs; nargs--, args++)
|
|
|
3417 @{
|
|
|
3418 Lisp_Object lisp_char = *args;
|
|
|
3419 CHECK_CHAR_COERCE_INT (lisp_char);
|
|
1261
|
3420 p += set_itext_ichar (p, XCHAR (lisp_char));
|
|
428
|
3421 @}
|
|
|
3422 return make_string (storage, p - storage);
|
|
|
3423 @}
|
|
|
3424 @end group
|
|
|
3425 @end example
|
|
|
3426
|
|
|
3427 Now we can analyze the source line by line.
|
|
|
3428
|
|
|
3429 Obviously, string will be as long as there are arguments to the
|
|
1261
|
3430 function. This is why we allocate @code{MAX_ICHAR_LEN} * @var{nargs}
|
|
428
|
3431 bytes on the stack, i.e. the worst-case number of bytes for @var{nargs}
|
|
1261
|
3432 @code{Ichar}s to fit in the string.
|
|
428
|
3433
|
|
|
3434 Then, the loop checks that each element is a character, converting
|
|
|
3435 integers in the process. Like many other functions in XEmacs, this
|
|
|
3436 function silently accepts integers where characters are expected, for
|
|
|
3437 historical and compatibility reasons. Unless you know what you are
|
|
|
3438 doing, @code{CHECK_CHAR} will also suffice. @code{XCHAR (lisp_char)}
|
|
1261
|
3439 extracts the @code{Ichar} from the @code{Lisp_Object}, and
|
|
|
3440 @code{set_itext_ichar} stores it to storage, increasing @code{p} in
|
|
428
|
3441 the process.
|
|
|
3442
|
|
|
3443 Other instructive examples of correct coding under Mule can be found all
|
|
|
3444 over the XEmacs code. For starters, I recommend
|
|
|
3445 @code{Fnormalize_menu_item_name} in @file{menubar.c}. After you have
|
|
|
3446 understood this section of the manual and studied the examples, you can
|
|
|
3447 proceed writing new Mule-aware code.
|
|
|
3448
|
|
1261
|
3449 @node Mule-izing Code
|
|
|
3450 @subsection Mule-izing Code
|
|
|
3451
|
|
|
3452 A lot of code is written without Mule in mind, and needs to be made
|
|
|
3453 Mule-correct or "Mule-ized". There is really no substitute for
|
|
|
3454 line-by-line analysis when doing this, but the following checklist can
|
|
|
3455 help:
|
|
|
3456
|
|
|
3457 @itemize @bullet
|
|
|
3458 @item
|
|
|
3459 Check all uses of @code{XSTRING_DATA}.
|
|
|
3460 @item
|
|
|
3461 Check all uses of @code{build_string} and @code{make_string}.
|
|
|
3462 @item
|
|
|
3463 Check all uses of @code{tolower} and @code{toupper}.
|
|
|
3464 @item
|
|
|
3465 Check object print methods.
|
|
|
3466 @item
|
|
|
3467 Check for use of functions such as @code{write_c_string},
|
|
|
3468 @code{write_fmt_string}, @code{stderr_out}, @code{stdout_out}.
|
|
|
3469 @item
|
|
|
3470 Check all occurrences of @code{char} and correct to one of the other
|
|
|
3471 typedefs described above.
|
|
|
3472 @item
|
|
|
3473 Check all existing uses of @code{TO_EXTERNAL_FORMAT},
|
|
|
3474 @code{TO_INTERNAL_FORMAT}, and any convenience macros (grep for
|
|
|
3475 @samp{EXTERNAL_TO}, @samp{TO_EXTERNAL}, and @samp{TO_SIZED_EXTERNAL}).
|
|
|
3476 @item
|
|
|
3477 In Windows code, string literals may need to be encapsulated with @code{XETEXT}.
|
|
|
3478 @end itemize
|
|
|
3479
|
|
462
|
3480 @node Techniques for XEmacs Developers
|
|
428
|
3481 @section Techniques for XEmacs Developers
|
|
462
|
3482 @cindex techniques for XEmacs developers
|
|
|
3483 @cindex developers, techniques for XEmacs
|
|
|
3484
|
|
|
3485 @cindex Purify
|
|
|
3486 @cindex Quantify
|
|
442
|
3487 To make a purified XEmacs, do: @code{make puremacs}.
|
|
428
|
3488 To make a quantified XEmacs, do: @code{make quantmacs}.
|
|
|
3489
|
|
442
|
3490 You simply can't dump Quantified and Purified images (unless using the
|
|
|
3491 portable dumper). Purify gets confused when xemacs frees memory in one
|
|
|
3492 process that was allocated in a @emph{different} process on a different
|
|
|
3493 machine!. Run it like so:
|
|
|
3494 @example
|
|
|
3495 temacs -batch -l loadup.el run-temacs @var{xemacs-args...}
|
|
|
3496 @end example
|
|
428
|
3497
|
|
462
|
3498 @cindex error checking
|
|
428
|
3499 Before you go through the trouble, are you compiling with all
|
|
442
|
3500 debugging and error-checking off? If not, try that first. Be warned
|
|
428
|
3501 that while Quantify is directly responsible for quite a few
|
|
|
3502 optimizations which have been made to XEmacs, doing a run which
|
|
|
3503 generates results which can be acted upon is not necessarily a trivial
|
|
|
3504 task.
|
|
|
3505
|
|
|
3506 Also, if you're still willing to do some runs make sure you configure
|
|
|
3507 with the @samp{--quantify} flag. That will keep Quantify from starting
|
|
|
3508 to record data until after the loadup is completed and will shut off
|
|
|
3509 recording right before it shuts down (which generates enough bogus data
|
|
|
3510 to throw most results off). It also enables three additional elisp
|
|
|
3511 commands: @code{quantify-start-recording-data},
|
|
|
3512 @code{quantify-stop-recording-data} and @code{quantify-clear-data}.
|
|
|
3513
|
|
|
3514 If you want to make XEmacs faster, target your favorite slow benchmark,
|
|
|
3515 run a profiler like Quantify, @code{gprof}, or @code{tcov}, and figure
|
|
1024
|
3516 out where the cycles are going. In many cases you can localize the
|
|
|
3517 problem (because a particular new feature or even a single patch
|
|
|
3518 elicited it). Don't hesitate to use brute force techniques like a
|
|
|
3519 global counter incremented at strategic places, especially in
|
|
|
3520 combination with other performance indications (@emph{e.g.}, degree of
|
|
|
3521 buffer fragmentation into extents).
|
|
|
3522
|
|
|
3523 Specific projects:
|
|
428
|
3524
|
|
|
3525 @itemize @bullet
|
|
|
3526 @item
|
|
|
3527 Make the garbage collector faster. Figure out how to write an
|
|
|
3528 incremental garbage collector.
|
|
|
3529 @item
|
|
|
3530 Write a compiler that takes bytecode and spits out C code.
|
|
|
3531 Unfortunately, you will then need a C compiler and a more fully
|
|
|
3532 developed module system.
|
|
|
3533 @item
|
|
|
3534 Speed up redisplay.
|
|
|
3535 @item
|
|
1024
|
3536 Speed up syntax highlighting. It was suggested that ``maybe moving some
|
|
|
3537 of the syntax highlighting capabilities into C would make a
|
|
|
3538 difference.'' Wrong idea, I think. When processing one large file a
|
|
|
3539 particular low-level routine was being called 40 @emph{million} times
|
|
|
3540 simply for @emph{one} call to @code{newline-and-indent}. Syntax
|
|
|
3541 highlighting needs to be rewritten to use a reliable, fast parser, then
|
|
|
3542 to trust the pre-parsed structure, and only do re-highlighting locally
|
|
|
3543 to a text change. Modern machines are fast enough to implement such
|
|
|
3544 parsers in Lisp; but no machine will ever be fast enough to deal with
|
|
|
3545 quadratic (or worse) algorithms!
|
|
428
|
3546 @item
|
|
|
3547 Implement tail recursion in Emacs Lisp (hard!).
|
|
|
3548 @end itemize
|
|
|
3549
|
|
|
3550 Unfortunately, Emacs Lisp is slow, and is going to stay slow. Function
|
|
|
3551 calls in elisp are especially expensive. Iterating over a long list is
|
|
|
3552 going to be 30 times faster implemented in C than in Elisp.
|
|
|
3553
|
|
442
|
3554 Heavily used small code fragments need to be fast. The traditional way
|
|
|
3555 to implement such code fragments in C is with macros. But macros in C
|
|
|
3556 are known to be broken.
|
|
|
3557
|
|
462
|
3558 @cindex macro hygiene
|
|
442
|
3559 Macro arguments that are repeatedly evaluated may suffer from repeated
|
|
|
3560 side effects or suboptimal performance.
|
|
|
3561
|
|
|
3562 Variable names used in macros may collide with caller's variables,
|
|
|
3563 causing (at least) unwanted compiler warnings.
|
|
|
3564
|
|
|
3565 In order to solve these problems, and maintain statement semantics, one
|
|
|
3566 should use the @code{do @{ ... @} while (0)} trick while trying to
|
|
|
3567 reference macro arguments exactly once using local variables.
|
|
|
3568
|
|
|
3569 Let's take a look at this poor macro definition:
|
|
|
3570
|
|
|
3571 @example
|
|
|
3572 #define MARK_OBJECT(obj) \
|
|
|
3573 if (!marked_p (obj)) mark_object (obj), did_mark = 1
|
|
|
3574 @end example
|
|
|
3575
|
|
|
3576 This macro evaluates its argument twice, and also fails if used like this:
|
|
|
3577 @example
|
|
|
3578 if (flag) MARK_OBJECT (obj); else do_something();
|
|
|
3579 @end example
|
|
|
3580
|
|
|
3581 A much better definition is
|
|
|
3582
|
|
|
3583 @example
|
|
|
3584 #define MARK_OBJECT(obj) do @{ \
|
|
|
3585 Lisp_Object mo_obj = (obj); \
|
|
|
3586 if (!marked_p (mo_obj)) \
|
|
|
3587 @{ \
|
|
|
3588 mark_object (mo_obj); \
|
|
|
3589 did_mark = 1; \
|
|
|
3590 @} \
|
|
|
3591 @} while (0)
|
|
|
3592 @end example
|
|
|
3593
|
|
|
3594 Notice the elimination of double evaluation by using the local variable
|
|
|
3595 with the obscure name. Writing safe and efficient macros requires great
|
|
|
3596 care. The one problem with macros that cannot be portably worked around
|
|
|
3597 is, since a C block has no value, a macro used as an expression rather
|
|
|
3598 than a statement cannot use the techniques just described to avoid
|
|
|
3599 multiple evaluation.
|
|
|
3600
|
|
462
|
3601 @cindex inline functions
|
|
442
|
3602 In most cases where a macro has function semantics, an inline function
|
|
|
3603 is a better implementation technique. Modern compiler optimizers tend
|
|
|
3604 to inline functions even if they have no @code{inline} keyword, and
|
|
|
3605 configure magic ensures that the @code{inline} keyword can be safely
|
|
|
3606 used as an additional compiler hint. Inline functions used in a single
|
|
|
3607 .c files are easy. The function must already be defined to be
|
|
|
3608 @code{static}. Just add another @code{inline} keyword to the
|
|
|
3609 definition.
|
|
|
3610
|
|
|
3611 @example
|
|
|
3612 inline static int
|
|
|
3613 heavily_used_small_function (int arg)
|
|
|
3614 @{
|
|
|
3615 ...
|
|
|
3616 @}
|
|
|
3617 @end example
|
|
|
3618
|
|
|
3619 Inline functions in header files are trickier, because we would like to
|
|
|
3620 make the following optimization if the function is @emph{not} inlined
|
|
|
3621 (for example, because we're compiling for debugging). We would like the
|
|
|
3622 function to be defined externally exactly once, and each calling
|
|
|
3623 translation unit would create an external reference to the function,
|
|
|
3624 instead of including a definition of the inline function in the object
|
|
|
3625 code of every translation unit that uses it. This optimization is
|
|
|
3626 currently only available for gcc. But you don't have to worry about the
|
|
|
3627 trickiness; just define your inline functions in header files using this
|
|
|
3628 pattern:
|
|
|
3629
|
|
|
3630 @example
|
|
|
3631 INLINE_HEADER int
|
|
|
3632 i_used_to_be_a_crufty_macro_but_look_at_me_now (int arg);
|
|
|
3633 INLINE_HEADER int
|
|
|
3634 i_used_to_be_a_crufty_macro_but_look_at_me_now (int arg)
|
|
|
3635 @{
|
|
|
3636 ...
|
|
|
3637 @}
|
|
|
3638 @end example
|
|
|
3639
|
|
|
3640 The declaration right before the definition is to prevent warnings when
|
|
|
3641 compiling with @code{gcc -Wmissing-declarations}. I consider issuing
|
|
|
3642 this warning for inline functions a gcc bug, but the gcc maintainers disagree.
|
|
|
3643
|
|
462
|
3644 @cindex inline functions, headers
|
|
|
3645 @cindex header files, inline functions
|
|
442
|
3646 Every header which contains inline functions, either directly by using
|
|
|
3647 @code{INLINE_HEADER} or indirectly by using @code{DECLARE_LRECORD} must
|
|
|
3648 be added to @file{inline.c}'s includes to make the optimization
|
|
|
3649 described above work. (Optimization note: if all INLINE_HEADER
|
|
|
3650 functions are in fact inlined in all translation units, then the linker
|
|
|
3651 can just discard @code{inline.o}, since it contains only unreferenced code).
|
|
|
3652
|
|
438
|
3653 To get started debugging XEmacs, take a look at the @file{.gdbinit} and
|
|
442
|
3654 @file{.dbxrc} files in the @file{src} directory. See the section in the
|
|
|
3655 XEmacs FAQ on How to Debug an XEmacs problem with a debugger.
|
|
428
|
3656
|
|
|
3657 After making source code changes, run @code{make check} to ensure that
|
|
442
|
3658 you haven't introduced any regressions. If you want to make xemacs more
|
|
|
3659 reliable, please improve the test suite in @file{tests/automated}.
|
|
|
3660
|
|
|
3661 Did you make sure you didn't introduce any new compiler warnings?
|
|
|
3662
|
|
|
3663 Before submitting a patch, please try compiling at least once with
|
|
|
3664
|
|
|
3665 @example
|
|
607
|
3666 configure --with-mule --use-union-type --error-checking=all
|
|
442
|
3667 @end example
|
|
428
|
3668
|
|
|
3669 Here are things to know when you create a new source file:
|
|
|
3670
|
|
|
3671 @itemize @bullet
|
|
|
3672 @item
|
|
|
3673 All @file{.c} files should @code{#include <config.h>} first. Almost all
|
|
|
3674 @file{.c} files should @code{#include "lisp.h"} second.
|
|
|
3675
|
|
|
3676 @item
|
|
|
3677 Generated header files should be included using the @code{#include <...>} syntax,
|
|
|
3678 not the @code{#include "..."} syntax. The generated headers are:
|
|
|
3679
|
|
442
|
3680 @file{config.h sheap-adjust.h paths.h Emacs.ad.h}
|
|
428
|
3681
|
|
|
3682 The basic rule is that you should assume builds using @code{--srcdir}
|
|
|
3683 and the @code{#include <...>} syntax needs to be used when the
|
|
|
3684 to-be-included generated file is in a potentially different directory
|
|
|
3685 @emph{at compile time}. The non-obvious C rule is that @code{#include "..."}
|
|
|
3686 means to search for the included file in the same directory as the
|
|
|
3687 including file, @emph{not} in the current directory.
|
|
|
3688
|
|
|
3689 @item
|
|
|
3690 Header files should @emph{not} include @code{<config.h>} and
|
|
|
3691 @code{"lisp.h"}. It is the responsibility of the @file{.c} files that
|
|
|
3692 use it to do so.
|
|
|
3693
|
|
|
3694 @end itemize
|
|
|
3695
|
|
462
|
3696 @cindex Lisp object types, creating
|
|
|
3697 @cindex creating Lisp object types
|
|
|
3698 @cindex object types, creating Lisp
|
|
442
|
3699 Here is a checklist of things to do when creating a new lisp object type
|
|
|
3700 named @var{foo}:
|
|
|
3701
|
|
|
3702 @enumerate
|
|
|
3703 @item
|
|
|
3704 create @var{foo}.h
|
|
|
3705 @item
|
|
|
3706 create @var{foo}.c
|
|
|
3707 @item
|
|
|
3708 add definitions of @code{syms_of_@var{foo}}, etc. to @file{@var{foo}.c}
|
|
|
3709 @item
|
|
|
3710 add declarations of @code{syms_of_@var{foo}}, etc. to @file{symsinit.h}
|
|
|
3711 @item
|
|
|
3712 add calls to @code{syms_of_@var{foo}}, etc. to @file{emacs.c}
|
|
|
3713 @item
|
|
|
3714 add definitions of macros like @code{CHECK_@var{FOO}} and
|
|
|
3715 @code{@var{FOO}P} to @file{@var{foo}.h}
|
|
|
3716 @item
|
|
|
3717 add the new type index to @code{enum lrecord_type}
|
|
|
3718 @item
|
|
|
3719 add a DEFINE_LRECORD_IMPLEMENTATION call to @file{@var{foo}.c}
|
|
|
3720 @item
|
|
|
3721 add an INIT_LRECORD_IMPLEMENTATION call to @code{syms_of_@var{foo}.c}
|
|
|
3722 @end enumerate
|
|
428
|
3723
|
|
965
|
3724 @node Regression Testing XEmacs, CVS Techniques, Rules When Writing New C Code, Top
|
|
|
3725 @chapter Regression Testing XEmacs
|
|
|
3726 @cindex testing, regression
|
|
|
3727
|
|
|
3728 The source directory @file{tests/automated} contains XEmacs' automated
|
|
|
3729 test suite. The usual way of running all the tests is running
|
|
|
3730 @code{make check} from the top-level build directory.
|
|
|
3731
|
|
|
3732 The test suite is unfinished and it's still lacking some essential
|
|
|
3733 features. It is nevertheless recommended that you run the tests to
|
|
|
3734 confirm that XEmacs behaves correctly.
|
|
|
3735
|
|
|
3736 If you want to run a specific test case, you can do it from the
|
|
|
3737 command-line like this:
|
|
|
3738
|
|
|
3739 @example
|
|
|
3740 $ xemacs -batch -l test-harness.elc -f batch-test-emacs TEST-FILE
|
|
967
|
3741 @end example
|
|
965
|
3742
|
|
1135
|
3743 If a test fails and you need more information, you can run the test
|
|
|
3744 suite interactively by loading @file{test-harness.el} into a running
|
|
|
3745 XEmacs and typing @kbd{M-x test-emacs-test-file RET <filename> RET}.
|
|
|
3746 You will see a log of passed and failed tests, which should allow you to
|
|
|
3747 investigate the source of the error and ultimately fix the bug. If you
|
|
|
3748 are not capable of, or don't have time for, debugging it yourself,
|
|
|
3749 please do report the failures using @kbd{M-x report-emacs-bug} or
|
|
|
3750 @kbd{M-x build-report}.
|
|
|
3751
|
|
|
3752 @deffn Command test-emacs-test-file file
|
|
|
3753 Runs the tests in @var{file}. @file{test-harness.el} must be loaded.
|
|
|
3754 Defines all the macros described in this node, and undefines them when
|
|
|
3755 done.
|
|
|
3756 @end deffn
|
|
965
|
3757
|
|
|
3758 Adding a new test file is trivial: just create a new file here and it
|
|
|
3759 will be run. There is no need to byte-compile any of the files in
|
|
|
3760 this directory---the test-harness will take care of any necessary
|
|
|
3761 byte-compilation.
|
|
|
3762
|
|
|
3763 Look at the existing test cases for the examples of coding test cases.
|
|
|
3764 It all boils down to your imagination and judicious use of the macros
|
|
|
3765 @code{Assert}, @code{Check-Error}, @code{Check-Error-Message}, and
|
|
1135
|
3766 @code{Check-Message}. Note that all of these macros are defined only
|
|
|
3767 for the duration of the test: they do not exist in the global
|
|
|
3768 environment.
|
|
|
3769
|
|
|
3770 @deffn Macro Assert expr
|
|
|
3771 Check that @var{expr} is non-nil at this point in the test.
|
|
|
3772 @end deffn
|
|
|
3773
|
|
|
3774 @deffn Macro Check-Error expected-error body
|
|
|
3775 Check that execution of @var{body} causes @var{expected-error} to be
|
|
|
3776 signaled. @var{body} is a @code{progn}-like body, and may contain
|
|
|
3777 several expressions. @var{expected-error} is a symbol defined as
|
|
|
3778 an error by @code{define-error}.
|
|
|
3779 @end deffn
|
|
|
3780
|
|
|
3781 @deffn Macro Check-Error-Message expected-error expected-error-regexp body
|
|
|
3782 Check that execution of @var{body} causes @var{expected-error} to be
|
|
|
3783 signaled, and generate a message matching @var{expected-error-regexp}.
|
|
|
3784 @var{body} is a @code{progn}-like body, and may contain several
|
|
|
3785 expressions. @var{expected-error} is a symbol defined as an error
|
|
|
3786 by @code{define-error}.
|
|
|
3787 @end deffn
|
|
|
3788
|
|
|
3789 @deffn Macro Check-Message expected-message body
|
|
|
3790 Check that execution of @var{body} causes @var{expected-message} to be
|
|
|
3791 generated (using @code{message} or a similar function). @var{body} is a
|
|
|
3792 @code{progn}-like body, and may contain several expressions.
|
|
|
3793 @end deffn
|
|
965
|
3794
|
|
|
3795 Here's a simple example checking case-sensitive and case-insensitive
|
|
|
3796 comparisons from @file{case-tests.el}.
|
|
|
3797
|
|
|
3798 @example
|
|
|
3799 (with-temp-buffer
|
|
|
3800 (insert "Test Buffer")
|
|
|
3801 (let ((case-fold-search t))
|
|
|
3802 (goto-char (point-min))
|
|
|
3803 (Assert (eq (search-forward "test buffer" nil t) 12))
|
|
|
3804 (goto-char (point-min))
|
|
|
3805 (Assert (eq (search-forward "Test buffer" nil t) 12))
|
|
|
3806 (goto-char (point-min))
|
|
|
3807 (Assert (eq (search-forward "Test Buffer" nil t) 12))
|
|
|
3808
|
|
|
3809 (setq case-fold-search nil)
|
|
|
3810 (goto-char (point-min))
|
|
|
3811 (Assert (not (search-forward "test buffer" nil t)))
|
|
|
3812 (goto-char (point-min))
|
|
|
3813 (Assert (not (search-forward "Test buffer" nil t)))
|
|
|
3814 (goto-char (point-min))
|
|
|
3815 (Assert (eq (search-forward "Test Buffer" nil t) 12))))
|
|
967
|
3816 @end example
|
|
965
|
3817
|
|
1135
|
3818 This example could be saved in a file in @file{tests/automated}, and it
|
|
|
3819 would constitute a complete test, automatically executed when you run
|
|
965
|
3820 @kbd{make check} after building XEmacs. More complex tests may require
|
|
|
3821 substantial temporary scaffolding to create the environment that elicits
|
|
1135
|
3822 the bugs, but the top-level @file{Makefile} and @file{test-harness.el}
|
|
|
3823 handle the running and collection of results from the @code{Assert},
|
|
965
|
3824 @code{Check-Error}, @code{Check-Error-Message}, and @code{Check-Message}
|
|
|
3825 macros.
|
|
|
3826
|
|
1135
|
3827 Don't suppress tests just because they're due to known bugs not yet
|
|
|
3828 fixed---use the @code{Known-Bug-Expect-Failure} wrapper macro to mark
|
|
|
3829 them.
|
|
|
3830
|
|
|
3831 @deffn Macro Known-Bug-Expect-Failure body
|
|
|
3832 Arrange for failing tests in @var{body} to generate messages prefixed
|
|
|
3833 with "KNOWN BUG:" instead of "FAIL:". @var{body} is a @code{progn}-like
|
|
|
3834 body, and may contain several tests.
|
|
|
3835 @end deffn
|
|
|
3836
|
|
|
3837 A lot of the tests we run push limits; suppress Ebola warning messages
|
|
|
3838 with the @code{Ignore-Ebola} wrapper macro.
|
|
|
3839
|
|
|
3840 @deffn Macro Ignore-Ebola body
|
|
|
3841 Suppress Ebola warning messages while running tests in @var{body}.
|
|
|
3842 @var{body} is a @code{progn}-like body, and may contain several tests.
|
|
|
3843 @end deffn
|
|
|
3844
|
|
|
3845 Both macros are defined temporarily within the test function. Simple
|
|
|
3846 examples:
|
|
|
3847
|
|
|
3848 @example
|
|
|
3849 ;; Apparently Ignore-Ebola is a solution with no problem to address.
|
|
|
3850 ;; There are no examples in 21.5, anyway.
|
|
|
3851
|
|
|
3852 ;; from regexp-tests.el
|
|
|
3853 (Known-Bug-Expect-Failure
|
|
|
3854 (Assert (not (string-match "\\b" "")))
|
|
|
3855 (Assert (not (string-match " \\b" " "))))
|
|
|
3856 @end example
|
|
|
3857
|
|
973
|
3858 In general, you should avoid using functionality from packages in your
|
|
|
3859 tests, because you can't be sure that everyone will have the required
|
|
|
3860 package. However, if you've got a test that works, by all means add it.
|
|
|
3861 Simply wrap the test in an appropriate test, add a notice that the test
|
|
1135
|
3862 was skipped, and update the @code{skipped-test-reasons} hashtable. The
|
|
|
3863 wrapper macro @code{Skip-Test-Unless} is provided to handle common
|
|
|
3864 cases.
|
|
|
3865
|
|
|
3866 @defvar skipped-test-reasons
|
|
|
3867 Hash table counting the number of times a particular reason is given for
|
|
|
3868 skipping tests. This is only defined within @code{test-emacs-test-file}.
|
|
|
3869 @end defvar
|
|
|
3870
|
|
|
3871 @deffn Macro Skip-Test-Unless prerequisite reason description body
|
|
|
3872 @var{prerequisite} is usually a feature test (@code{featurep},
|
|
|
3873 @code{boundp}, @code{fboundp}). @var{reason} is a string describing the
|
|
|
3874 prerequisite; it must be unique because it is used as a hash key in a
|
|
|
3875 table of reasons for skipping tests. @var{description} describes the
|
|
|
3876 tests being skipped, for the test result summary. @var{body} is a
|
|
|
3877 @code{progn}-like body, and may contain several tests.
|
|
|
3878 @end deffn
|
|
|
3879
|
|
|
3880 @code{Skip-Test-Unless} is defined temporarily within the test function.
|
|
|
3881 Here's an example of usage from @file{syntax-tests.el}:
|
|
973
|
3882
|
|
|
3883 @example
|
|
|
3884 ;; Test forward-comment at buffer boundaries
|
|
|
3885 (with-temp-buffer
|
|
|
3886 ;; try to use exactly what you need: featurep, boundp, fboundp
|
|
1135
|
3887 (Skip-Test-Unless (fboundp 'c-mode)
|
|
|
3888 "c-mode unavailable"
|
|
|
3889 "comment and parse-partial-sexp tests"
|
|
973
|
3890 ;; and here's the test code
|
|
|
3891 (c-mode)
|
|
|
3892 (insert "// comment\n")
|
|
|
3893 (forward-comment -2)
|
|
|
3894 (Assert (eq (point) (point-min)))
|
|
|
3895 (let ((point (point)))
|
|
|
3896 (insert "/* comment */")
|
|
|
3897 (goto-char point)
|
|
|
3898 (forward-comment 2)
|
|
|
3899 (Assert (eq (point) (point-max)))
|
|
|
3900 (parse-partial-sexp point (point-max)))))
|
|
|
3901 @end example
|
|
|
3902
|
|
1135
|
3903 @code{Skip-Test-Unless} is intended for use with features that are normally
|
|
973
|
3904 present in typical configurations. For truly optional features, or
|
|
|
3905 tests that apply to one of several alternative implementations (eg, to
|
|
|
3906 GTK widgets, but not Athena, Motif, MS Windows, or Carbon), simply
|
|
1135
|
3907 silently suppress the test if the feature is not available.
|
|
973
|
3908
|
|
1183
|
3909 Here are a few general hints for writing tests.
|
|
|
3910
|
|
|
3911 @enumerate
|
|
|
3912 @item
|
|
|
3913 Include related successful cases. Fixes often break something.
|
|
|
3914
|
|
|
3915 @item
|
|
|
3916 Use the Known-Bug-Expect-Failure macro to mark the cases you know
|
|
|
3917 are going to fail. We want to be able to distinguish between
|
|
|
3918 regressions and other unexpected failures, and cases that have
|
|
|
3919 been (partially) analyzed but not yet repaired.
|
|
|
3920
|
|
|
3921 @item
|
|
|
3922 Mark the bug with the date of report. An ``Unfixed since yyyy-mm-dd''
|
|
|
3923 gloss for Known-Bug-Expect-Failure is planned to further increase
|
|
|
3924 developer embarrassment (== incentive to fix the bug), but until then at
|
|
|
3925 least put a comment about the date so we can easily see when it was
|
|
|
3926 first reported.
|
|
|
3927
|
|
|
3928 @item
|
|
|
3929 It's a matter of your judgement, but you should often use generic tests
|
|
|
3930 (@emph{e.g.}, @code{eq}) instead of more specific tests (@code{=} for
|
|
|
3931 numbers) even though you know that arguments ``should'' be of correct
|
|
|
3932 type. That is, if the functions used can return generic objects
|
|
|
3933 (typically @code{nil}), as well as some more specific type that will be
|
|
|
3934 returned on success. We don't want failures of those assertions
|
|
|
3935 reported as ``other failures'' (a wrong-type-arg signal, rather than a
|
|
|
3936 null return), we want them reported as ``assertion failures.''
|
|
|
3937
|
|
|
3938 One example is a test that tests @code{(= (string-match this that) 0)},
|
|
|
3939 expecting a successful match. Now suppose @code{string-match} is broken
|
|
|
3940 such that the match fails. Then it will return @code{nil}, and @code{=}
|
|
|
3941 will signal ``wrong-type-argument, number-char-or-marker-p, nil'',
|
|
|
3942 generating an ``other failure'' in the report. But this should be
|
|
|
3943 reported as an assertion failure (the test failed in a foreseeable way),
|
|
|
3944 rather than something else (we don't know what happened because XEmacs
|
|
|
3945 is broken in a way that we weren't trying to test!)
|
|
|
3946 @end enumerate
|
|
|
3947
|
|
973
|
3948
|
|
965
|
3949 @node CVS Techniques, A Summary of the Various XEmacs Modules, Regression Testing XEmacs, Top
|
|
802
|
3950 @chapter CVS Techniques
|
|
|
3951 @cindex CVS techniques
|
|
|
3952
|
|
|
3953 @menu
|
|
|
3954 * Merging a Branch into the Trunk::
|
|
|
3955 @end menu
|
|
|
3956
|
|
|
3957 @node Merging a Branch into the Trunk
|
|
|
3958 @section Merging a Branch into the Trunk
|
|
|
3959 @cindex merging a branch into the trunk
|
|
|
3960
|
|
|
3961 @enumerate
|
|
|
3962 @item
|
|
|
3963 If you haven't already done a merge, you will be merging from the branch
|
|
|
3964 point; otherwise you'll be merging from the last merge point, which
|
|
|
3965 should be marked by a tag, e.g. @samp{last-sync-ben-mule-21-5}. In the
|
|
|
3966 former case, create the last-sync tag, e.g.
|
|
|
3967
|
|
|
3968 @example
|
|
|
3969 crw rtag -r ben-mule-21-5-bp last-sync-ben-mule-21-5 xemacs
|
|
|
3970 @end example
|
|
|
3971
|
|
|
3972 (You did create a branch point tag when you created the branch, didn't
|
|
|
3973 you?)
|
|
|
3974
|
|
|
3975 @item
|
|
|
3976 Check everything in on your branch.
|
|
|
3977
|
|
|
3978 @item
|
|
|
3979 Tag your branch with a pre-sync tag, e.g.
|
|
|
3980
|
|
|
3981 @example
|
|
|
3982 crw rtag -r ben-mule-21-5 ben-mule-21-5-pre-feb-20-2002-sync xemacs
|
|
|
3983 @end example
|
|
|
3984
|
|
|
3985 Note, you need to use rtag and specify a version with @samp{-r} (use
|
|
|
3986 @samp{-r HEAD} if necessary) so that removed files are handled correctly
|
|
|
3987 in some obscure cases. See section 4.8 of the CVS manual.
|
|
|
3988
|
|
|
3989 @item
|
|
|
3990 Tag the trunk so you have a stable place to merge up to in case people
|
|
|
3991 are asynchronously committing to the trunk, e.g.
|
|
|
3992
|
|
|
3993 @example
|
|
|
3994 crw rtag -r HEAD main-branch-ben-mule-21-5-syncpoint-feb-20-2002 xemacs
|
|
|
3995 crw rtag -F -r main-branch-ben-mule-21-5-syncpoint-feb-20-2002 next-sync-ben-mule-21-5 xemacs
|
|
|
3996 @end example
|
|
|
3997
|
|
|
3998 Use -F in the second case because the name might already exist, e.g. if
|
|
|
3999 you've already done a merge. We make two tags because one is a
|
|
|
4000 permanent mark indicating a syncpoint when merging, and the other is a
|
|
|
4001 symbolic tag to make other operations easier.
|
|
|
4002
|
|
|
4003 @item
|
|
|
4004 Make a backup of your source tree (not totally necessary but useful for
|
|
|
4005 reference and peace of mind): Move one level up from the top directory
|
|
|
4006 of your branch and do, e.g.
|
|
|
4007
|
|
|
4008 @example
|
|
|
4009 cp -a mule mule-backup-2-23-02
|
|
|
4010 @end example
|
|
|
4011
|
|
|
4012 @item
|
|
|
4013 Now, we're ready to merge! Make sure you're in the top directory of
|
|
|
4014 your branch and do, e.g.
|
|
|
4015
|
|
|
4016 @example
|
|
|
4017 cvs update -j last-sync-ben-mule-21-5 -j next-sync-ben-mule-21-5
|
|
|
4018 @end example
|
|
|
4019
|
|
|
4020 @item
|
|
|
4021 Fix all merge conflicts. Get the sucker to compile and run.
|
|
|
4022
|
|
|
4023 @item
|
|
|
4024 Tag your branch with a post-sync tag, e.g.
|
|
|
4025
|
|
|
4026 @example
|
|
|
4027 crw rtag -r ben-mule-21-5 ben-mule-21-5-post-feb-20-2002-sync xemacs
|
|
|
4028 @end example
|
|
|
4029
|
|
|
4030 @item
|
|
|
4031 Update the last-sync tag, e.g.
|
|
|
4032
|
|
|
4033 @example
|
|
|
4034 crw rtag -F -r next-sync-ben-mule-21-5 last-sync-ben-mule-21-5 xemacs
|
|
|
4035 @end example
|
|
|
4036 @end enumerate
|
|
|
4037
|
|
|
4038
|
|
|
4039 @node A Summary of the Various XEmacs Modules, Allocation of Objects in XEmacs Lisp, CVS Techniques, Top
|
|
428
|
4040 @chapter A Summary of the Various XEmacs Modules
|
|
462
|
4041 @cindex modules, a summary of the various XEmacs
|
|
428
|
4042
|
|
|
4043 This is accurate as of XEmacs 20.0.
|
|
|
4044
|
|
|
4045 @menu
|
|
|
4046 * Low-Level Modules::
|
|
|
4047 * Basic Lisp Modules::
|
|
|
4048 * Modules for Standard Editing Operations::
|
|
|
4049 * Editor-Level Control Flow Modules::
|
|
|
4050 * Modules for the Basic Displayable Lisp Objects::
|
|
|
4051 * Modules for other Display-Related Lisp Objects::
|
|
|
4052 * Modules for the Redisplay Mechanism::
|
|
|
4053 * Modules for Interfacing with the File System::
|
|
|
4054 * Modules for Other Aspects of the Lisp Interpreter and Object System::
|
|
|
4055 * Modules for Interfacing with the Operating System::
|
|
|
4056 * Modules for Interfacing with X Windows::
|
|
|
4057 * Modules for Internationalization::
|
|
965
|
4058 * Modules for Regression Testing::
|
|
428
|
4059 @end menu
|
|
|
4060
|
|
462
|
4061 @node Low-Level Modules
|
|
428
|
4062 @section Low-Level Modules
|
|
462
|
4063 @cindex low-level modules
|
|
|
4064 @cindex modules, low-level
|
|
428
|
4065
|
|
|
4066 @example
|
|
|
4067 config.h
|
|
|
4068 @end example
|
|
|
4069
|
|
|
4070 This is automatically generated from @file{config.h.in} based on the
|
|
|
4071 results of configure tests and user-selected optional features and
|
|
|
4072 contains preprocessor definitions specifying the nature of the
|
|
|
4073 environment in which XEmacs is being compiled.
|
|
|
4074
|
|
|
4075
|
|
|
4076
|
|
|
4077 @example
|
|
|
4078 paths.h
|
|
|
4079 @end example
|
|
|
4080
|
|
|
4081 This is automatically generated from @file{paths.h.in} based on supplied
|
|
|
4082 configure values, and allows for non-standard installed configurations
|
|
|
4083 of the XEmacs directories. It's currently broken, though.
|
|
|
4084
|
|
|
4085
|
|
|
4086
|
|
|
4087 @example
|
|
|
4088 emacs.c
|
|
|
4089 signal.c
|
|
|
4090 @end example
|
|
|
4091
|
|
|
4092 @file{emacs.c} contains @code{main()} and other code that performs the most
|
|
|
4093 basic environment initializations and handles shutting down the XEmacs
|
|
|
4094 process (this includes @code{kill-emacs}, the normal way that XEmacs is
|
|
|
4095 exited; @code{dump-emacs}, which is used during the build process to
|
|
|
4096 write out the XEmacs executable; @code{run-emacs-from-temacs}, which can
|
|
|
4097 be used to start XEmacs directly when temacs has finished loading all
|
|
|
4098 the Lisp code; and emergency code to handle crashes [XEmacs tries to
|
|
|
4099 auto-save all files before it crashes]).
|
|
|
4100
|
|
|
4101 Low-level code that directly interacts with the Unix signal mechanism,
|
|
|
4102 however, is in @file{signal.c}. Note that this code does not handle system
|
|
|
4103 dependencies in interfacing to signals; that is handled using the
|
|
|
4104 @file{syssignal.h} header file, described in section J below.
|
|
|
4105
|
|
|
4106
|
|
|
4107
|
|
|
4108 @example
|
|
|
4109 unexaix.c
|
|
|
4110 unexalpha.c
|
|
|
4111 unexapollo.c
|
|
|
4112 unexconvex.c
|
|
|
4113 unexec.c
|
|
|
4114 unexelf.c
|
|
|
4115 unexelfsgi.c
|
|
|
4116 unexencap.c
|
|
|
4117 unexenix.c
|
|
|
4118 unexfreebsd.c
|
|
|
4119 unexfx2800.c
|
|
|
4120 unexhp9k3.c
|
|
|
4121 unexhp9k800.c
|
|
|
4122 unexmips.c
|
|
|
4123 unexnext.c
|
|
|
4124 unexsol2.c
|
|
|
4125 unexsunos4.c
|
|
|
4126 @end example
|
|
|
4127
|
|
|
4128 These modules contain code dumping out the XEmacs executable on various
|
|
|
4129 different systems. (This process is highly machine-specific and
|
|
|
4130 requires intimate knowledge of the executable format and the memory map
|
|
|
4131 of the process.) Only one of these modules is actually used; this is
|
|
|
4132 chosen by @file{configure}.
|
|
|
4133
|
|
|
4134
|
|
|
4135
|
|
|
4136 @example
|
|
442
|
4137 ecrt0.c
|
|
428
|
4138 lastfile.c
|
|
|
4139 pre-crt0.c
|
|
|
4140 @end example
|
|
|
4141
|
|
|
4142 These modules are used in conjunction with the dump mechanism. On some
|
|
|
4143 systems, an alternative version of the C startup code (the actual code
|
|
|
4144 that receives control from the operating system when the process is
|
|
|
4145 started, and which calls @code{main()}) is required so that the dumping
|
|
|
4146 process works properly; @file{crt0.c} provides this.
|
|
|
4147
|
|
|
4148 @file{pre-crt0.c} and @file{lastfile.c} should be the very first and
|
|
|
4149 very last file linked, respectively. (Actually, this is not really true.
|
|
|
4150 @file{lastfile.c} should be after all Emacs modules whose initialized
|
|
|
4151 data should be made constant, and before all other Emacs files and all
|
|
|
4152 libraries. In particular, the allocation modules @file{gmalloc.c},
|
|
|
4153 @file{alloca.c}, etc. are normally placed past @file{lastfile.c}, and
|
|
|
4154 all of the files that implement Xt widget classes @emph{must} be placed
|
|
|
4155 after @file{lastfile.c} because they contain various structures that
|
|
|
4156 must be statically initialized and into which Xt writes at various
|
|
|
4157 times.) @file{pre-crt0.c} and @file{lastfile.c} contain exported symbols
|
|
|
4158 that are used to determine the start and end of XEmacs' initialized
|
|
|
4159 data space when dumping.
|
|
|
4160
|
|
|
4161
|
|
|
4162
|
|
|
4163 @example
|
|
|
4164 alloca.c
|
|
|
4165 free-hook.c
|
|
|
4166 getpagesize.h
|
|
|
4167 gmalloc.c
|
|
|
4168 malloc.c
|
|
|
4169 mem-limits.h
|
|
|
4170 ralloc.c
|
|
|
4171 vm-limit.c
|
|
|
4172 @end example
|
|
|
4173
|
|
|
4174 These handle basic C allocation of memory. @file{alloca.c} is an emulation of
|
|
|
4175 the stack allocation function @code{alloca()} on machines that lack
|
|
|
4176 this. (XEmacs makes extensive use of @code{alloca()} in its code.)
|
|
|
4177
|
|
|
4178 @file{gmalloc.c} and @file{malloc.c} are two implementations of the standard C
|
|
|
4179 functions @code{malloc()}, @code{realloc()} and @code{free()}. They are
|
|
|
4180 often used in place of the standard system-provided @code{malloc()}
|
|
|
4181 because they usually provide a much faster implementation, at the
|
|
|
4182 expense of additional memory use. @file{gmalloc.c} is a newer implementation
|
|
|
4183 that is much more memory-efficient for large allocations than @file{malloc.c},
|
|
|
4184 and should always be preferred if it works. (At one point, @file{gmalloc.c}
|
|
|
4185 didn't work on some systems where @file{malloc.c} worked; but this should be
|
|
|
4186 fixed now.)
|
|
|
4187
|
|
|
4188 @cindex relocating allocator
|
|
|
4189 @file{ralloc.c} is the @dfn{relocating allocator}. It provides
|
|
|
4190 functions similar to @code{malloc()}, @code{realloc()} and @code{free()}
|
|
|
4191 that allocate memory that can be dynamically relocated in memory. The
|
|
|
4192 advantage of this is that allocated memory can be shuffled around to
|
|
|
4193 place all the free memory at the end of the heap, and the heap can then
|
|
|
4194 be shrunk, releasing the memory back to the operating system. The use
|
|
|
4195 of this can be controlled with the configure option @code{--rel-alloc};
|
|
|
4196 if enabled, memory allocated for buffers will be relocatable, so that if
|
|
|
4197 a very large file is visited and the buffer is later killed, the memory
|
|
|
4198 can be released to the operating system. (The disadvantage of this
|
|
|
4199 mechanism is that it can be very slow. On systems with the
|
|
|
4200 @code{mmap()} system call, the XEmacs version of @file{ralloc.c} uses
|
|
|
4201 this to move memory around without actually having to block-copy it,
|
|
|
4202 which can speed things up; but it can still cause noticeable performance
|
|
|
4203 degradation.)
|
|
|
4204
|
|
1096
|
4205 On Linux systems using @samp{glibc 2}, these strategies are built in to
|
|
|
4206 the so-called ``Doug Lea malloc.'' See, for example, Doug Lea's home
|
|
|
4207 page, especially @uref{http://gee.cs.oswego.edu/dl/html/malloc.html,``A
|
|
|
4208 Memory Allocator''}. The source file, @file{malloc.c} (available at the
|
|
|
4209 same place) is copiously (and usefully!) commented.
|
|
|
4210 @uref{http://www.malloc.de/,Wolfram Gloger's home page} may also be
|
|
|
4211 useful.
|
|
|
4212
|
|
428
|
4213 @file{free-hook.c} contains some debugging functions for checking for invalid
|
|
|
4214 arguments to @code{free()}.
|
|
|
4215
|
|
|
4216 @file{vm-limit.c} contains some functions that warn the user when memory is
|
|
|
4217 getting low. These are callback functions that are called by @file{gmalloc.c}
|
|
|
4218 and @file{malloc.c} at appropriate times.
|
|
|
4219
|
|
|
4220 @file{getpagesize.h} provides a uniform interface for retrieving the size of a
|
|
|
4221 page in virtual memory. @file{mem-limits.h} provides a uniform interface for
|
|
|
4222 retrieving the total amount of available virtual memory. Both are
|
|
|
4223 similar in spirit to the @file{sys*.h} files described in section J, below.
|
|
|
4224
|
|
|
4225
|
|
|
4226 @example
|
|
|
4227 blocktype.c
|
|
|
4228 blocktype.h
|
|
|
4229 dynarr.c
|
|
|
4230 @end example
|
|
|
4231
|
|
|
4232 These implement a couple of basic C data types to facilitate memory
|
|
|
4233 allocation. The @code{Blocktype} type efficiently manages the
|
|
|
4234 allocation of fixed-size blocks by minimizing the number of times that
|
|
|
4235 @code{malloc()} and @code{free()} are called. It allocates memory in
|
|
|
4236 large chunks, subdivides the chunks into blocks of the proper size, and
|
|
|
4237 returns the blocks as requested. When blocks are freed, they are placed
|
|
|
4238 onto a linked list, so they can be efficiently reused. This data type
|
|
|
4239 is not much used in XEmacs currently, because it's a fairly new
|
|
|
4240 addition.
|
|
|
4241
|
|
|
4242 @cindex dynamic array
|
|
|
4243 The @code{Dynarr} type implements a @dfn{dynamic array}, which is
|
|
|
4244 similar to a standard C array but has no fixed limit on the number of
|
|
|
4245 elements it can contain. Dynamic arrays can hold elements of any type,
|
|
|
4246 and when you add a new element, the array automatically resizes itself
|
|
|
4247 if it isn't big enough. Dynarrs are extensively used in the redisplay
|
|
|
4248 mechanism.
|
|
|
4249
|
|
|
4250
|
|
|
4251
|
|
|
4252 @example
|
|
|
4253 inline.c
|
|
|
4254 @end example
|
|
|
4255
|
|
|
4256 This module is used in connection with inline functions (available in
|
|
|
4257 some compilers). Often, inline functions need to have a corresponding
|
|
|
4258 non-inline function that does the same thing. This module is where they
|
|
|
4259 reside. It contains no actual code, but defines some special flags that
|
|
|
4260 cause inline functions defined in header files to be rendered as actual
|
|
|
4261 functions. It then includes all header files that contain any inline
|
|
|
4262 function definitions, so that each one gets a real function equivalent.
|
|
|
4263
|
|
|
4264
|
|
|
4265
|
|
|
4266 @example
|
|
|
4267 debug.c
|
|
|
4268 debug.h
|
|
|
4269 @end example
|
|
|
4270
|
|
|
4271 These functions provide a system for doing internal consistency checks
|
|
|
4272 during code development. This system is not currently used; instead the
|
|
|
4273 simpler @code{assert()} macro is used along with the various checks
|
|
|
4274 provided by the @samp{--error-check-*} configuration options.
|
|
|
4275
|
|
|
4276
|
|
|
4277
|
|
|
4278 @example
|
|
|
4279 universe.h
|
|
|
4280 @end example
|
|
|
4281
|
|
|
4282 This is not currently used.
|
|
|
4283
|
|
|
4284
|
|
|
4285
|
|
462
|
4286 @node Basic Lisp Modules
|
|
428
|
4287 @section Basic Lisp Modules
|
|
462
|
4288 @cindex Lisp modules, basic
|
|
|
4289 @cindex modules, basic Lisp
|
|
428
|
4290
|
|
|
4291 @example
|
|
|
4292 lisp-disunion.h
|
|
|
4293 lisp-union.h
|
|
|
4294 lisp.h
|
|
|
4295 lrecord.h
|
|
|
4296 symsinit.h
|
|
|
4297 @end example
|
|
|
4298
|
|
|
4299 These are the basic header files for all XEmacs modules. Each module
|
|
|
4300 includes @file{lisp.h}, which brings the other header files in.
|
|
|
4301 @file{lisp.h} contains the definitions of the structures and extractor
|
|
|
4302 and constructor macros for the basic Lisp objects and various other
|
|
|
4303 basic definitions for the Lisp environment, as well as some
|
|
|
4304 general-purpose definitions (e.g. @code{min()} and @code{max()}).
|
|
|
4305 @file{lisp.h} includes either @file{lisp-disunion.h} or
|
|
|
4306 @file{lisp-union.h}, depending on whether @code{USE_UNION_TYPE} is
|
|
|
4307 defined. These files define the typedef of the Lisp object itself (as
|
|
|
4308 described above) and the low-level macros that hide the actual
|
|
|
4309 implementation of the Lisp object. All extractor and constructor macros
|
|
|
4310 for particular types of Lisp objects are defined in terms of these
|
|
|
4311 low-level macros.
|
|
|
4312
|
|
|
4313 As a general rule, all typedefs should go into the typedefs section of
|
|
|
4314 @file{lisp.h} rather than into a module-specific header file even if the
|
|
|
4315 structure is defined elsewhere. This allows function prototypes that
|
|
|
4316 use the typedef to be placed into other header files. Forward structure
|
|
|
4317 declarations (i.e. a simple declaration like @code{struct foo;} where
|
|
|
4318 the structure itself is defined elsewhere) should be placed into the
|
|
|
4319 typedefs section as necessary.
|
|
|
4320
|
|
|
4321 @file{lrecord.h} contains the basic structures and macros that implement
|
|
440
|
4322 all record-type Lisp objects---i.e. all objects whose type is a field
|
|
428
|
4323 in their C structure, which includes all objects except the few most
|
|
|
4324 basic ones.
|
|
|
4325
|
|
|
4326 @file{lisp.h} contains prototypes for most of the exported functions in
|
|
|
4327 the various modules. Lisp primitives defined using @code{DEFUN} that
|
|
|
4328 need to be called by C code should be declared using @code{EXFUN}.
|
|
|
4329 Other function prototypes should be placed either into the appropriate
|
|
|
4330 section of @code{lisp.h}, or into a module-specific header file,
|
|
|
4331 depending on how general-purpose the function is and whether it has
|
|
|
4332 special-purpose argument types requiring definitions not in
|
|
|
4333 @file{lisp.h}.) All initialization functions are prototyped in
|
|
|
4334 @file{symsinit.h}.
|
|
|
4335
|
|
|
4336
|
|
|
4337
|
|
|
4338 @example
|
|
|
4339 alloc.c
|
|
|
4340 @end example
|
|
|
4341
|
|
|
4342 The large module @file{alloc.c} implements all of the basic allocation and
|
|
|
4343 garbage collection for Lisp objects. The most commonly used Lisp
|
|
|
4344 objects are allocated in chunks, similar to the Blocktype data type
|
|
|
4345 described above; others are allocated in individually @code{malloc()}ed
|
|
|
4346 blocks. This module provides the foundation on which all other aspects
|
|
|
4347 of the Lisp environment sit, and is the first module initialized at
|
|
|
4348 startup.
|
|
|
4349
|
|
|
4350 Note that @file{alloc.c} provides a series of generic functions that are
|
|
|
4351 not dependent on any particular object type, and interfaces to
|
|
|
4352 particular types of objects using a standardized interface of
|
|
|
4353 type-specific methods. This scheme is a fundamental principle of
|
|
|
4354 object-oriented programming and is heavily used throughout XEmacs. The
|
|
|
4355 great advantage of this is that it allows for a clean separation of
|
|
440
|
4356 functionality into different modules---new classes of Lisp objects, new
|
|
428
|
4357 event interfaces, new device types, new stream interfaces, etc. can be
|
|
|
4358 added transparently without affecting code anywhere else in XEmacs.
|
|
|
4359 Because the different subsystems are divided into general and specific
|
|
|
4360 code, adding a new subtype within a subsystem will in general not
|
|
|
4361 require changes to the generic subsystem code or affect any of the other
|
|
|
4362 subtypes in the subsystem; this provides a great deal of robustness to
|
|
|
4363 the XEmacs code.
|
|
|
4364
|
|
|
4365
|
|
|
4366 @example
|
|
|
4367 eval.c
|
|
|
4368 backtrace.h
|
|
|
4369 @end example
|
|
|
4370
|
|
|
4371 This module contains all of the functions to handle the flow of control.
|
|
|
4372 This includes the mechanisms of defining functions, calling functions,
|
|
|
4373 traversing stack frames, and binding variables; the control primitives
|
|
|
4374 and other special forms such as @code{while}, @code{if}, @code{eval},
|
|
|
4375 @code{let}, @code{and}, @code{or}, @code{progn}, etc.; handling of
|
|
|
4376 non-local exits, unwind-protects, and exception handlers; entering the
|
|
|
4377 debugger; methods for the subr Lisp object type; etc. It does
|
|
|
4378 @emph{not} include the @code{read} function, the @code{print} function,
|
|
|
4379 or the handling of symbols and obarrays.
|
|
|
4380
|
|
|
4381 @file{backtrace.h} contains some structures related to stack frames and the
|
|
|
4382 flow of control.
|
|
|
4383
|
|
|
4384
|
|
|
4385
|
|
|
4386 @example
|
|
|
4387 lread.c
|
|
|
4388 @end example
|
|
|
4389
|
|
|
4390 This module implements the Lisp reader and the @code{read} function,
|
|
|
4391 which converts text into Lisp objects, according to the read syntax of
|
|
|
4392 the objects, as described above. This is similar to the parser that is
|
|
|
4393 a part of all compilers.
|
|
|
4394
|
|
|
4395
|
|
|
4396
|
|
|
4397 @example
|
|
|
4398 print.c
|
|
|
4399 @end example
|
|
|
4400
|
|
|
4401 This module implements the Lisp print mechanism and the @code{print}
|
|
|
4402 function and related functions. This is the inverse of the Lisp reader
|
|
|
4403 -- it converts Lisp objects to a printed, textual representation.
|
|
|
4404 (Hopefully something that can be read back in using @code{read} to get
|
|
|
4405 an equivalent object.)
|
|
|
4406
|
|
|
4407
|
|
|
4408
|
|
|
4409 @example
|
|
|
4410 general.c
|
|
|
4411 symbols.c
|
|
|
4412 symeval.h
|
|
|
4413 @end example
|
|
|
4414
|
|
|
4415 @file{symbols.c} implements the handling of symbols, obarrays, and
|
|
|
4416 retrieving the values of symbols. Much of the code is devoted to
|
|
|
4417 handling the special @dfn{symbol-value-magic} objects that define
|
|
440
|
4418 special types of variables---this includes buffer-local variables,
|
|
428
|
4419 variable aliases, variables that forward into C variables, etc. This
|
|
|
4420 module is initialized extremely early (right after @file{alloc.c}),
|
|
|
4421 because it is here that the basic symbols @code{t} and @code{nil} are
|
|
|
4422 created, and those symbols are used everywhere throughout XEmacs.
|
|
|
4423
|
|
|
4424 @file{symeval.h} contains the definitions of symbol structures and the
|
|
|
4425 @code{DEFVAR_LISP()} and related macros for declaring variables.
|
|
|
4426
|
|
|
4427
|
|
|
4428
|
|
|
4429 @example
|
|
|
4430 data.c
|
|
|
4431 floatfns.c
|
|
|
4432 fns.c
|
|
|
4433 @end example
|
|
|
4434
|
|
|
4435 These modules implement the methods and standard Lisp primitives for all
|
|
|
4436 the basic Lisp object types other than symbols (which are described
|
|
|
4437 above). @file{data.c} contains all the predicates (primitives that return
|
|
|
4438 whether an object is of a particular type); the integer arithmetic
|
|
|
4439 functions; and the basic accessor and mutator primitives for the various
|
|
|
4440 object types. @file{fns.c} contains all the standard predicates for working
|
|
|
4441 with sequences (where, abstractly speaking, a sequence is an ordered set
|
|
|
4442 of objects, and can be represented by a list, string, vector, or
|
|
|
4443 bit-vector); it also contains @code{equal}, perhaps on the grounds that
|
|
|
4444 bulk of the operation of @code{equal} is comparing sequences.
|
|
|
4445 @file{floatfns.c} contains methods and primitives for floats and floating-point
|
|
|
4446 arithmetic.
|
|
|
4447
|
|
|
4448
|
|
|
4449
|
|
|
4450 @example
|
|
|
4451 bytecode.c
|
|
|
4452 bytecode.h
|
|
|
4453 @end example
|
|
|
4454
|
|
|
4455 @file{bytecode.c} implements the byte-code interpreter and
|
|
|
4456 compiled-function objects, and @file{bytecode.h} contains associated
|
|
|
4457 structures. Note that the byte-code @emph{compiler} is written in Lisp.
|
|
|
4458
|
|
|
4459
|
|
|
4460
|
|
|
4461
|
|
462
|
4462 @node Modules for Standard Editing Operations
|
|
428
|
4463 @section Modules for Standard Editing Operations
|
|
462
|
4464 @cindex modules for standard editing operations
|
|
|
4465 @cindex editing operations, modules for standard
|
|
428
|
4466
|
|
|
4467 @example
|
|
|
4468 buffer.c
|
|
|
4469 buffer.h
|
|
|
4470 bufslots.h
|
|
|
4471 @end example
|
|
|
4472
|
|
|
4473 @file{buffer.c} implements the @dfn{buffer} Lisp object type. This
|
|
|
4474 includes functions that create and destroy buffers; retrieve buffers by
|
|
|
4475 name or by other properties; manipulate lists of buffers (remember that
|
|
|
4476 buffers are permanent objects and stored in various ordered lists);
|
|
|
4477 retrieve or change buffer properties; etc. It also contains the
|
|
|
4478 definitions of all the built-in buffer-local variables (which can be
|
|
|
4479 viewed as buffer properties). It does @emph{not} contain code to
|
|
|
4480 manipulate buffer-local variables (that's in @file{symbols.c}, described
|
|
|
4481 above); or code to manipulate the text in a buffer.
|
|
|
4482
|
|
|
4483 @file{buffer.h} defines the structures associated with a buffer and the various
|
|
|
4484 macros for retrieving text from a buffer and special buffer positions
|
|
|
4485 (e.g. @code{point}, the default location for text insertion). It also
|
|
|
4486 contains macros for working with buffer positions and converting between
|
|
|
4487 their representations as character offsets and as byte offsets (under
|
|
|
4488 MULE, they are different, because characters can be multi-byte). It is
|
|
|
4489 one of the largest header files.
|
|
|
4490
|
|
|
4491 @file{bufslots.h} defines the fields in the buffer structure that correspond to
|
|
|
4492 the built-in buffer-local variables. It is its own header file because
|
|
|
4493 it is included many times in @file{buffer.c}, as a way of iterating over all
|
|
|
4494 the built-in buffer-local variables.
|
|
|
4495
|
|
|
4496
|
|
|
4497
|
|
|
4498 @example
|
|
|
4499 insdel.c
|
|
|
4500 insdel.h
|
|
|
4501 @end example
|
|
|
4502
|
|
|
4503 @file{insdel.c} contains low-level functions for inserting and deleting text in
|
|
|
4504 a buffer, keeping track of changed regions for use by redisplay, and
|
|
|
4505 calling any before-change and after-change functions that may have been
|
|
|
4506 registered for the buffer. It also contains the actual functions that
|
|
|
4507 convert between byte offsets and character offsets.
|
|
|
4508
|
|
|
4509 @file{insdel.h} contains associated headers.
|
|
|
4510
|
|
|
4511
|
|
|
4512
|
|
|
4513 @example
|
|
|
4514 marker.c
|
|
|
4515 @end example
|
|
|
4516
|
|
|
4517 This module implements the @dfn{marker} Lisp object type, which
|
|
|
4518 conceptually is a pointer to a text position in a buffer that moves
|
|
|
4519 around as text is inserted and deleted, so as to remain in the same
|
|
|
4520 relative position. This module doesn't actually move the markers around
|
|
|
4521 -- that's handled in @file{insdel.c}. This module just creates them and
|
|
|
4522 implements the primitives for working with them. As markers are simple
|
|
|
4523 objects, this does not entail much.
|
|
|
4524
|
|
|
4525 Note that the standard arithmetic primitives (e.g. @code{+}) accept
|
|
|
4526 markers in place of integers and automatically substitute the value of
|
|
|
4527 @code{marker-position} for the marker, i.e. an integer describing the
|
|
|
4528 current buffer position of the marker.
|
|
|
4529
|
|
|
4530
|
|
|
4531
|
|
|
4532 @example
|
|
|
4533 extents.c
|
|
|
4534 extents.h
|
|
|
4535 @end example
|
|
|
4536
|
|
|
4537 This module implements the @dfn{extent} Lisp object type, which is like
|
|
|
4538 a marker that works over a range of text rather than a single position.
|
|
|
4539 Extents are also much more complex and powerful than markers and have a
|
|
|
4540 more efficient (and more algorithmically complex) implementation. The
|
|
|
4541 implementation is described in detail in comments in @file{extents.c}.
|
|
|
4542
|
|
|
4543 The code in @file{extents.c} works closely with @file{insdel.c} so that
|
|
|
4544 extents are properly moved around as text is inserted and deleted.
|
|
|
4545 There is also code in @file{extents.c} that provides information needed
|
|
|
4546 by the redisplay mechanism for efficient operation. (Remember that
|
|
|
4547 extents can have display properties that affect [sometimes drastically,
|
|
|
4548 as in the @code{invisible} property] the display of the text they
|
|
|
4549 cover.)
|
|
|
4550
|
|
|
4551
|
|
|
4552
|
|
|
4553 @example
|
|
|
4554 editfns.c
|
|
|
4555 @end example
|
|
|
4556
|
|
|
4557 @file{editfns.c} contains the standard Lisp primitives for working with
|
|
|
4558 a buffer's text, and calls the low-level functions in @file{insdel.c}.
|
|
|
4559 It also contains primitives for working with @code{point} (the default
|
|
|
4560 buffer insertion location).
|
|
|
4561
|
|
|
4562 @file{editfns.c} also contains functions for retrieving various
|
|
|
4563 characteristics from the external environment: the current time, the
|
|
|
4564 process ID of the running XEmacs process, the name of the user who ran
|
|
|
4565 this XEmacs process, etc. It's not clear why this code is in
|
|
|
4566 @file{editfns.c}.
|
|
|
4567
|
|
|
4568
|
|
|
4569
|
|
|
4570 @example
|
|
|
4571 callint.c
|
|
|
4572 cmds.c
|
|
|
4573 commands.h
|
|
|
4574 @end example
|
|
|
4575
|
|
|
4576 @cindex interactive
|
|
|
4577 These modules implement the basic @dfn{interactive} commands,
|
|
|
4578 i.e. user-callable functions. Commands, as opposed to other functions,
|
|
|
4579 have special ways of getting their parameters interactively (by querying
|
|
|
4580 the user), as opposed to having them passed in a normal function
|
|
|
4581 invocation. Many commands are not really meant to be called from other
|
|
|
4582 Lisp functions, because they modify global state in a way that's often
|
|
|
4583 undesired as part of other Lisp functions.
|
|
|
4584
|
|
|
4585 @file{callint.c} implements the mechanism for querying the user for
|
|
|
4586 parameters and calling interactive commands. The bulk of this module is
|
|
|
4587 code that parses the interactive spec that is supplied with an
|
|
|
4588 interactive command.
|
|
|
4589
|
|
|
4590 @file{cmds.c} implements the basic, most commonly used editing commands:
|
|
|
4591 commands to move around the current buffer and insert and delete
|
|
|
4592 characters. These commands are implemented using the Lisp primitives
|
|
|
4593 defined in @file{editfns.c}.
|
|
|
4594
|
|
|
4595 @file{commands.h} contains associated structure definitions and prototypes.
|
|
|
4596
|
|
|
4597
|
|
|
4598
|
|
|
4599 @example
|
|
|
4600 regex.c
|
|
|
4601 regex.h
|
|
|
4602 search.c
|
|
|
4603 @end example
|
|
|
4604
|
|
|
4605 @file{search.c} implements the Lisp primitives for searching for text in
|
|
|
4606 a buffer, and some of the low-level algorithms for doing this. In
|
|
|
4607 particular, the fast fixed-string Boyer-Moore search algorithm is
|
|
|
4608 implemented in @file{search.c}. The low-level algorithms for doing
|
|
|
4609 regular-expression searching, however, are implemented in @file{regex.c}
|
|
|
4610 and @file{regex.h}. These two modules are largely independent of
|
|
|
4611 XEmacs, and are similar to (and based upon) the regular-expression
|
|
|
4612 routines used in @file{grep} and other GNU utilities.
|
|
|
4613
|
|
|
4614
|
|
|
4615
|
|
|
4616 @example
|
|
|
4617 doprnt.c
|
|
|
4618 @end example
|
|
|
4619
|
|
|
4620 @file{doprnt.c} implements formatted-string processing, similar to
|
|
|
4621 @code{printf()} command in C.
|
|
|
4622
|
|
|
4623
|
|
|
4624
|
|
|
4625 @example
|
|
|
4626 undo.c
|
|
|
4627 @end example
|
|
|
4628
|
|
|
4629 This module implements the undo mechanism for tracking buffer changes.
|
|
|
4630 Most of this could be implemented in Lisp.
|
|
|
4631
|
|
|
4632
|
|
|
4633
|
|
462
|
4634 @node Editor-Level Control Flow Modules
|
|
428
|
4635 @section Editor-Level Control Flow Modules
|
|
462
|
4636 @cindex control flow modules, editor-level
|
|
|
4637 @cindex modules, editor-level control flow
|
|
428
|
4638
|
|
|
4639 @example
|
|
|
4640 event-Xt.c
|
|
442
|
4641 event-msw.c
|
|
428
|
4642 event-stream.c
|
|
|
4643 event-tty.c
|
|
442
|
4644 events-mod.h
|
|
|
4645 gpmevent.c
|
|
|
4646 gpmevent.h
|
|
428
|
4647 events.c
|
|
|
4648 events.h
|
|
|
4649 @end example
|
|
|
4650
|
|
|
4651 These implement the handling of events (user input and other system
|
|
|
4652 notifications).
|
|
|
4653
|
|
|
4654 @file{events.c} and @file{events.h} define the @dfn{event} Lisp object
|
|
|
4655 type and primitives for manipulating it.
|
|
|
4656
|
|
|
4657 @file{event-stream.c} implements the basic functions for working with
|
|
|
4658 event queues, dispatching an event by looking it up in relevant keymaps
|
|
|
4659 and such, and handling timeouts; this includes the primitives
|
|
|
4660 @code{next-event} and @code{dispatch-event}, as well as related
|
|
|
4661 primitives such as @code{sit-for}, @code{sleep-for}, and
|
|
|
4662 @code{accept-process-output}. (@file{event-stream.c} is one of the
|
|
|
4663 hairiest and trickiest modules in XEmacs. Beware! You can easily mess
|
|
|
4664 things up here.)
|
|
|
4665
|
|
|
4666 @file{event-Xt.c} and @file{event-tty.c} implement the low-level
|
|
|
4667 interfaces onto retrieving events from Xt (the X toolkit) and from TTY's
|
|
|
4668 (using @code{read()} and @code{select()}), respectively. The event
|
|
|
4669 interface enforces a clean separation between the specific code for
|
|
|
4670 interfacing with the operating system and the generic code for working
|
|
|
4671 with events, by defining an API of basic, low-level event methods;
|
|
|
4672 @file{event-Xt.c} and @file{event-tty.c} are two different
|
|
|
4673 implementations of this API. To add support for a new operating system
|
|
|
4674 (e.g. NeXTstep), one merely needs to provide another implementation of
|
|
|
4675 those API functions.
|
|
|
4676
|
|
|
4677 Note that the choice of whether to use @file{event-Xt.c} or
|
|
|
4678 @file{event-tty.c} is made at compile time! Or at the very latest, it
|
|
|
4679 is made at startup time. @file{event-Xt.c} handles events for
|
|
|
4680 @emph{both} X and TTY frames; @file{event-tty.c} is only used when X
|
|
|
4681 support is not compiled into XEmacs. The reason for this is that there
|
|
|
4682 is only one event loop in XEmacs: thus, it needs to be able to receive
|
|
|
4683 events from all different kinds of frames.
|
|
|
4684
|
|
|
4685
|
|
|
4686
|
|
|
4687 @example
|
|
|
4688 keymap.c
|
|
|
4689 keymap.h
|
|
|
4690 @end example
|
|
|
4691
|
|
|
4692 @file{keymap.c} and @file{keymap.h} define the @dfn{keymap} Lisp object
|
|
|
4693 type and associated methods and primitives. (Remember that keymaps are
|
|
|
4694 objects that associate event descriptions with functions to be called to
|
|
|
4695 ``execute'' those events; @code{dispatch-event} looks up events in the
|
|
|
4696 relevant keymaps.)
|
|
|
4697
|
|
|
4698
|
|
|
4699
|
|
|
4700 @example
|
|
442
|
4701 cmdloop.c
|
|
|
4702 @end example
|
|
|
4703
|
|
|
4704 @file{cmdloop.c} contains functions that implement the actual editor
|
|
440
|
4705 command loop---i.e. the event loop that cyclically retrieves and
|
|
428
|
4706 dispatches events. This code is also rather tricky, just like
|
|
|
4707 @file{event-stream.c}.
|
|
|
4708
|
|
|
4709
|
|
|
4710
|
|
|
4711 @example
|
|
|
4712 macros.c
|
|
|
4713 macros.h
|
|
|
4714 @end example
|
|
|
4715
|
|
|
4716 These two modules contain the basic code for defining keyboard macros.
|
|
|
4717 These functions don't actually do much; most of the code that handles keyboard
|
|
|
4718 macros is mixed in with the event-handling code in @file{event-stream.c}.
|
|
|
4719
|
|
|
4720
|
|
|
4721
|
|
|
4722 @example
|
|
|
4723 minibuf.c
|
|
|
4724 @end example
|
|
|
4725
|
|
|
4726 This contains some miscellaneous code related to the minibuffer (most of
|
|
|
4727 the minibuffer code was moved into Lisp by Richard Mlynarik). This
|
|
|
4728 includes the primitives for completion (although filename completion is
|
|
|
4729 in @file{dired.c}), the lowest-level interface to the minibuffer (if the
|
|
|
4730 command loop were cleaned up, this too could be in Lisp), and code for
|
|
|
4731 dealing with the echo area (this, too, was mostly moved into Lisp, and
|
|
|
4732 the only code remaining is code to call out to Lisp or provide simple
|
|
|
4733 bootstrapping implementations early in temacs, before the echo-area Lisp
|
|
|
4734 code is loaded).
|
|
|
4735
|
|
|
4736
|
|
|
4737
|
|
462
|
4738 @node Modules for the Basic Displayable Lisp Objects
|
|
428
|
4739 @section Modules for the Basic Displayable Lisp Objects
|
|
462
|
4740 @cindex modules for the basic displayable Lisp objects
|
|
|
4741 @cindex displayable Lisp objects, modules for the basic
|
|
|
4742 @cindex Lisp objects, modules for the basic displayable
|
|
|
4743 @cindex objects, modules for the basic displayable Lisp
|
|
428
|
4744
|
|
|
4745 @example
|
|
442
|
4746 console-msw.c
|
|
|
4747 console-msw.h
|
|
|
4748 console-stream.c
|
|
|
4749 console-stream.h
|
|
|
4750 console-tty.c
|
|
|
4751 console-tty.h
|
|
|
4752 console-x.c
|
|
|
4753 console-x.h
|
|
|
4754 console.c
|
|
|
4755 console.h
|
|
|
4756 @end example
|
|
|
4757
|
|
|
4758 These modules implement the @dfn{console} Lisp object type. A console
|
|
|
4759 contains multiple display devices, but only one keyboard and mouse.
|
|
|
4760 Most of the time, a console will contain exactly one device.
|
|
|
4761
|
|
|
4762 Consoles are the top of a lisp object inclusion hierarchy. Consoles
|
|
|
4763 contain devices, which contain frames, which contain windows.
|
|
|
4764
|
|
|
4765
|
|
|
4766
|
|
|
4767 @example
|
|
|
4768 device-msw.c
|
|
428
|
4769 device-tty.c
|
|
|
4770 device-x.c
|
|
|
4771 device.c
|
|
|
4772 device.h
|
|
|
4773 @end example
|
|
|
4774
|
|
|
4775 These modules implement the @dfn{device} Lisp object type. This
|
|
|
4776 abstracts a particular screen or connection on which frames are
|
|
|
4777 displayed. As with Lisp objects, event interfaces, and other
|
|
|
4778 subsystems, the device code is separated into a generic component that
|
|
|
4779 contains a standardized interface (in the form of a set of methods) onto
|
|
|
4780 particular device types.
|
|
|
4781
|
|
|
4782 The device subsystem defines all the methods and provides method
|
|
|
4783 services for not only device operations but also for the frame, window,
|
|
|
4784 menubar, scrollbar, toolbar, and other displayable-object subsystems.
|
|
|
4785 The reason for this is that all of these subsystems have the same
|
|
|
4786 subtypes (X, TTY, NeXTstep, Microsoft Windows, etc.) as devices do.
|
|
|
4787
|
|
|
4788
|
|
|
4789
|
|
|
4790 @example
|
|
442
|
4791 frame-msw.c
|
|
428
|
4792 frame-tty.c
|
|
|
4793 frame-x.c
|
|
|
4794 frame.c
|
|
|
4795 frame.h
|
|
|
4796 @end example
|
|
|
4797
|
|
|
4798 Each device contains one or more frames in which objects (e.g. text) are
|
|
|
4799 displayed. A frame corresponds to a window in the window system;
|
|
|
4800 usually this is a top-level window but it could potentially be one of a
|
|
|
4801 number of overlapping child windows within a top-level window, using the
|
|
|
4802 MDI (Multiple Document Interface) protocol in Microsoft Windows or a
|
|
|
4803 similar scheme.
|
|
|
4804
|
|
|
4805 The @file{frame-*} files implement the @dfn{frame} Lisp object type and
|
|
|
4806 provide the generic and device-type-specific operations on frames
|
|
|
4807 (e.g. raising, lowering, resizing, moving, etc.).
|
|
|
4808
|
|
|
4809
|
|
|
4810
|
|
|
4811 @example
|
|
|
4812 window.c
|
|
|
4813 window.h
|
|
|
4814 @end example
|
|
|
4815
|
|
|
4816 @cindex window (in Emacs)
|
|
|
4817 @cindex pane
|
|
|
4818 Each frame consists of one or more non-overlapping @dfn{windows} (better
|
|
|
4819 known as @dfn{panes} in standard window-system terminology) in which a
|
|
|
4820 buffer's text can be displayed. Windows can also have scrollbars
|
|
|
4821 displayed around their edges.
|
|
|
4822
|
|
|
4823 @file{window.c} and @file{window.h} implement the @dfn{window} Lisp
|
|
|
4824 object type and provide code to manage windows. Since windows have no
|
|
|
4825 associated resources in the window system (the window system knows only
|
|
|
4826 about the frame; no child windows or anything are used for XEmacs
|
|
|
4827 windows), there is no device-type-specific code here; all of that code
|
|
|
4828 is part of the redisplay mechanism or the code for particular object
|
|
|
4829 types such as scrollbars.
|
|
|
4830
|
|
|
4831
|
|
|
4832
|
|
462
|
4833 @node Modules for other Display-Related Lisp Objects
|
|
428
|
4834 @section Modules for other Display-Related Lisp Objects
|
|
462
|
4835 @cindex modules for other display-related Lisp objects
|
|
|
4836 @cindex display-related Lisp objects, modules for other
|
|
|
4837 @cindex Lisp objects, modules for other display-related
|
|
428
|
4838
|
|
|
4839 @example
|
|
|
4840 faces.c
|
|
|
4841 faces.h
|
|
|
4842 @end example
|
|
|
4843
|
|
|
4844
|
|
|
4845
|
|
|
4846 @example
|
|
|
4847 bitmaps.h
|
|
442
|
4848 glyphs-eimage.c
|
|
|
4849 glyphs-msw.c
|
|
|
4850 glyphs-msw.h
|
|
|
4851 glyphs-widget.c
|
|
428
|
4852 glyphs-x.c
|
|
|
4853 glyphs-x.h
|
|
|
4854 glyphs.c
|
|
|
4855 glyphs.h
|
|
|
4856 @end example
|
|
|
4857
|
|
|
4858
|
|
|
4859
|
|
|
4860 @example
|
|
442
|
4861 objects-msw.c
|
|
|
4862 objects-msw.h
|
|
428
|
4863 objects-tty.c
|
|
|
4864 objects-tty.h
|
|
|
4865 objects-x.c
|
|
|
4866 objects-x.h
|
|
|
4867 objects.c
|
|
|
4868 objects.h
|
|
|
4869 @end example
|
|
|
4870
|
|
|
4871
|
|
|
4872
|
|
|
4873 @example
|
|
442
|
4874 menubar-msw.c
|
|
|
4875 menubar-msw.h
|
|
428
|
4876 menubar-x.c
|
|
|
4877 menubar.c
|
|
442
|
4878 menubar.h
|
|
|
4879 @end example
|
|
|
4880
|
|
|
4881
|
|
|
4882
|
|
|
4883 @example
|
|
|
4884 scrollbar-msw.c
|
|
|
4885 scrollbar-msw.h
|
|
428
|
4886 scrollbar-x.c
|
|
|
4887 scrollbar-x.h
|
|
|
4888 scrollbar.c
|
|
|
4889 scrollbar.h
|
|
|
4890 @end example
|
|
|
4891
|
|
|
4892
|
|
|
4893
|
|
|
4894 @example
|
|
442
|
4895 toolbar-msw.c
|
|
428
|
4896 toolbar-x.c
|
|
|
4897 toolbar.c
|
|
|
4898 toolbar.h
|
|
|
4899 @end example
|
|
|
4900
|
|
|
4901
|
|
|
4902
|
|
|
4903 @example
|
|
|
4904 font-lock.c
|
|
|
4905 @end example
|
|
|
4906
|
|
440
|
4907 This file provides C support for syntax highlighting---i.e.
|
|
428
|
4908 highlighting different syntactic constructs of a source file in
|
|
|
4909 different colors, for easy reading. The C support is provided so that
|
|
|
4910 this is fast.
|
|
|
4911
|
|
|
4912
|
|
|
4913
|
|
|
4914 @example
|
|
|
4915 dgif_lib.c
|
|
|
4916 gif_err.c
|
|
|
4917 gif_lib.h
|
|
|
4918 gifalloc.c
|
|
|
4919 @end example
|
|
|
4920
|
|
|
4921 These modules decode GIF-format image files, for use with glyphs.
|
|
442
|
4922 These files were removed due to Unisys patent infringement concerns.
|
|
|
4923
|
|
|
4924
|
|
|
4925
|
|
462
|
4926 @node Modules for the Redisplay Mechanism
|
|
428
|
4927 @section Modules for the Redisplay Mechanism
|
|
462
|
4928 @cindex modules for the redisplay mechanism
|
|
|
4929 @cindex redisplay mechanism, modules for the
|
|
428
|
4930
|
|
|
4931 @example
|
|
|
4932 redisplay-output.c
|
|
442
|
4933 redisplay-msw.c
|
|
428
|
4934 redisplay-tty.c
|
|
|
4935 redisplay-x.c
|
|
|
4936 redisplay.c
|
|
|
4937 redisplay.h
|
|
|
4938 @end example
|
|
|
4939
|
|
|
4940 These files provide the redisplay mechanism. As with many other
|
|
|
4941 subsystems in XEmacs, there is a clean separation between the general
|
|
|
4942 and device-specific support.
|
|
|
4943
|
|
|
4944 @file{redisplay.c} contains the bulk of the redisplay engine. These
|
|
|
4945 functions update the redisplay structures (which describe how the screen
|
|
|
4946 is to appear) to reflect any changes made to the state of any
|
|
|
4947 displayable objects (buffer, frame, window, etc.) since the last time
|
|
|
4948 that redisplay was called. These functions are highly optimized to
|
|
|
4949 avoid doing more work than necessary (since redisplay is called
|
|
|
4950 extremely often and is potentially a huge time sink), and depend heavily
|
|
|
4951 on notifications from the objects themselves that changes have occurred,
|
|
|
4952 so that redisplay doesn't explicitly have to check each possible object.
|
|
|
4953 The redisplay mechanism also contains a great deal of caching to further
|
|
|
4954 speed things up; some of this caching is contained within the various
|
|
|
4955 displayable objects.
|
|
|
4956
|
|
|
4957 @file{redisplay-output.c} goes through the redisplay structures and converts
|
|
|
4958 them into calls to device-specific methods to actually output the screen
|
|
|
4959 changes.
|
|
|
4960
|
|
|
4961 @file{redisplay-x.c} and @file{redisplay-tty.c} are two implementations
|
|
|
4962 of these redisplay output methods, for X frames and TTY frames,
|
|
|
4963 respectively.
|
|
|
4964
|
|
|
4965
|
|
|
4966
|
|
|
4967 @example
|
|
|
4968 indent.c
|
|
|
4969 @end example
|
|
|
4970
|
|
|
4971 This module contains various functions and Lisp primitives for
|
|
|
4972 converting between buffer positions and screen positions. These
|
|
|
4973 functions call the redisplay mechanism to do most of the work, and then
|
|
|
4974 examine the redisplay structures to get the necessary information. This
|
|
|
4975 module needs work.
|
|
|
4976
|
|
|
4977
|
|
|
4978
|
|
|
4979 @example
|
|
|
4980 termcap.c
|
|
|
4981 terminfo.c
|
|
|
4982 tparam.c
|
|
|
4983 @end example
|
|
|
4984
|
|
|
4985 These files contain functions for working with the termcap (BSD-style)
|
|
|
4986 and terminfo (System V style) databases of terminal capabilities and
|
|
|
4987 escape sequences, used when XEmacs is displaying in a TTY.
|
|
|
4988
|
|
|
4989
|
|
|
4990
|
|
|
4991 @example
|
|
|
4992 cm.c
|
|
|
4993 cm.h
|
|
|
4994 @end example
|
|
|
4995
|
|
|
4996 These files provide some miscellaneous TTY-output functions and should
|
|
|
4997 probably be merged into @file{redisplay-tty.c}.
|
|
|
4998
|
|
|
4999
|
|
|
5000
|
|
462
|
5001 @node Modules for Interfacing with the File System
|
|
428
|
5002 @section Modules for Interfacing with the File System
|
|
462
|
5003 @cindex modules for interfacing with the file system
|
|
|
5004 @cindex interfacing with the file system, modules for
|
|
|
5005 @cindex file system, modules for interfacing with the
|
|
428
|
5006
|
|
|
5007 @example
|
|
|
5008 lstream.c
|
|
|
5009 lstream.h
|
|
|
5010 @end example
|
|
|
5011
|
|
|
5012 These modules implement the @dfn{stream} Lisp object type. This is an
|
|
|
5013 internal-only Lisp object that implements a generic buffering stream.
|
|
|
5014 The idea is to provide a uniform interface onto all sources and sinks of
|
|
|
5015 data, including file descriptors, stdio streams, chunks of memory, Lisp
|
|
|
5016 buffers, Lisp strings, etc. That way, I/O functions can be written to
|
|
|
5017 the stream interface and can transparently handle all possible sources
|
|
|
5018 and sinks. (For example, the @code{read} function can read data from a
|
|
|
5019 file, a string, a buffer, or even a function that is called repeatedly
|
|
|
5020 to return data, without worrying about where the data is coming from or
|
|
|
5021 what-size chunks it is returned in.)
|
|
|
5022
|
|
|
5023 @cindex lstream
|
|
|
5024 Note that in the C code, streams are called @dfn{lstreams} (for ``Lisp
|
|
|
5025 streams'') to distinguish them from other kinds of streams, e.g. stdio
|
|
|
5026 streams and C++ I/O streams.
|
|
|
5027
|
|
|
5028 Similar to other subsystems in XEmacs, lstreams are separated into
|
|
|
5029 generic functions and a set of methods for the different types of
|
|
|
5030 lstreams. @file{lstream.c} provides implementations of many different
|
|
442
|
5031 types of streams; others are provided, e.g., in @file{file-coding.c}.
|
|
428
|
5032
|
|
|
5033
|
|
|
5034
|
|
|
5035 @example
|
|
|
5036 fileio.c
|
|
|
5037 @end example
|
|
|
5038
|
|
|
5039 This implements the basic primitives for interfacing with the file
|
|
|
5040 system. This includes primitives for reading files into buffers,
|
|
|
5041 writing buffers into files, checking for the presence or accessibility
|
|
|
5042 of files, canonicalizing file names, etc. Note that these primitives
|
|
|
5043 are usually not invoked directly by the user: There is a great deal of
|
|
|
5044 higher-level Lisp code that implements the user commands such as
|
|
|
5045 @code{find-file} and @code{save-buffer}. This is similar to the
|
|
|
5046 distinction between the lower-level primitives in @file{editfns.c} and
|
|
|
5047 the higher-level user commands in @file{commands.c} and
|
|
|
5048 @file{simple.el}.
|
|
|
5049
|
|
|
5050
|
|
|
5051
|
|
|
5052 @example
|
|
|
5053 filelock.c
|
|
|
5054 @end example
|
|
|
5055
|
|
|
5056 This file provides functions for detecting clashes between different
|
|
|
5057 processes (e.g. XEmacs and some external process, or two different
|
|
|
5058 XEmacs processes) modifying the same file. (XEmacs can optionally use
|
|
|
5059 the @file{lock/} subdirectory to provide a form of ``locking'' between
|
|
|
5060 different XEmacs processes.) This module is also used by the low-level
|
|
|
5061 functions in @file{insdel.c} to ensure that, if the first modification
|
|
|
5062 is being made to a buffer whose corresponding file has been externally
|
|
|
5063 modified, the user is made aware of this so that the buffer can be
|
|
|
5064 synched up with the external changes if necessary.
|
|
|
5065
|
|
|
5066
|
|
|
5067 @example
|
|
|
5068 filemode.c
|
|
|
5069 @end example
|
|
|
5070
|
|
|
5071 This file provides some miscellaneous functions that construct a
|
|
|
5072 @samp{rwxr-xr-x}-type permissions string (as might appear in an
|
|
|
5073 @file{ls}-style directory listing) given the information returned by the
|
|
|
5074 @code{stat()} system call.
|
|
|
5075
|
|
|
5076
|
|
|
5077
|
|
|
5078 @example
|
|
|
5079 dired.c
|
|
|
5080 ndir.h
|
|
|
5081 @end example
|
|
|
5082
|
|
|
5083 These files implement the XEmacs interface to directory searching. This
|
|
|
5084 includes a number of primitives for determining the files in a directory
|
|
|
5085 and for doing filename completion. (Remember that generic completion is
|
|
|
5086 handled by a different mechanism, in @file{minibuf.c}.)
|
|
|
5087
|
|
|
5088 @file{ndir.h} is a header file used for the directory-searching
|
|
|
5089 emulation functions provided in @file{sysdep.c} (see section J below),
|
|
|
5090 for systems that don't provide any directory-searching functions. (On
|
|
|
5091 those systems, directories can be read directly as files, and parsed.)
|
|
|
5092
|
|
|
5093
|
|
|
5094
|
|
|
5095 @example
|
|
|
5096 realpath.c
|
|
|
5097 @end example
|
|
|
5098
|
|
|
5099 This file provides an implementation of the @code{realpath()} function
|
|
|
5100 for expanding symbolic links, on systems that don't implement it or have
|
|
|
5101 a broken implementation.
|
|
|
5102
|
|
|
5103
|
|
|
5104
|
|
462
|
5105 @node Modules for Other Aspects of the Lisp Interpreter and Object System
|
|
428
|
5106 @section Modules for Other Aspects of the Lisp Interpreter and Object System
|
|
462
|
5107 @cindex modules for other aspects of the Lisp interpreter and object system
|
|
|
5108 @cindex Lisp interpreter and object system, modules for other aspects of the
|
|
|
5109 @cindex interpreter and object system, modules for other aspects of the Lisp
|
|
|
5110 @cindex object system, modules for other aspects of the Lisp interpreter and
|
|
428
|
5111
|
|
|
5112 @example
|
|
|
5113 elhash.c
|
|
|
5114 elhash.h
|
|
|
5115 hash.c
|
|
|
5116 hash.h
|
|
|
5117 @end example
|
|
|
5118
|
|
|
5119 These files provide two implementations of hash tables. Files
|
|
|
5120 @file{hash.c} and @file{hash.h} provide a generic C implementation of
|
|
|
5121 hash tables which can stand independently of XEmacs. Files
|
|
|
5122 @file{elhash.c} and @file{elhash.h} provide a separate implementation of
|
|
|
5123 hash tables that can store only Lisp objects, and knows about Lispy
|
|
|
5124 things like garbage collection, and implement the @dfn{hash-table} Lisp
|
|
|
5125 object type.
|
|
|
5126
|
|
|
5127
|
|
|
5128 @example
|
|
|
5129 specifier.c
|
|
|
5130 specifier.h
|
|
|
5131 @end example
|
|
|
5132
|
|
|
5133 This module implements the @dfn{specifier} Lisp object type. This is
|
|
|
5134 primarily used for displayable properties, and allows for values that
|
|
|
5135 are specific to a particular buffer, window, frame, device, or device
|
|
|
5136 class, as well as a default value existing. This is used, for example,
|
|
|
5137 to control the height of the horizontal scrollbar or the appearance of
|
|
|
5138 the @code{default}, @code{bold}, or other faces. The specifier object
|
|
|
5139 consists of a number of specifications, each of which maps from a
|
|
|
5140 buffer, window, etc. to a value. The function @code{specifier-instance}
|
|
|
5141 looks up a value given a window (from which a buffer, frame, and device
|
|
|
5142 can be derived).
|
|
|
5143
|
|
|
5144
|
|
|
5145 @example
|
|
|
5146 chartab.c
|
|
|
5147 chartab.h
|
|
|
5148 casetab.c
|
|
|
5149 @end example
|
|
|
5150
|
|
|
5151 @file{chartab.c} and @file{chartab.h} implement the @dfn{char table}
|
|
|
5152 Lisp object type, which maps from characters or certain sorts of
|
|
|
5153 character ranges to Lisp objects. The implementation of this object
|
|
|
5154 type is optimized for the internal representation of characters. Char
|
|
|
5155 tables come in different types, which affect the allowed object types to
|
|
|
5156 which a character can be mapped and also dictate certain other
|
|
|
5157 properties of the char table.
|
|
|
5158
|
|
|
5159 @cindex case table
|
|
|
5160 @file{casetab.c} implements one sort of char table, the @dfn{case
|
|
|
5161 table}, which maps characters to other characters of possibly different
|
|
|
5162 case. These are used by XEmacs to implement case-changing primitives
|
|
|
5163 and to do case-insensitive searching.
|
|
|
5164
|
|
|
5165
|
|
|
5166
|
|
|
5167 @example
|
|
|
5168 syntax.c
|
|
|
5169 syntax.h
|
|
|
5170 @end example
|
|
|
5171
|
|
|
5172 @cindex scanner
|
|
|
5173 This module implements @dfn{syntax tables}, another sort of char table
|
|
|
5174 that maps characters into syntax classes that define the syntax of these
|
|
|
5175 characters (e.g. a parenthesis belongs to a class of @samp{open}
|
|
|
5176 characters that have corresponding @samp{close} characters and can be
|
|
|
5177 nested). This module also implements the Lisp @dfn{scanner}, a set of
|
|
|
5178 primitives for scanning over text based on syntax tables. This is used,
|
|
|
5179 for example, to find the matching parenthesis in a command such as
|
|
|
5180 @code{forward-sexp}, and by @file{font-lock.c} to locate quoted strings,
|
|
|
5181 comments, etc.
|
|
|
5182
|
|
1024
|
5183 @c #### Break this out into a separate node somewhere!
|
|
|
5184 Syntax codes are implemented as bitfields in an int. Bits 0-6 contain
|
|
|
5185 the syntax code itself, bit 7 is a special prefix flag used for Lisp,
|
|
|
5186 and bits 16-23 contain comment syntax flags. From the Lisp programmer's
|
|
|
5187 point of view, there are 11 flags: 2 styles X 2 characters X @{start,
|
|
|
5188 end@} flags for two-character comment delimiters, 2 style flags for
|
|
|
5189 one-character comment delimiters, and the prefix flag.
|
|
|
5190
|
|
|
5191 Internally, however, the characters used in multi-character delimiters
|
|
|
5192 will have non-comment-character syntax classes (@emph{e.g.}, the
|
|
|
5193 @samp{/} in C's @samp{/*} comment-start delimiter has ``punctuation''
|
|
|
5194 (here meaning ``operator-like'') class in C modes). Thus in a mixed
|
|
|
5195 comment style, such as C++'s @samp{//} to end of line, is represented by
|
|
|
5196 giving @samp{/} the ``punctuation'' class and the ``style b first
|
|
|
5197 character of start sequence'' and ``style b second character of start
|
|
|
5198 sequence'' flags. The fact that class is @emph{not} punctuation allows
|
|
|
5199 the syntax scanner to recognize that this is a multi-character
|
|
|
5200 delimiter. The @samp{newline} character is given (single-character)
|
|
|
5201 ``comment-end'' @emph{class} and the ``style b first character of end
|
|
|
5202 sequence'' @emph{flag}. The ``comment-end'' class allows the scanner to
|
|
|
5203 determine that no second character is needed to terminate the comment.
|
|
428
|
5204
|
|
|
5205
|
|
|
5206 @example
|
|
|
5207 casefiddle.c
|
|
|
5208 @end example
|
|
|
5209
|
|
|
5210 This module implements various Lisp primitives for upcasing, downcasing
|
|
|
5211 and capitalizing strings or regions of buffers.
|
|
|
5212
|
|
|
5213
|
|
|
5214
|
|
|
5215 @example
|
|
|
5216 rangetab.c
|
|
|
5217 @end example
|
|
|
5218
|
|
|
5219 This module implements the @dfn{range table} Lisp object type, which
|
|
|
5220 provides for a mapping from ranges of integers to arbitrary Lisp
|
|
|
5221 objects.
|
|
|
5222
|
|
|
5223
|
|
|
5224
|
|
|
5225 @example
|
|
|
5226 opaque.c
|
|
|
5227 opaque.h
|
|
|
5228 @end example
|
|
|
5229
|
|
|
5230 This module implements the @dfn{opaque} Lisp object type, an
|
|
|
5231 internal-only Lisp object that encapsulates an arbitrary block of memory
|
|
|
5232 so that it can be managed by the Lisp allocation system. To create an
|
|
|
5233 opaque object, you call @code{make_opaque()}, passing a pointer to a
|
|
|
5234 block of memory. An object is created that is big enough to hold the
|
|
|
5235 memory, which is copied into the object's storage. The object will then
|
|
|
5236 stick around as long as you keep pointers to it, after which it will be
|
|
|
5237 automatically reclaimed.
|
|
|
5238
|
|
|
5239 @cindex mark method
|
|
|
5240 Opaque objects can also have an arbitrary @dfn{mark method} associated
|
|
|
5241 with them, in case the block of memory contains other Lisp objects that
|
|
|
5242 need to be marked for garbage-collection purposes. (If you need other
|
|
|
5243 object methods, such as a finalize method, you should just go ahead and
|
|
440
|
5244 create a new Lisp object type---it's not hard.)
|
|
428
|
5245
|
|
|
5246
|
|
|
5247
|
|
|
5248 @example
|
|
|
5249 abbrev.c
|
|
|
5250 @end example
|
|
|
5251
|
|
|
5252 This function provides a few primitives for doing dynamic abbreviation
|
|
|
5253 expansion. In XEmacs, most of the code for this has been moved into
|
|
|
5254 Lisp. Some C code remains for speed and because the primitive
|
|
|
5255 @code{self-insert-command} (which is executed for all self-inserting
|
|
|
5256 characters) hooks into the abbrev mechanism. (@code{self-insert-command}
|
|
|
5257 is itself in C only for speed.)
|
|
|
5258
|
|
|
5259
|
|
|
5260
|
|
|
5261 @example
|
|
|
5262 doc.c
|
|
|
5263 @end example
|
|
|
5264
|
|
|
5265 This function provides primitives for retrieving the documentation
|
|
|
5266 strings of functions and variables. These documentation strings contain
|
|
|
5267 certain special markers that get dynamically expanded (e.g. a
|
|
|
5268 reverse-lookup is performed on some named functions to retrieve their
|
|
|
5269 current key bindings). Some documentation strings (in particular, for
|
|
|
5270 the built-in primitives and pre-loaded Lisp functions) are stored
|
|
|
5271 externally in a file @file{DOC} in the @file{lib-src/} directory and
|
|
|
5272 need to be fetched from that file. (Part of the build stage involves
|
|
|
5273 building this file, and another part involves constructing an index for
|
|
|
5274 this file and embedding it into the executable, so that the functions in
|
|
|
5275 @file{doc.c} do not have to search the entire @file{DOC} file to find
|
|
|
5276 the appropriate documentation string.)
|
|
|
5277
|
|
|
5278
|
|
|
5279
|
|
|
5280 @example
|
|
|
5281 md5.c
|
|
|
5282 @end example
|
|
|
5283
|
|
|
5284 This function provides a Lisp primitive that implements the MD5 secure
|
|
|
5285 hashing scheme, used to create a large hash value of a string of data such that
|
|
|
5286 the data cannot be derived from the hash value. This is used for
|
|
|
5287 various security applications on the Internet.
|
|
|
5288
|
|
|
5289
|
|
|
5290
|
|
|
5291
|
|
462
|
5292 @node Modules for Interfacing with the Operating System
|
|
428
|
5293 @section Modules for Interfacing with the Operating System
|
|
462
|
5294 @cindex modules for interfacing with the operating system
|
|
|
5295 @cindex interfacing with the operating system, modules for
|
|
|
5296 @cindex operating system, modules for interfacing with the
|
|
428
|
5297
|
|
|
5298 @example
|
|
|
5299 callproc.c
|
|
|
5300 process.c
|
|
|
5301 process.h
|
|
|
5302 @end example
|
|
|
5303
|
|
|
5304 These modules allow XEmacs to spawn and communicate with subprocesses
|
|
|
5305 and network connections.
|
|
|
5306
|
|
|
5307 @cindex synchronous subprocesses
|
|
|
5308 @cindex subprocesses, synchronous
|
|
|
5309 @file{callproc.c} implements (through the @code{call-process}
|
|
|
5310 primitive) what are called @dfn{synchronous subprocesses}. This means
|
|
|
5311 that XEmacs runs a program, waits till it's done, and retrieves its
|
|
|
5312 output. A typical example might be calling the @file{ls} program to get
|
|
|
5313 a directory listing.
|
|
|
5314
|
|
|
5315 @cindex asynchronous subprocesses
|
|
|
5316 @cindex subprocesses, asynchronous
|
|
|
5317 @file{process.c} and @file{process.h} implement @dfn{asynchronous
|
|
|
5318 subprocesses}. This means that XEmacs starts a program and then
|
|
|
5319 continues normally, not waiting for the process to finish. Data can be
|
|
|
5320 sent to the process or retrieved from it as it's running. This is used
|
|
|
5321 for the @code{shell} command (which provides a front end onto a shell
|
|
|
5322 program such as @file{csh}), the mail and news readers implemented in
|
|
|
5323 XEmacs, etc. The result of calling @code{start-process} to start a
|
|
|
5324 subprocess is a process object, a particular kind of object used to
|
|
|
5325 communicate with the subprocess. You can send data to the process by
|
|
|
5326 passing the process object and the data to @code{send-process}, and you
|
|
|
5327 can specify what happens to data retrieved from the process by setting
|
|
|
5328 properties of the process object. (When the process sends data, XEmacs
|
|
|
5329 receives a process event, which says that there is data ready. When
|
|
|
5330 @code{dispatch-event} is called on this event, it reads the data from
|
|
|
5331 the process and does something with it, as specified by the process
|
|
|
5332 object's properties. Typically, this means inserting the data into a
|
|
|
5333 buffer or calling a function.) Another property of the process object is
|
|
|
5334 called the @dfn{sentinel}, which is a function that is called when the
|
|
|
5335 process terminates.
|
|
|
5336
|
|
|
5337 @cindex network connections
|
|
|
5338 Process objects are also used for network connections (connections to a
|
|
|
5339 process running on another machine). Network connections are started
|
|
|
5340 with @code{open-network-stream} but otherwise work just like
|
|
|
5341 subprocesses.
|
|
|
5342
|
|
|
5343
|
|
|
5344
|
|
|
5345 @example
|
|
|
5346 sysdep.c
|
|
|
5347 sysdep.h
|
|
|
5348 @end example
|
|
|
5349
|
|
|
5350 These modules implement most of the low-level, messy operating-system
|
|
|
5351 interface code. This includes various device control (ioctl) operations
|
|
|
5352 for file descriptors, TTY's, pseudo-terminals, etc. (usually this stuff
|
|
|
5353 is fairly system-dependent; thus the name of this module), and emulation
|
|
|
5354 of standard library functions and system calls on systems that don't
|
|
|
5355 provide them or have broken versions.
|
|
|
5356
|
|
|
5357
|
|
|
5358
|
|
|
5359 @example
|
|
|
5360 sysdir.h
|
|
|
5361 sysfile.h
|
|
|
5362 sysfloat.h
|
|
|
5363 sysproc.h
|
|
|
5364 syspwd.h
|
|
|
5365 syssignal.h
|
|
|
5366 systime.h
|
|
|
5367 systty.h
|
|
|
5368 syswait.h
|
|
|
5369 @end example
|
|
|
5370
|
|
|
5371 These header files provide consistent interfaces onto system-dependent
|
|
|
5372 header files and system calls. The idea is that, instead of including a
|
|
|
5373 standard header file like @file{<sys/param.h>} (which may or may not
|
|
|
5374 exist on various systems) or having to worry about whether all system
|
|
|
5375 provide a particular preprocessor constant, or having to deal with the
|
|
|
5376 four different paradigms for manipulating signals, you just include the
|
|
|
5377 appropriate @file{sys*.h} header file, which includes all the right
|
|
|
5378 system header files, defines and missing preprocessor constants,
|
|
|
5379 provides a uniform interface onto system calls, etc.
|
|
|
5380
|
|
|
5381 @file{sysdir.h} provides a uniform interface onto directory-querying
|
|
|
5382 functions. (In some cases, this is in conjunction with emulation
|
|
|
5383 functions in @file{sysdep.c}.)
|
|
|
5384
|
|
|
5385 @file{sysfile.h} includes all the necessary header files for standard
|
|
|
5386 system calls (e.g. @code{read()}), ensures that all necessary
|
|
|
5387 @code{open()} and @code{stat()} preprocessor constants are defined, and
|
|
|
5388 possibly (usually) substitutes sugared versions of @code{read()},
|
|
|
5389 @code{write()}, etc. that automatically restart interrupted I/O
|
|
|
5390 operations.
|
|
|
5391
|
|
|
5392 @file{sysfloat.h} includes the necessary header files for floating-point
|
|
|
5393 operations.
|
|
|
5394
|
|
|
5395 @file{sysproc.h} includes the necessary header files for calling
|
|
|
5396 @code{select()}, @code{fork()}, @code{execve()}, socket operations, and
|
|
|
5397 the like, and ensures that the @code{FD_*()} macros for descriptor-set
|
|
|
5398 manipulations are available.
|
|
|
5399
|
|
|
5400 @file{syspwd.h} includes the necessary header files for obtaining
|
|
|
5401 information from @file{/etc/passwd} (the functions are emulated under
|
|
|
5402 VMS).
|
|
|
5403
|
|
|
5404 @file{syssignal.h} includes the necessary header files for
|
|
|
5405 signal-handling and provides a uniform interface onto the different
|
|
|
5406 signal-handling and signal-blocking paradigms.
|
|
|
5407
|
|
|
5408 @file{systime.h} includes the necessary header files and provides
|
|
|
5409 uniform interfaces for retrieving the time of day, setting file
|
|
|
5410 access/modification times, getting the amount of time used by the XEmacs
|
|
|
5411 process, etc.
|
|
|
5412
|
|
|
5413 @file{systty.h} buffers against the infinitude of different ways of
|
|
|
5414 controlling TTY's.
|
|
|
5415
|
|
|
5416 @file{syswait.h} provides a uniform way of retrieving the exit status
|
|
|
5417 from a @code{wait()}ed-on process (some systems use a union, others use
|
|
|
5418 an int).
|
|
|
5419
|
|
|
5420
|
|
|
5421
|
|
|
5422 @example
|
|
|
5423 hpplay.c
|
|
|
5424 libsst.c
|
|
|
5425 libsst.h
|
|
|
5426 libst.h
|
|
|
5427 linuxplay.c
|
|
|
5428 nas.c
|
|
|
5429 sgiplay.c
|
|
|
5430 sound.c
|
|
|
5431 sunplay.c
|
|
|
5432 @end example
|
|
|
5433
|
|
|
5434 These files implement the ability to play various sounds on some types
|
|
|
5435 of computers. You have to configure your XEmacs with sound support in
|
|
|
5436 order to get this capability.
|
|
|
5437
|
|
|
5438 @file{sound.c} provides the generic interface. It implements various
|
|
|
5439 Lisp primitives and variables that let you specify which sounds should
|
|
|
5440 be played in certain conditions. (The conditions are identified by
|
|
|
5441 symbols, which are passed to @code{ding} to make a sound. Various
|
|
|
5442 standard functions call this function at certain times; if sound support
|
|
|
5443 does not exist, a simple beep results.
|
|
|
5444
|
|
|
5445 @cindex native sound
|
|
|
5446 @cindex sound, native
|
|
|
5447 @file{sgiplay.c}, @file{sunplay.c}, @file{hpplay.c}, and
|
|
|
5448 @file{linuxplay.c} interface to the machine's speaker for various
|
|
|
5449 different kind of machines. This is called @dfn{native} sound.
|
|
|
5450
|
|
|
5451 @cindex sound, network
|
|
|
5452 @cindex network sound
|
|
|
5453 @cindex NAS
|
|
|
5454 @file{nas.c} interfaces to a computer somewhere else on the network
|
|
|
5455 using the NAS (Network Audio Server) protocol, playing sounds on that
|
|
|
5456 machine. This allows you to run XEmacs on a remote machine, with its
|
|
|
5457 display set to your local machine, and have the sounds be made on your
|
|
|
5458 local machine, provided that you have a NAS server running on your local
|
|
|
5459 machine.
|
|
|
5460
|
|
|
5461 @file{libsst.c}, @file{libsst.h}, and @file{libst.h} provide some
|
|
|
5462 additional functions for playing sound on a Sun SPARC but are not
|
|
|
5463 currently in use.
|
|
|
5464
|
|
|
5465
|
|
|
5466
|
|
|
5467 @example
|
|
|
5468 tooltalk.c
|
|
|
5469 tooltalk.h
|
|
|
5470 @end example
|
|
|
5471
|
|
|
5472 These two modules implement an interface to the ToolTalk protocol, which
|
|
|
5473 is an interprocess communication protocol implemented on some versions
|
|
|
5474 of Unix. ToolTalk is a high-level protocol that allows processes to
|
|
|
5475 register themselves as providers of particular services; other processes
|
|
|
5476 can then request a service without knowing or caring exactly who is
|
|
|
5477 providing the service. It is similar in spirit to the DDE protocol
|
|
|
5478 provided under Microsoft Windows. ToolTalk is a part of the new CDE
|
|
|
5479 (Common Desktop Environment) specification and is used to connect the
|
|
|
5480 parts of the SPARCWorks development environment.
|
|
|
5481
|
|
|
5482
|
|
|
5483
|
|
|
5484 @example
|
|
|
5485 getloadavg.c
|
|
|
5486 @end example
|
|
|
5487
|
|
|
5488 This module provides the ability to retrieve the system's current load
|
|
|
5489 average. (The way to do this is highly system-specific, unfortunately,
|
|
|
5490 and requires a lot of special-case code.)
|
|
|
5491
|
|
|
5492
|
|
|
5493
|
|
|
5494 @example
|
|
|
5495 sunpro.c
|
|
|
5496 @end example
|
|
|
5497
|
|
|
5498 This module provides a small amount of code used internally at Sun to
|
|
|
5499 keep statistics on the usage of XEmacs.
|
|
|
5500
|
|
|
5501
|
|
|
5502
|
|
|
5503 @example
|
|
|
5504 broken-sun.h
|
|
|
5505 strcmp.c
|
|
|
5506 strcpy.c
|
|
|
5507 sunOS-fix.c
|
|
|
5508 @end example
|
|
|
5509
|
|
|
5510 These files provide replacement functions and prototypes to fix numerous
|
|
|
5511 bugs in early releases of SunOS 4.1.
|
|
|
5512
|
|
|
5513
|
|
|
5514
|
|
|
5515 @example
|
|
|
5516 hftctl.c
|
|
|
5517 @end example
|
|
|
5518
|
|
|
5519 This module provides some terminal-control code necessary on versions of
|
|
|
5520 AIX prior to 4.1.
|
|
|
5521
|
|
|
5522
|
|
|
5523
|
|
462
|
5524 @node Modules for Interfacing with X Windows
|
|
428
|
5525 @section Modules for Interfacing with X Windows
|
|
462
|
5526 @cindex modules for interfacing with X Windows
|
|
|
5527 @cindex interfacing with X Windows, modules for
|
|
|
5528 @cindex X Windows, modules for interfacing with
|
|
428
|
5529
|
|
|
5530 @example
|
|
|
5531 Emacs.ad.h
|
|
|
5532 @end example
|
|
|
5533
|
|
|
5534 A file generated from @file{Emacs.ad}, which contains XEmacs-supplied
|
|
|
5535 fallback resources (so that XEmacs has pretty defaults).
|
|
|
5536
|
|
|
5537
|
|
|
5538
|
|
|
5539 @example
|
|
|
5540 EmacsFrame.c
|
|
|
5541 EmacsFrame.h
|
|
|
5542 EmacsFrameP.h
|
|
|
5543 @end example
|
|
|
5544
|
|
|
5545 These modules implement an Xt widget class that encapsulates a frame.
|
|
|
5546 This is for ease in integrating with Xt. The EmacsFrame widget covers
|
|
|
5547 the entire X window except for the menubar; the scrollbars are
|
|
|
5548 positioned on top of the EmacsFrame widget.
|
|
|
5549
|
|
|
5550 @strong{Warning:} Abandon hope, all ye who enter here. This code took
|
|
|
5551 an ungodly amount of time to get right, and is likely to fall apart
|
|
|
5552 mercilessly at the slightest change. Such is life under Xt.
|
|
|
5553
|
|
|
5554
|
|
|
5555
|
|
|
5556 @example
|
|
|
5557 EmacsManager.c
|
|
|
5558 EmacsManager.h
|
|
|
5559 EmacsManagerP.h
|
|
|
5560 @end example
|
|
|
5561
|
|
|
5562 These modules implement a simple Xt manager (i.e. composite) widget
|
|
|
5563 class that simply lets its children set whatever geometry they want.
|
|
|
5564 It's amazing that Xt doesn't provide this standardly, but on second
|
|
|
5565 thought, it makes sense, considering how amazingly broken Xt is.
|
|
|
5566
|
|
|
5567
|
|
|
5568 @example
|
|
|
5569 EmacsShell-sub.c
|
|
|
5570 EmacsShell.c
|
|
|
5571 EmacsShell.h
|
|
|
5572 EmacsShellP.h
|
|
|
5573 @end example
|
|
|
5574
|
|
|
5575 These modules implement two Xt widget classes that are subclasses of
|
|
|
5576 the TopLevelShell and TransientShell classes. This is necessary to deal
|
|
|
5577 with more brokenness that Xt has sadistically thrust onto the backs of
|
|
|
5578 developers.
|
|
|
5579
|
|
|
5580
|
|
|
5581
|
|
|
5582 @example
|
|
|
5583 xgccache.c
|
|
|
5584 xgccache.h
|
|
|
5585 @end example
|
|
|
5586
|
|
|
5587 These modules provide functions for maintenance and caching of GC's
|
|
|
5588 (graphics contexts) under the X Window System. This code is junky and
|
|
|
5589 needs to be rewritten.
|
|
|
5590
|
|
|
5591
|
|
|
5592
|
|
|
5593 @example
|
|
442
|
5594 select-msw.c
|
|
|
5595 select-x.c
|
|
|
5596 select.c
|
|
|
5597 select.h
|
|
428
|
5598 @end example
|
|
|
5599
|
|
|
5600 @cindex selections
|
|
|
5601 This module provides an interface to the X Window System's concept of
|
|
|
5602 @dfn{selections}, the standard way for X applications to communicate
|
|
|
5603 with each other.
|
|
|
5604
|
|
|
5605
|
|
|
5606
|
|
|
5607 @example
|
|
|
5608 xintrinsic.h
|
|
|
5609 xintrinsicp.h
|
|
|
5610 xmmanagerp.h
|
|
|
5611 xmprimitivep.h
|
|
|
5612 @end example
|
|
|
5613
|
|
|
5614 These header files are similar in spirit to the @file{sys*.h} files and buffer
|
|
|
5615 against different implementations of Xt and Motif.
|
|
|
5616
|
|
|
5617 @itemize @bullet
|
|
|
5618 @item
|
|
|
5619 @file{xintrinsic.h} should be included in place of @file{<Intrinsic.h>}.
|
|
|
5620 @item
|
|
|
5621 @file{xintrinsicp.h} should be included in place of @file{<IntrinsicP.h>}.
|
|
|
5622 @item
|
|
|
5623 @file{xmmanagerp.h} should be included in place of @file{<XmManagerP.h>}.
|
|
|
5624 @item
|
|
|
5625 @file{xmprimitivep.h} should be included in place of @file{<XmPrimitiveP.h>}.
|
|
|
5626 @end itemize
|
|
|
5627
|
|
|
5628
|
|
|
5629
|
|
|
5630 @example
|
|
|
5631 xmu.c
|
|
|
5632 xmu.h
|
|
|
5633 @end example
|
|
|
5634
|
|
|
5635 These files provide an emulation of the Xmu library for those systems
|
|
|
5636 (i.e. HPUX) that don't provide it as a standard part of X.
|
|
|
5637
|
|
|
5638
|
|
|
5639
|
|
|
5640 @example
|
|
|
5641 ExternalClient-Xlib.c
|
|
|
5642 ExternalClient.c
|
|
|
5643 ExternalClient.h
|
|
|
5644 ExternalClientP.h
|
|
|
5645 ExternalShell.c
|
|
|
5646 ExternalShell.h
|
|
|
5647 ExternalShellP.h
|
|
|
5648 extw-Xlib.c
|
|
|
5649 extw-Xlib.h
|
|
|
5650 extw-Xt.c
|
|
|
5651 extw-Xt.h
|
|
|
5652 @end example
|
|
|
5653
|
|
|
5654 @cindex external widget
|
|
|
5655 These files provide the @dfn{external widget} interface, which allows an
|
|
|
5656 XEmacs frame to appear as a widget in another application. To do this,
|
|
|
5657 you have to configure with @samp{--external-widget}.
|
|
|
5658
|
|
|
5659 @file{ExternalShell*} provides the server (XEmacs) side of the
|
|
|
5660 connection.
|
|
|
5661
|
|
|
5662 @file{ExternalClient*} provides the client (other application) side of
|
|
|
5663 the connection. These files are not compiled into XEmacs but are
|
|
|
5664 compiled into libraries that are then linked into your application.
|
|
|
5665
|
|
|
5666 @file{extw-*} is common code that is used for both the client and server.
|
|
|
5667
|
|
|
5668 Don't touch this code; something is liable to break if you do.
|
|
|
5669
|
|
|
5670
|
|
|
5671
|
|
462
|
5672 @node Modules for Internationalization
|
|
428
|
5673 @section Modules for Internationalization
|
|
462
|
5674 @cindex modules for internationalization
|
|
|
5675 @cindex internationalization, modules for
|
|
428
|
5676
|
|
|
5677 @example
|
|
|
5678 mule-canna.c
|
|
|
5679 mule-ccl.c
|
|
|
5680 mule-charset.c
|
|
|
5681 mule-charset.h
|
|
442
|
5682 file-coding.c
|
|
|
5683 file-coding.h
|
|
428
|
5684 mule-mcpath.c
|
|
|
5685 mule-mcpath.h
|
|
|
5686 mule-wnnfns.c
|
|
|
5687 mule.c
|
|
|
5688 @end example
|
|
|
5689
|
|
|
5690 These files implement the MULE (Asian-language) support. Note that MULE
|
|
|
5691 actually provides a general interface for all sorts of languages, not
|
|
|
5692 just Asian languages (although they are generally the most complicated
|
|
|
5693 to support). This code is still in beta.
|
|
|
5694
|
|
442
|
5695 @file{mule-charset.*} and @file{file-coding.*} provide the heart of the
|
|
428
|
5696 XEmacs MULE support. @file{mule-charset.*} implements the @dfn{charset}
|
|
|
5697 Lisp object type, which encapsulates a character set (an ordered one- or
|
|
|
5698 two-dimensional set of characters, such as US ASCII or JISX0208 Japanese
|
|
|
5699 Kanji).
|
|
|
5700
|
|
442
|
5701 @file{file-coding.*} implements the @dfn{coding-system} Lisp object
|
|
428
|
5702 type, which encapsulates a method of converting between different
|
|
|
5703 encodings. An encoding is a representation of a stream of characters,
|
|
|
5704 possibly from multiple character sets, using a stream of bytes or words,
|
|
|
5705 and defines (e.g.) which escape sequences are used to specify particular
|
|
|
5706 character sets, how the indices for a character are converted into bytes
|
|
|
5707 (sometimes this involves setting the high bit; sometimes complicated
|
|
|
5708 rearranging of the values takes place, as in the Shift-JIS encoding),
|
|
|
5709 etc.
|
|
|
5710
|
|
|
5711 @file{mule-ccl.c} provides the CCL (Code Conversion Language)
|
|
|
5712 interpreter. CCL is similar in spirit to Lisp byte code and is used to
|
|
|
5713 implement converters for custom encodings.
|
|
|
5714
|
|
|
5715 @file{mule-canna.c} and @file{mule-wnnfns.c} implement interfaces to
|
|
|
5716 external programs used to implement the Canna and WNN input methods,
|
|
|
5717 respectively. This is currently in beta.
|
|
|
5718
|
|
|
5719 @file{mule-mcpath.c} provides some functions to allow for pathnames
|
|
|
5720 containing extended characters. This code is fragmentary, obsolete, and
|
|
1738
|
5721 completely non-working. Instead, @code{pathname-coding-system} is used
|
|
428
|
5722 to specify conversions of names of files and directories. The standard
|
|
|
5723 C I/O functions like @samp{open()} are wrapped so that conversion occurs
|
|
|
5724 automatically.
|
|
|
5725
|
|
|
5726 @file{mule.c} provides a few miscellaneous things that should probably
|
|
|
5727 be elsewhere.
|
|
|
5728
|
|
|
5729
|
|
|
5730
|
|
|
5731 @example
|
|
|
5732 intl.c
|
|
|
5733 @end example
|
|
|
5734
|
|
|
5735 This provides some miscellaneous internationalization code for
|
|
|
5736 implementing message translation and interfacing to the Ximp input
|
|
|
5737 method. None of this code is currently working.
|
|
|
5738
|
|
|
5739
|
|
|
5740
|
|
|
5741 @example
|
|
|
5742 iso-wide.h
|
|
|
5743 @end example
|
|
|
5744
|
|
|
5745 This contains leftover code from an earlier implementation of
|
|
|
5746 Asian-language support, and is not currently used.
|
|
|
5747
|
|
|
5748
|
|
|
5749
|
|
|
5750
|
|
965
|
5751 @node Modules for Regression Testing
|
|
|
5752 @section Modules for Regression Testing
|
|
|
5753 @cindex modules for regression testing
|
|
|
5754 @cindex regression testing, modules for
|
|
|
5755
|
|
|
5756 @example
|
|
|
5757 test-harness.el
|
|
|
5758 base64-tests.el
|
|
|
5759 byte-compiler-tests.el
|
|
|
5760 case-tests.el
|
|
|
5761 ccl-tests.el
|
|
|
5762 c-tests.el
|
|
|
5763 database-tests.el
|
|
|
5764 extent-tests.el
|
|
|
5765 hash-table-tests.el
|
|
|
5766 lisp-tests.el
|
|
|
5767 md5-tests.el
|
|
|
5768 mule-tests.el
|
|
|
5769 regexp-tests.el
|
|
|
5770 symbol-tests.el
|
|
|
5771 syntax-tests.el
|
|
|
5772 @end example
|
|
|
5773
|
|
|
5774 @file{test-harness.el} defines the macros @code{Assert},
|
|
|
5775 @code{Check-Error}, @code{Check-Error-Message}, and
|
|
|
5776 @code{Check-Message}. The other files are test files, testing various
|
|
|
5777 XEmacs facilities.
|
|
|
5778
|
|
|
5779
|
|
|
5780
|
|
442
|
5781 @node Allocation of Objects in XEmacs Lisp, Dumping, A Summary of the Various XEmacs Modules, Top
|
|
428
|
5782 @chapter Allocation of Objects in XEmacs Lisp
|
|
462
|
5783 @cindex allocation of objects in XEmacs Lisp
|
|
|
5784 @cindex objects in XEmacs Lisp, allocation of
|
|
|
5785 @cindex Lisp objects, allocation of in XEmacs
|
|
428
|
5786
|
|
|
5787 @menu
|
|
|
5788 * Introduction to Allocation::
|
|
|
5789 * Garbage Collection::
|
|
|
5790 * GCPROing::
|
|
|
5791 * Garbage Collection - Step by Step::
|
|
|
5792 * Integers and Characters::
|
|
|
5793 * Allocation from Frob Blocks::
|
|
|
5794 * lrecords::
|
|
|
5795 * Low-level allocation::
|
|
|
5796 * Cons::
|
|
|
5797 * Vector::
|
|
|
5798 * Bit Vector::
|
|
|
5799 * Symbol::
|
|
|
5800 * Marker::
|
|
|
5801 * String::
|
|
|
5802 * Compiled Function::
|
|
|
5803 @end menu
|
|
|
5804
|
|
462
|
5805 @node Introduction to Allocation
|
|
428
|
5806 @section Introduction to Allocation
|
|
462
|
5807 @cindex allocation, introduction to
|
|
428
|
5808
|
|
|
5809 Emacs Lisp, like all Lisps, has garbage collection. This means that
|
|
|
5810 the programmer never has to explicitly free (destroy) an object; it
|
|
|
5811 happens automatically when the object becomes inaccessible. Most
|
|
|
5812 experts agree that garbage collection is a necessity in a modern,
|
|
|
5813 high-level language. Its omission from C stems from the fact that C was
|
|
|
5814 originally designed to be a nice abstract layer on top of assembly
|
|
|
5815 language, for writing kernels and basic system utilities rather than
|
|
|
5816 large applications.
|
|
|
5817
|
|
|
5818 Lisp objects can be created by any of a number of Lisp primitives.
|
|
|
5819 Most object types have one or a small number of basic primitives
|
|
|
5820 for creating objects. For conses, the basic primitive is @code{cons};
|
|
|
5821 for vectors, the primitives are @code{make-vector} and @code{vector}; for
|
|
|
5822 symbols, the primitives are @code{make-symbol} and @code{intern}; etc.
|
|
|
5823 Some Lisp objects, especially those that are primarily used internally,
|
|
|
5824 have no corresponding Lisp primitives. Every Lisp object, though,
|
|
|
5825 has at least one C primitive for creating it.
|
|
|
5826
|
|
442
|
5827 Recall from section (VII) that a Lisp object, as stored in a 32-bit or
|
|
|
5828 64-bit word, has a few tag bits, and a ``value'' that occupies the
|
|
|
5829 remainder of the bits. We can separate the different Lisp object types
|
|
|
5830 into three broad categories:
|
|
428
|
5831
|
|
|
5832 @itemize @bullet
|
|
|
5833 @item
|
|
|
5834 (a) Those for whom the value directly represents the contents of the
|
|
|
5835 Lisp object. Only two types are in this category: integers and
|
|
|
5836 characters. No special allocation or garbage collection is necessary
|
|
|
5837 for such objects. Lisp objects of these types do not need to be
|
|
|
5838 @code{GCPRO}ed.
|
|
|
5839 @end itemize
|
|
|
5840
|
|
442
|
5841 In the remaining two categories, the type is stored in the object
|
|
|
5842 itself. The tag for all such objects is the generic @dfn{lrecord}
|
|
|
5843 (Lisp_Type_Record) tag. The first bytes of the object's structure are an
|
|
|
5844 integer (actually a char) characterising the object's type and some
|
|
|
5845 flags, in particular the mark bit used for garbage collection. A
|
|
|
5846 structure describing the type is accessible thru the
|
|
|
5847 lrecord_implementation_table indexed with said integer. This structure
|
|
|
5848 includes the method pointers and a pointer to a string naming the type.
|
|
428
|
5849
|
|
|
5850 @itemize @bullet
|
|
|
5851 @item
|
|
442
|
5852 (b) Those lrecords that are allocated in frob blocks (see above). This
|
|
428
|
5853 includes the objects that are most common and relatively small, and
|
|
442
|
5854 includes conses, strings, subrs, floats, compiled functions, symbols,
|
|
428
|
5855 extents, events, and markers. With the cleanup of frob blocks done in
|
|
|
5856 19.12, it's not terribly hard to add more objects to this category, but
|
|
442
|
5857 it's a bit trickier than adding an object type to type (c) (esp. if the
|
|
428
|
5858 object needs a finalization method), and is not likely to save much
|
|
|
5859 space unless the object is small and there are many of them. (In fact,
|
|
|
5860 if there are very few of them, it might actually waste space.)
|
|
|
5861 @item
|
|
442
|
5862 (c) Those lrecords that are individually @code{malloc()}ed. These are
|
|
428
|
5863 called @dfn{lcrecords}. All other types are in this category. Adding a
|
|
|
5864 new type to this category is comparatively easy, and all types added
|
|
|
5865 since 19.8 (when the current allocation scheme was devised, by Richard
|
|
|
5866 Mlynarik), with the exception of the character type, have been in this
|
|
|
5867 category.
|
|
|
5868 @end itemize
|
|
|
5869
|
|
|
5870 Note that bit vectors are a bit of a special case. They are
|
|
442
|
5871 simple lrecords as in category (b), but are individually @code{malloc()}ed
|
|
428
|
5872 like vectors. You can basically view them as exactly like vectors
|
|
|
5873 except that their type is stored in lrecord fashion rather than
|
|
|
5874 in directly-tagged fashion.
|
|
|
5875
|
|
442
|
5876
|
|
462
|
5877 @node Garbage Collection
|
|
428
|
5878 @section Garbage Collection
|
|
|
5879 @cindex garbage collection
|
|
|
5880
|
|
|
5881 @cindex mark and sweep
|
|
|
5882 Garbage collection is simple in theory but tricky to implement.
|
|
|
5883 Emacs Lisp uses the oldest garbage collection method, called
|
|
|
5884 @dfn{mark and sweep}. Garbage collection begins by starting with
|
|
|
5885 all accessible locations (i.e. all variables and other slots where
|
|
|
5886 Lisp objects might occur) and recursively traversing all objects
|
|
|
5887 accessible from those slots, marking each one that is found.
|
|
|
5888 We then go through all of memory and free each object that is
|
|
|
5889 not marked, and unmarking each object that is marked. Note
|
|
|
5890 that ``all of memory'' means all currently allocated objects.
|
|
|
5891 Traversing all these objects means traversing all frob blocks,
|
|
|
5892 all vectors (which are chained in one big list), and all
|
|
|
5893 lcrecords (which are likewise chained).
|
|
|
5894
|
|
442
|
5895 Garbage collection can be invoked explicitly by calling
|
|
|
5896 @code{garbage-collect} but is also called automatically by @code{eval},
|
|
|
5897 once a certain amount of memory has been allocated since the last
|
|
|
5898 garbage collection (according to @code{gc-cons-threshold}).
|
|
|
5899
|
|
|
5900
|
|
462
|
5901 @node GCPROing
|
|
428
|
5902 @section @code{GCPRO}ing
|
|
462
|
5903 @cindex @code{GCPRO}ing
|
|
|
5904 @cindex garbage collection protection
|
|
|
5905 @cindex protection, garbage collection
|
|
428
|
5906
|
|
|
5907 @code{GCPRO}ing is one of the ugliest and trickiest parts of Emacs
|
|
|
5908 internals. The basic idea is that whenever garbage collection
|
|
|
5909 occurs, all in-use objects must be reachable somehow or
|
|
|
5910 other from one of the roots of accessibility. The roots
|
|
|
5911 of accessibility are:
|
|
|
5912
|
|
|
5913 @enumerate
|
|
|
5914 @item
|
|
442
|
5915 All objects that have been @code{staticpro()}d or
|
|
|
5916 @code{staticpro_nodump()}ed. This is used for any global C variables
|
|
|
5917 that hold Lisp objects. A call to @code{staticpro()} happens implicitly
|
|
|
5918 as a result of any symbols declared with @code{defsymbol()} and any
|
|
|
5919 variables declared with @code{DEFVAR_FOO()}. You need to explicitly
|
|
|
5920 call @code{staticpro()} (in the @code{vars_of_foo()} method of a module)
|
|
|
5921 for other global C variables holding Lisp objects. (This typically
|
|
|
5922 includes internal lists and such things.). Use
|
|
|
5923 @code{staticpro_nodump()} only in the rare cases when you do not want
|
|
|
5924 the pointed variable to be saved at dump time but rather recompute it at
|
|
|
5925 startup.
|
|
428
|
5926
|
|
|
5927 Note that @code{obarray} is one of the @code{staticpro()}d things.
|
|
|
5928 Therefore, all functions and variables get marked through this.
|
|
|
5929 @item
|
|
|
5930 Any shadowed bindings that are sitting on the @code{specpdl} stack.
|
|
|
5931 @item
|
|
|
5932 Any objects sitting in currently active (Lisp) stack frames,
|
|
|
5933 catches, and condition cases.
|
|
|
5934 @item
|
|
|
5935 A couple of special-case places where active objects are
|
|
|
5936 located.
|
|
|
5937 @item
|
|
|
5938 Anything currently marked with @code{GCPRO}.
|
|
|
5939 @end enumerate
|
|
|
5940
|
|
|
5941 Marking with @code{GCPRO} is necessary because some C functions (quite
|
|
|
5942 a lot, in fact), allocate objects during their operation. Quite
|
|
|
5943 frequently, there will be no other pointer to the object while the
|
|
|
5944 function is running, and if a garbage collection occurs and the object
|
|
|
5945 needs to be referenced again, bad things will happen. The solution is
|
|
1920
|
5946 to mark those references with @code{GCPRO}. Note that it is a
|
|
|
5947 @emph{reference} that is marked with @code{GCPRO}, not an object. If
|
|
|
5948 you declare a @code{Lisp_Object} variable, assign to it, @code{GCPRO}
|
|
|
5949 it, and then assign to it again, the first object assigned @emph{is not}
|
|
|
5950 protected, while the second object @emph{is} protected. Unfortunately
|
|
|
5951 @code{GCPRO}ing is easy to forget, and there is basically no way around
|
|
|
5952 this problem. Here are some rules, though:
|
|
428
|
5953
|
|
|
5954 @enumerate
|
|
|
5955 @item
|
|
1920
|
5956 A garbage collection can occur whenever anything calls @code{Feval}, or
|
|
|
5957 whenever a @code{QUIT} can occur where execution can continue past
|
|
|
5958 this. (Remember, this is almost anywhere.) Note that @code{Fsignal} can
|
|
|
5959 GC, and it can return (even though it normally doesn't). This means
|
|
|
5960 that you must @code{GCPRO} before calling most of the error functions,
|
|
|
5961 including the @samp{CONCHECK} family of macros, if references occur
|
|
|
5962 after the call.
|
|
428
|
5963
|
|
|
5964 @item
|
|
|
5965 You @emph{must} @code{UNGCPRO} anything that's @code{GCPRO}ed, and you
|
|
|
5966 @emph{must not} @code{UNGCPRO} if you haven't @code{GCPRO}ed. Getting
|
|
|
5967 either of these wrong will lead to crashes, often in completely random
|
|
1920
|
5968 places unrelated to where the problem lies. There are some functions
|
|
|
5969 (@code{Fsignal} is the canonical example) which may or may not return.
|
|
|
5970 In these cases, the function is responsible for cleaning up the
|
|
|
5971 @code{GCPRO}s if it doesn't return, so you should treat it as an
|
|
|
5972 ordinary function.
|
|
|
5973
|
|
|
5974 @item
|
|
|
5975 For every @code{GCPRO@var{n}}, there have to be declarations of
|
|
|
5976 @code{struct gcpro gcpro1, gcpro2, ..., gcpro@var{n}}.
|
|
428
|
5977
|
|
|
5978 @item
|
|
|
5979 The way this actually works is that all currently active @code{GCPRO}s
|
|
|
5980 are chained through the @code{struct gcpro} local variables, with the
|
|
|
5981 variable @samp{gcprolist} pointing to the head of the list and the nth
|
|
|
5982 local @code{gcpro} variable pointing to the first @code{gcpro} variable
|
|
|
5983 in the next enclosing stack frame. Each @code{GCPRO}ed thing is an
|
|
|
5984 lvalue, and the @code{struct gcpro} local variable contains a pointer to
|
|
|
5985 this lvalue. This is why things will mess up badly if you don't pair up
|
|
440
|
5986 the @code{GCPRO}s and @code{UNGCPRO}s---you will end up with
|
|
428
|
5987 @code{gcprolist}s containing pointers to @code{struct gcpro}s or local
|
|
|
5988 @code{Lisp_Object} variables in no-longer-active stack frames.
|
|
|
5989
|
|
|
5990 @item
|
|
|
5991 It is actually possible for a single @code{struct gcpro} to
|
|
|
5992 protect a contiguous array of any number of values, rather than
|
|
|
5993 just a single lvalue. To effect this, call @code{GCPRO@var{n}} as usual on
|
|
|
5994 the first object in the array and then set @code{gcpro@var{n}.nvars}.
|
|
|
5995
|
|
|
5996 @item
|
|
|
5997 @strong{Strings are relocated.} What this means in practice is that the
|
|
|
5998 pointer obtained using @code{XSTRING_DATA()} is liable to change at any
|
|
|
5999 time, and you should never keep it around past any function call, or
|
|
|
6000 pass it as an argument to any function that might cause a garbage
|
|
|
6001 collection. This is why a number of functions accept either a
|
|
|
6002 ``non-relocatable'' @code{char *} pointer or a relocatable Lisp string,
|
|
|
6003 and only access the Lisp string's data at the very last minute. In some
|
|
|
6004 cases, you may end up having to @code{alloca()} some space and copy the
|
|
|
6005 string's data into it.
|
|
|
6006
|
|
|
6007 @item
|
|
|
6008 By convention, if you have to nest @code{GCPRO}'s, use @code{NGCPRO@var{n}}
|
|
|
6009 (along with @code{struct gcpro ngcpro1, ngcpro2}, etc.), @code{NNGCPRO@var{n}},
|
|
|
6010 etc. This avoids compiler warnings about shadowed locals.
|
|
|
6011
|
|
|
6012 @item
|
|
|
6013 It is @emph{always} better to err on the side of extra @code{GCPRO}s
|
|
|
6014 rather than too few. The extra cycles spent on this are
|
|
|
6015 almost never going to make a whit of difference in the
|
|
|
6016 speed of anything.
|
|
|
6017
|
|
|
6018 @item
|
|
|
6019 The general rule to follow is that caller, not callee, @code{GCPRO}s.
|
|
|
6020 That is, you should not have to explicitly @code{GCPRO} any Lisp objects
|
|
|
6021 that are passed in as parameters.
|
|
|
6022
|
|
|
6023 One exception from this rule is if you ever plan to change the parameter
|
|
|
6024 value, and store a new object in it. In that case, you @emph{must}
|
|
|
6025 @code{GCPRO} the parameter, because otherwise the new object will not be
|
|
|
6026 protected.
|
|
|
6027
|
|
|
6028 So, if you create any Lisp objects (remember, this happens in all sorts
|
|
|
6029 of circumstances, e.g. with @code{Fcons()}, etc.), you are responsible
|
|
|
6030 for @code{GCPRO}ing them, unless you are @emph{absolutely sure} that
|
|
|
6031 there's no possibility that a garbage-collection can occur while you
|
|
|
6032 need to use the object. Even then, consider @code{GCPRO}ing.
|
|
|
6033
|
|
|
6034 @item
|
|
|
6035 If you have the @emph{least smidgeon of doubt} about whether
|
|
|
6036 you need to @code{GCPRO}, you should @code{GCPRO}.
|
|
|
6037
|
|
|
6038 @item
|
|
|
6039 Beware of @code{GCPRO}ing something that is uninitialized. If you have
|
|
|
6040 any shade of doubt about this, initialize all your variables to @code{Qnil}.
|
|
|
6041
|
|
|
6042 @item
|
|
|
6043 Be careful of traps, like calling @code{Fcons()} in the argument to
|
|
|
6044 another function. By the ``caller protects'' law, you should be
|
|
|
6045 @code{GCPRO}ing the newly-created cons, but you aren't. A certain
|
|
|
6046 number of functions that are commonly called on freshly created stuff
|
|
|
6047 (e.g. @code{nconc2()}, @code{Fsignal()}), break the ``caller protects''
|
|
|
6048 law and go ahead and @code{GCPRO} their arguments so as to simplify
|
|
|
6049 things, but make sure and check if it's OK whenever doing something like
|
|
|
6050 this.
|
|
|
6051
|
|
|
6052 @item
|
|
|
6053 Once again, remember to @code{GCPRO}! Bugs resulting from insufficient
|
|
|
6054 @code{GCPRO}ing are intermittent and extremely difficult to track down,
|
|
|
6055 often showing up in crashes inside of @code{garbage-collect} or in
|
|
|
6056 weirdly corrupted objects or even in incorrect values in a totally
|
|
|
6057 different section of code.
|
|
|
6058 @end enumerate
|
|
|
6059
|
|
965
|
6060 If you don't understand whether to @code{GCPRO} in a particular
|
|
|
6061 instance, ask on the mailing lists. A general hint is that @code{prog1}
|
|
1709
|
6062 is the canonical example.
|
|
965
|
6063
|
|
428
|
6064 @cindex garbage collection, conservative
|
|
|
6065 @cindex conservative garbage collection
|
|
|
6066 Given the extremely error-prone nature of the @code{GCPRO} scheme, and
|
|
|
6067 the difficulties in tracking down, it should be considered a deficiency
|
|
|
6068 in the XEmacs code. A solution to this problem would involve
|
|
|
6069 implementing so-called @dfn{conservative} garbage collection for the C
|
|
|
6070 stack. That involves looking through all of stack memory and treating
|
|
|
6071 anything that looks like a reference to an object as a reference. This
|
|
|
6072 will result in a few objects not getting collected when they should, but
|
|
|
6073 it obviates the need for @code{GCPRO}ing, and allows garbage collection
|
|
|
6074 to happen at any point at all, such as during object allocation.
|
|
|
6075
|
|
462
|
6076 @node Garbage Collection - Step by Step
|
|
428
|
6077 @section Garbage Collection - Step by Step
|
|
462
|
6078 @cindex garbage collection - step by step
|
|
428
|
6079
|
|
|
6080 @menu
|
|
|
6081 * Invocation::
|
|
|
6082 * garbage_collect_1::
|
|
|
6083 * mark_object::
|
|
|
6084 * gc_sweep::
|
|
|
6085 * sweep_lcrecords_1::
|
|
|
6086 * compact_string_chars::
|
|
|
6087 * sweep_strings::
|
|
|
6088 * sweep_bit_vectors_1::
|
|
|
6089 @end menu
|
|
|
6090
|
|
462
|
6091 @node Invocation
|
|
428
|
6092 @subsection Invocation
|
|
|
6093 @cindex garbage collection, invocation
|
|
|
6094
|
|
|
6095 The first thing that anyone should know about garbage collection is:
|
|
442
|
6096 when and how the garbage collector is invoked. One might think that this
|
|
428
|
6097 could happen every time new memory is allocated, e.g. new objects are
|
|
|
6098 created, but this is @emph{not} the case. Instead, we have the following
|
|
|
6099 situation:
|
|
|
6100
|
|
|
6101 The entry point of any process of garbage collection is an invocation
|
|
|
6102 of the function @code{garbage_collect_1} in file @code{alloc.c}. The
|
|
|
6103 invocation can occur @emph{explicitly} by calling the function
|
|
|
6104 @code{Fgarbage_collect} (in addition this function provides information
|
|
442
|
6105 about the freed memory), or can occur @emph{implicitly} in four different
|
|
428
|
6106 situations:
|
|
|
6107 @enumerate
|
|
|
6108 @item
|
|
|
6109 In function @code{main_1} in file @code{emacs.c}. This function is called
|
|
|
6110 at each startup of xemacs. The garbage collection is invoked after all
|
|
|
6111 initial creations are completed, but only if a special internal error
|
|
|
6112 checking-constant @code{ERROR_CHECK_GC} is defined.
|
|
|
6113 @item
|
|
|
6114 In function @code{disksave_object_finalization} in file
|
|
|
6115 @code{alloc.c}. The only purpose of this function is to clear the
|
|
442
|
6116 objects from memory which need not be stored with xemacs when we dump out
|
|
428
|
6117 an executable. This is only done by @code{Fdump_emacs} or by
|
|
|
6118 @code{Fdump_emacs_data} respectively (both in @code{emacs.c}). The
|
|
|
6119 actual clearing is accomplished by making these objects unreachable and
|
|
|
6120 starting a garbage collection. The function is only used while building
|
|
|
6121 xemacs.
|
|
|
6122 @item
|
|
|
6123 In function @code{Feval / eval} in file @code{eval.c}. Each time the
|
|
|
6124 well known and often used function eval is called to evaluate a form,
|
|
|
6125 one of the first things that could happen, is a potential call of
|
|
|
6126 @code{garbage_collect_1}. There exist three global variables,
|
|
|
6127 @code{consing_since_gc} (counts the created cons-cells since the last
|
|
|
6128 garbage collection), @code{gc_cons_threshold} (a specified threshold
|
|
|
6129 after which a garbage collection occurs) and @code{always_gc}. If
|
|
|
6130 @code{always_gc} is set or if the threshold is exceeded, the garbage
|
|
|
6131 collection will start.
|
|
|
6132 @item
|
|
|
6133 In function @code{Ffuncall / funcall} in file @code{eval.c}. This
|
|
|
6134 function evaluates calls of elisp functions and works according to
|
|
|
6135 @code{Feval}.
|
|
|
6136 @end enumerate
|
|
|
6137
|
|
|
6138 The upshot is that garbage collection can basically occur everywhere
|
|
|
6139 @code{Feval}, respectively @code{Ffuncall}, is used - either directly or
|
|
442
|
6140 through another function. Since calls to these two functions are hidden
|
|
|
6141 in various other functions, many calls to @code{garbage_collect_1} are
|
|
|
6142 not obviously foreseeable, and therefore unexpected. Instances where
|
|
|
6143 they are used that are worth remembering are various elisp commands, as
|
|
|
6144 for example @code{or}, @code{and}, @code{if}, @code{cond}, @code{while},
|
|
|
6145 @code{setq}, etc., miscellaneous @code{gui_item_...} functions,
|
|
|
6146 everything related to @code{eval} (@code{Feval_buffer}, @code{call0},
|
|
|
6147 ...) and inside @code{Fsignal}. The latter is used to handle signals, as
|
|
444
|
6148 for example the ones raised by every @code{QUIT}-macro triggered after
|
|
442
|
6149 pressing Ctrl-g.
|
|
|
6150
|
|
462
|
6151 @node garbage_collect_1
|
|
428
|
6152 @subsection @code{garbage_collect_1}
|
|
|
6153 @cindex @code{garbage_collect_1}
|
|
|
6154
|
|
|
6155 We can now describe exactly what happens after the invocation takes
|
|
|
6156 place.
|
|
|
6157 @enumerate
|
|
|
6158 @item
|
|
442
|
6159 There are several cases in which the garbage collector is left immediately:
|
|
428
|
6160 when we are already garbage collecting (@code{gc_in_progress}), when
|
|
|
6161 the garbage collection is somehow forbidden
|
|
|
6162 (@code{gc_currently_forbidden}), when we are currently displaying something
|
|
|
6163 (@code{in_display}) or when we are preparing for the armageddon of the
|
|
|
6164 whole system (@code{preparing_for_armageddon}).
|
|
|
6165 @item
|
|
|
6166 Next the correct frame in which to put
|
|
|
6167 all the output occurring during garbage collecting is determined. In
|
|
|
6168 order to be able to restore the old display's state after displaying the
|
|
|
6169 message, some data about the current cursor position has to be
|
|
442
|
6170 saved. The variables @code{pre_gc_cursor} and @code{cursor_changed} take
|
|
428
|
6171 care of that.
|
|
|
6172 @item
|
|
|
6173 The state of @code{gc_currently_forbidden} must be restored after
|
|
|
6174 the garbage collection, no matter what happens during the process. We
|
|
|
6175 accomplish this by @code{record_unwind_protect}ing the suitable function
|
|
|
6176 @code{restore_gc_inhibit} together with the current value of
|
|
442
|
6177 @code{gc_currently_forbidden}.
|
|
428
|
6178 @item
|
|
|
6179 If we are concurrently running an interactive xemacs session, the next step
|
|
|
6180 is simply to show the garbage collector's cursor/message.
|
|
|
6181 @item
|
|
|
6182 The following steps are the intrinsic steps of the garbage collector,
|
|
|
6183 therefore @code{gc_in_progress} is set.
|
|
|
6184 @item
|
|
|
6185 For debugging purposes, it is possible to copy the current C stack
|
|
|
6186 frame. However, this seems to be a currently unused feature.
|
|
|
6187 @item
|
|
|
6188 Before actually starting to go over all live objects, references to
|
|
|
6189 objects that are no longer used are pruned. We only have to do this for events
|
|
|
6190 (@code{clear_event_resource}) and for specifiers
|
|
442
|
6191 (@code{cleanup_specifiers}).
|
|
428
|
6192 @item
|
|
|
6193 Now the mark phase begins and marks all accessible elements. In order to
|
|
|
6194 start from
|
|
|
6195 all slots that serve as roots of accessibility, the function
|
|
|
6196 @code{mark_object} is called for each root individually to go out from
|
|
|
6197 there to mark all reachable objects. All roots that are traversed are
|
|
|
6198 shown in their processed order:
|
|
|
6199 @itemize @bullet
|
|
|
6200 @item
|
|
|
6201 all constant symbols and static variables that are registered via
|
|
452
|
6202 @code{staticpro}@ in the dynarr @code{staticpros}.
|
|
442
|
6203 @xref{Adding Global Lisp Variables}.
|
|
428
|
6204 @item
|
|
|
6205 all Lisp objects that are created in C functions and that must be
|
|
|
6206 protected from freeing them. They are registered in the global
|
|
|
6207 list @code{gcprolist}.
|
|
|
6208 @xref{GCPROing}.
|
|
442
|
6209 @item
|
|
428
|
6210 all local variables (i.e. their name fields @code{symbol} and old
|
|
|
6211 values @code{old_values}) that are bound during the evaluation by the Lisp
|
|
|
6212 engine. They are stored in @code{specbinding} structs pushed on a stack
|
|
|
6213 called @code{specpdl}.
|
|
|
6214 @xref{Dynamic Binding; The specbinding Stack; Unwind-Protects}.
|
|
|
6215 @item
|
|
|
6216 all catch blocks that the Lisp engine encounters during the evaluation
|
|
|
6217 cause the creation of structs @code{catchtag} inserted in the list
|
|
|
6218 @code{catchlist}. Their tag (@code{tag}) and value (@code{val} fields
|
|
|
6219 are freshly created objects and therefore have to be marked.
|
|
|
6220 @xref{Catch and Throw}.
|
|
|
6221 @item
|
|
442
|
6222 every function application pushes new structs @code{backtrace}
|
|
|
6223 on the call stack of the Lisp engine (@code{backtrace_list}). The unique
|
|
428
|
6224 parts that have to be marked are the fields for each function
|
|
|
6225 (@code{function}) and all their arguments (@code{args}).
|
|
|
6226 @xref{Evaluation}.
|
|
|
6227 @item
|
|
442
|
6228 all objects that are used by the redisplay engine that must not be freed
|
|
428
|
6229 are marked by a special function called @code{mark_redisplay} (in
|
|
|
6230 @code{redisplay.c}).
|
|
|
6231 @item
|
|
|
6232 all objects created for profiling purposes are allocated by C functions
|
|
|
6233 instead of using the lisp allocation mechanisms. In order to receive the
|
|
|
6234 right ones during the sweep phase, they also have to be marked
|
|
|
6235 manually. That is done by the function @code{mark_profiling_info}
|
|
|
6236 @end itemize
|
|
|
6237 @item
|
|
436
|
6238 Hash tables in XEmacs belong to a kind of special objects that
|
|
428
|
6239 make use of a concept often called 'weak pointers'.
|
|
|
6240 To make a long story short, these kind of pointers are not followed
|
|
|
6241 during the estimation of the live objects during garbage collection.
|
|
|
6242 Any object referenced only by weak pointers is collected
|
|
|
6243 anyway, and the reference to it is cleared. In hash tables there are
|
|
|
6244 different usage patterns of them, manifesting in different types of hash
|
|
|
6245 tables, namely 'non-weak', 'weak', 'key-weak' and 'value-weak'
|
|
442
|
6246 (internally also 'key-car-weak' and 'value-car-weak') hash tables, each
|
|
|
6247 clearing entries depending on different conditions. More information can
|
|
428
|
6248 be found in the documentation to the function @code{make-hash-table}.
|
|
|
6249
|
|
|
6250 Because there are complicated dependency rules about when and what to
|
|
|
6251 mark while processing weak hash tables, the standard @code{marker}
|
|
|
6252 method is only active if it is marking non-weak hash tables. As soon as
|
|
|
6253 a weak component is in the table, the hash table entries are ignored
|
|
|
6254 while marking. Instead their marking is done each separately by the
|
|
|
6255 function @code{finish_marking_weak_hash_tables}. This function iterates
|
|
|
6256 over each hash table entry @code{hentries} for each weak hash table in
|
|
|
6257 @code{Vall_weak_hash_tables}. Depending on the type of a table, the
|
|
442
|
6258 appropriate action is performed.
|
|
428
|
6259 If a table is acting as @code{HASH_TABLE_KEY_WEAK}, and a key already marked,
|
|
442
|
6260 everything reachable from the @code{value} component is marked. If it is
|
|
428
|
6261 acting as a @code{HASH_TABLE_VALUE_WEAK} and the value component is
|
|
442
|
6262 already marked, the marking starts beginning only from the
|
|
428
|
6263 @code{key} component.
|
|
442
|
6264 If it is a @code{HASH_TABLE_KEY_CAR_WEAK} and the car
|
|
428
|
6265 of the key entry is already marked, we mark both the @code{key} and
|
|
|
6266 @code{value} components.
|
|
|
6267 Finally, if the table is of the type @code{HASH_TABLE_VALUE_CAR_WEAK}
|
|
|
6268 and the car of the value components is already marked, again both the
|
|
|
6269 @code{key} and the @code{value} components get marked.
|
|
|
6270
|
|
|
6271 Again, there are lists with comparable properties called weak
|
|
|
6272 lists. There exist different peculiarities of their types called
|
|
|
6273 @code{simple}, @code{assoc}, @code{key-assoc} and
|
|
|
6274 @code{value-assoc}. You can find further details about them in the
|
|
|
6275 description to the function @code{make-weak-list}. The scheme of their
|
|
442
|
6276 marking is similar: all weak lists are listed in @code{Qall_weak_lists},
|
|
428
|
6277 therefore we iterate over them. The marking is advanced until we hit an
|
|
442
|
6278 already marked pair. Then we know that during a former run all
|
|
428
|
6279 the rest has been marked completely. Again, depending on the special
|
|
|
6280 type of the weak list, our jobs differ. If it is a @code{WEAK_LIST_SIMPLE}
|
|
|
6281 and the elem is marked, we mark the @code{cons} part. If it is a
|
|
|
6282 @code{WEAK_LIST_ASSOC} and not a pair or a pair with both marked car and
|
|
|
6283 cdr, we mark the @code{cons} and the @code{elem}. If it is a
|
|
|
6284 @code{WEAK_LIST_KEY_ASSOC} and not a pair or a pair with a marked car of
|
|
|
6285 the elem, we mark the @code{cons} and the @code{elem}. Finally, if it is
|
|
|
6286 a @code{WEAK_LIST_VALUE_ASSOC} and not a pair or a pair with a marked
|
|
|
6287 cdr of the elem, we mark both the @code{cons} and the @code{elem}.
|
|
|
6288
|
|
|
6289 Since, by marking objects in reach from weak hash tables and weak lists,
|
|
|
6290 other objects could get marked, this perhaps implies further marking of
|
|
442
|
6291 other weak objects, both finishing functions are redone as long as
|
|
428
|
6292 yet unmarked objects get freshly marked.
|
|
|
6293
|
|
|
6294 @item
|
|
|
6295 After completing the special marking for the weak hash tables and for the weak
|
|
|
6296 lists, all entries that point to objects that are going to be swept in
|
|
|
6297 the further process are useless, and therefore have to be removed from
|
|
|
6298 the table or the list.
|
|
|
6299
|
|
|
6300 The function @code{prune_weak_hash_tables} does the job for weak hash
|
|
|
6301 tables. Totally unmarked hash tables are removed from the list
|
|
|
6302 @code{Vall_weak_hash_tables}. The other ones are treated more carefully
|
|
442
|
6303 by scanning over all entries and removing one as soon as one of
|
|
428
|
6304 the components @code{key} and @code{value} is unmarked.
|
|
|
6305
|
|
|
6306 The same idea applies to the weak lists. It is accomplished by
|
|
|
6307 @code{prune_weak_lists}: An unmarked list is pruned from
|
|
|
6308 @code{Vall_weak_lists} immediately. A marked list is treated more
|
|
|
6309 carefully by going over it and removing just the unmarked pairs.
|
|
|
6310
|
|
|
6311 @item
|
|
|
6312 The function @code{prune_specifiers} checks all listed specifiers held
|
|
442
|
6313 in @code{Vall_specifiers} and removes the ones from the lists that are
|
|
428
|
6314 unmarked.
|
|
|
6315
|
|
|
6316 @item
|
|
|
6317 All syntax tables are stored in a list called
|
|
442
|
6318 @code{Vall_syntax_tables}. The function @code{prune_syntax_tables} walks
|
|
428
|
6319 through it and unlinks the tables that are unmarked.
|
|
|
6320
|
|
|
6321 @item
|
|
|
6322 Next, we will attack the complete sweeping - the function
|
|
|
6323 @code{gc_sweep} which holds the predominance.
|
|
|
6324 @item
|
|
|
6325 First, all the variables with respect to garbage collection are
|
|
442
|
6326 reset. @code{consing_since_gc} - the counter of the created cells since
|
|
428
|
6327 the last garbage collection - is set back to 0, and
|
|
|
6328 @code{gc_in_progress} is not @code{true} anymore.
|
|
|
6329 @item
|
|
442
|
6330 In case the session is interactive, the displayed cursor and message are
|
|
428
|
6331 removed again.
|
|
|
6332 @item
|
|
|
6333 The state of @code{gc_inhibit} is restored to the former value by
|
|
|
6334 unwinding the stack.
|
|
|
6335 @item
|
|
|
6336 A small memory reserve is always held back that can be reached by
|
|
|
6337 @code{breathing_space}. If nothing more is left, we create a new reserve
|
|
442
|
6338 and exit.
|
|
428
|
6339 @end enumerate
|
|
|
6340
|
|
462
|
6341 @node mark_object
|
|
428
|
6342 @subsection @code{mark_object}
|
|
|
6343 @cindex @code{mark_object}
|
|
|
6344
|
|
|
6345 The first thing that is checked while marking an object is whether the
|
|
|
6346 object is a real Lisp object @code{Lisp_Type_Record} or just an integer
|
|
|
6347 or a character. Integers and characters are the only two types that are
|
|
|
6348 stored directly - without another level of indirection, and therefore they
|
|
442
|
6349 don't have to be marked and collected.
|
|
428
|
6350 @xref{How Lisp Objects Are Represented in C}.
|
|
|
6351
|
|
|
6352 The second case is the one we have to handle. It is the one when we are
|
|
|
6353 dealing with a pointer to a Lisp object. But, there exist also three
|
|
|
6354 possibilities, that prevent us from doing anything while marking: The
|
|
|
6355 object is read only which prevents it from being garbage collected,
|
|
|
6356 i.e. marked (@code{C_READONLY_RECORD_HEADER}). The object in question is
|
|
|
6357 already marked, and need not be marked for the second time (checked by
|
|
|
6358 @code{MARKED_RECORD_HEADER_P}). If it is a special, unmarkable object
|
|
|
6359 (@code{UNMARKABLE_RECORD_HEADER_P}, apparently, these are objects that
|
|
442
|
6360 sit in some const space, and can therefore not be marked, see
|
|
428
|
6361 @code{this_one_is_unmarkable} in @code{alloc.c}).
|
|
|
6362
|
|
|
6363 Now, the actual marking is feasible. We do so by once using the macro
|
|
|
6364 @code{MARK_RECORD_HEADER} to mark the object itself (actually the
|
|
|
6365 special flag in the lrecord header), and calling its special marker
|
|
|
6366 "method" @code{marker} if available. The marker method marks every
|
|
442
|
6367 other object that is in reach from our current object. Note, that these
|
|
428
|
6368 marker methods should not call @code{mark_object} recursively, but
|
|
|
6369 instead should return the next object from where further marking has to
|
|
|
6370 be performed.
|
|
|
6371
|
|
|
6372 In case another object was returned, as mentioned before, we reiterate
|
|
|
6373 the whole @code{mark_object} process beginning with this next object.
|
|
|
6374
|
|
462
|
6375 @node gc_sweep
|
|
428
|
6376 @subsection @code{gc_sweep}
|
|
|
6377 @cindex @code{gc_sweep}
|
|
|
6378
|
|
442
|
6379 The job of this function is to free all unmarked records from memory. As
|
|
428
|
6380 we know, there are different types of objects implemented and managed, and
|
|
|
6381 consequently different ways to free them from memory.
|
|
|
6382 @xref{Introduction to Allocation}.
|
|
|
6383
|
|
|
6384 We start with all objects stored through @code{lcrecords}. All
|
|
|
6385 bulkier objects are allocated and handled using that scheme of
|
|
|
6386 @code{lcrecords}. Each object is @code{malloc}ed separately
|
|
|
6387 instead of placing it in one of the contiguous frob blocks. All types
|
|
442
|
6388 that are currently stored
|
|
438
|
6389 using @code{lcrecords}'s @code{alloc_lcrecord} and
|
|
428
|
6390 @code{make_lcrecord_list} are the types: vectors, buffers,
|
|
|
6391 char-table, char-table-entry, console, weak-list, database, device,
|
|
|
6392 ldap, hash-table, command-builder, extent-auxiliary, extent-info, face,
|
|
|
6393 coding-system, frame, image-instance, glyph, popup-data, gui-item,
|
|
|
6394 keymap, charset, color_instance, font_instance, opaque, opaque-list,
|
|
|
6395 process, range-table, specifier, symbol-value-buffer-local,
|
|
|
6396 symbol-value-lisp-magic, symbol-value-varalias, toolbar-button,
|
|
|
6397 tooltalk-message, tooltalk-pattern, window, and window-configuration. We
|
|
|
6398 take care of them in the fist place
|
|
|
6399 in order to be able to handle and to finalize items stored in them more
|
|
|
6400 easily. The function @code{sweep_lcrecords_1} as described below is
|
|
|
6401 doing the whole job for us.
|
|
|
6402 For a description about the internals: @xref{lrecords}.
|
|
|
6403
|
|
|
6404 Our next candidates are the other objects that behave quite differently
|
|
|
6405 than everything else: the strings. They consists of two parts, a
|
|
442
|
6406 fixed-size portion (@code{struct Lisp_String}) holding the string's
|
|
428
|
6407 length, its property list and a pointer to the second part, and the
|
|
|
6408 actual string data, which is stored in string-chars blocks comparable to
|
|
|
6409 frob blocks. In this block, the data is not only freed, but also a
|
|
|
6410 compression of holes is made, i.e. all strings are relocated together.
|
|
|
6411 @xref{String}. This compacting phase is performed by the function
|
|
|
6412 @code{compact_string_chars}, the actual sweeping by the function
|
|
|
6413 @code{sweep_strings} is described below.
|
|
|
6414
|
|
|
6415 After that, the other types are swept step by step using functions
|
|
|
6416 @code{sweep_conses}, @code{sweep_bit_vectors_1},
|
|
|
6417 @code{sweep_compiled_functions}, @code{sweep_floats},
|
|
|
6418 @code{sweep_symbols}, @code{sweep_extents}, @code{sweep_markers} and
|
|
|
6419 @code{sweep_extents}. They are the fixed-size types cons, floats,
|
|
|
6420 compiled-functions, symbol, marker, extent, and event stored in
|
|
|
6421 so-called "frob blocks", and therefore we can basically do the same on
|
|
|
6422 every type objects, using the same macros, especially defined only to
|
|
442
|
6423 handle everything with respect to fixed-size blocks. The only fixed-size
|
|
428
|
6424 type that is not handled here are the fixed-size portion of strings,
|
|
|
6425 because we took special care of them earlier.
|
|
|
6426
|
|
|
6427 The only big exceptions are bit vectors stored differently and
|
|
442
|
6428 therefore treated differently by the function @code{sweep_bit_vectors_1}
|
|
428
|
6429 described later.
|
|
|
6430
|
|
|
6431 At first, we need some brief information about how
|
|
|
6432 these fixed-size types are managed in general, in order to understand
|
|
|
6433 how the sweeping is done. They have all a fixed size, and are therefore
|
|
|
6434 stored in big blocks of memory - allocated at once - that can hold a
|
|
|
6435 certain amount of objects of one type. The macro
|
|
|
6436 @code{DECLARE_FIXED_TYPE_ALLOC} creates the suitable structures for
|
|
442
|
6437 every type. More precisely, we have the block struct
|
|
428
|
6438 (holding a pointer to the previous block @code{prev} and the
|
|
|
6439 objects in @code{block[]}), a pointer to current block
|
|
|
6440 (@code{current_..._block)}) and its last index
|
|
|
6441 (@code{current_..._block_index}), and a pointer to the free list that
|
|
|
6442 will be created. Also a macro @code{FIXED_TYPE_FROM_BLOCK} plus some
|
|
|
6443 related macros exists that are used to obtain a new object, either from
|
|
|
6444 the free list @code{ALLOCATE_FIXED_TYPE_1} if there is an unused object
|
|
|
6445 of that type stored or by allocating a completely new block using
|
|
|
6446 @code{ALLOCATE_FIXED_TYPE_FROM_BLOCK}.
|
|
|
6447
|
|
|
6448 The rest works as follows: all of them define a
|
|
|
6449 macro @code{UNMARK_...} that is used to unmark the object. They define a
|
|
|
6450 macro @code{ADDITIONAL_FREE_...} that defines additional work that has
|
|
|
6451 to be done when converting an object from in use to not in use (so far,
|
|
|
6452 only markers use it in order to unchain them). Then, they all call
|
|
442
|
6453 the macro @code{SWEEP_FIXED_TYPE_BLOCK} instantiated with their type name
|
|
428
|
6454 and their struct name.
|
|
|
6455
|
|
|
6456 This call in particular does the following: we go over all blocks
|
|
|
6457 starting with the current moving towards the oldest.
|
|
|
6458 For each block, we look at every object in it. If the object already
|
|
|
6459 freed (checked with @code{FREE_STRUCT_P} using the first pointer of the
|
|
442
|
6460 object), or if it is
|
|
428
|
6461 set to read only (@code{C_READONLY_RECORD_HEADER_P}, nothing must be
|
|
|
6462 done. If it is unmarked (checked with @code{MARKED_RECORD_HEADER_P}), it
|
|
|
6463 is put in the free list and set free (using the macro
|
|
442
|
6464 @code{FREE_FIXED_TYPE}, otherwise it stays in the block, but is unmarked
|
|
428
|
6465 (by @code{UNMARK_...}). While going through one block, we note if the
|
|
|
6466 whole block is empty. If so, the whole block is freed (using
|
|
|
6467 @code{xfree}) and the free list state is set to the state it had before
|
|
|
6468 handling this block.
|
|
|
6469
|
|
462
|
6470 @node sweep_lcrecords_1
|
|
428
|
6471 @subsection @code{sweep_lcrecords_1}
|
|
|
6472 @cindex @code{sweep_lcrecords_1}
|
|
|
6473
|
|
|
6474 After nullifying the complete lcrecord statistics, we go over all
|
|
442
|
6475 lcrecords two separate times. They are all chained together in a list with
|
|
|
6476 a head called @code{all_lcrecords}.
|
|
|
6477
|
|
|
6478 The first loop calls for each object its @code{finalizer} method, but only
|
|
428
|
6479 in the case that it is not read only
|
|
|
6480 (@code{C_READONLY_RECORD_HEADER_P)}, it is not already marked
|
|
|
6481 (@code{MARKED_RECORD_HEADER_P}), it is not already in a free list (list of
|
|
|
6482 freed objects, field @code{free}) and finally it owns a finalizer
|
|
|
6483 method.
|
|
442
|
6484
|
|
|
6485 The second loop actually frees the appropriate objects again by iterating
|
|
|
6486 through the whole list. In case an object is read only or marked, it
|
|
428
|
6487 has to persist, otherwise it is manually freed by calling
|
|
|
6488 @code{xfree}. During this loop, the lcrecord statistics are kept up to
|
|
442
|
6489 date by calling @code{tick_lcrecord_stats} with the right arguments,
|
|
|
6490
|
|
462
|
6491 @node compact_string_chars
|
|
428
|
6492 @subsection @code{compact_string_chars}
|
|
|
6493 @cindex @code{compact_string_chars}
|
|
|
6494
|
|
|
6495 The purpose of this function is to compact all the data parts of the
|
|
|
6496 strings that are held in so-called @code{string_chars_block}, i.e. the
|
|
|
6497 strings that do not exceed a certain maximal length.
|
|
|
6498
|
|
|
6499 The procedure with which this is done is as follows. We are keeping two
|
|
|
6500 positions in the @code{string_chars_block}s using two pointer/integer
|
|
|
6501 pairs, namely @code{from_sb}/@code{from_pos} and
|
|
|
6502 @code{to_sb}/@code{to_pos}. They stand for the actual positions, from
|
|
442
|
6503 where to where, to copy the actually handled string.
|
|
428
|
6504
|
|
|
6505 While going over all chained @code{string_char_block}s and their held
|
|
|
6506 strings, staring at @code{first_string_chars_block}, both pointers
|
|
|
6507 are advanced and eventually a string is copied from @code{from_sb} to
|
|
|
6508 @code{to_sb}, depending on the status of the pointed at strings.
|
|
|
6509
|
|
|
6510 More precisely, we can distinguish between the following actions.
|
|
|
6511 @itemize @bullet
|
|
|
6512 @item
|
|
|
6513 The string at @code{from_sb}'s position could be marked as free, which
|
|
442
|
6514 is indicated by an invalid pointer to the pointer that should point back
|
|
428
|
6515 to the fixed size string object, and which is checked by
|
|
|
6516 @code{FREE_STRUCT_P}. In this case, the @code{from_sb}/@code{from_pos}
|
|
|
6517 is advanced to the next string, and nothing has to be copied.
|
|
|
6518 @item
|
|
|
6519 Also, if a string object itself is unmarked, nothing has to be
|
|
|
6520 copied. We likewise advance the @code{from_sb}/@code{from_pos}
|
|
|
6521 pair as described above.
|
|
|
6522 @item
|
|
442
|
6523 In all other cases, we have a marked string at hand. The string data
|
|
428
|
6524 must be moved from the from-position to the to-position. In case
|
|
|
6525 there is not enough space in the actual @code{to_sb}-block, we advance
|
|
|
6526 this pointer to the beginning of the next block before copying. In case the
|
|
|
6527 from and to positions are different, we perform the
|
|
|
6528 actual copying using the library function @code{memmove}.
|
|
|
6529 @end itemize
|
|
|
6530
|
|
|
6531 After compacting, the pointer to the current
|
|
|
6532 @code{string_chars_block}, sitting in @code{current_string_chars_block},
|
|
|
6533 is reset on the last block to which we moved a string,
|
|
|
6534 i.e. @code{to_block}, and all remaining blocks (we know that they just
|
|
|
6535 carry garbage) are explicitly @code{xfree}d.
|
|
|
6536
|
|
462
|
6537 @node sweep_strings
|
|
428
|
6538 @subsection @code{sweep_strings}
|
|
|
6539 @cindex @code{sweep_strings}
|
|
|
6540
|
|
|
6541 The sweeping for the fixed sized string objects is essentially exactly
|
|
|
6542 the same as it is for all other fixed size types. As before, the freeing
|
|
|
6543 into the suitable free list is done by using the macro
|
|
|
6544 @code{SWEEP_FIXED_SIZE_BLOCK} after defining the right macros
|
|
|
6545 @code{UNMARK_string} and @code{ADDITIONAL_FREE_string}. These two
|
|
|
6546 definitions are a little bit special compared to the ones used
|
|
|
6547 for the other fixed size types.
|
|
|
6548
|
|
442
|
6549 @code{UNMARK_string} is defined the same way except some additional code
|
|
428
|
6550 used for updating the bookkeeping information.
|
|
|
6551
|
|
|
6552 For strings, @code{ADDITIONAL_FREE_string} has to do something in
|
|
|
6553 addition: in case, the string was not allocated in a
|
|
|
6554 @code{string_chars_block} because it exceeded the maximal length, and
|
|
|
6555 therefore it was @code{malloc}ed separately, we know also @code{xfree}
|
|
|
6556 it explicitly.
|
|
|
6557
|
|
462
|
6558 @node sweep_bit_vectors_1
|
|
428
|
6559 @subsection @code{sweep_bit_vectors_1}
|
|
|
6560 @cindex @code{sweep_bit_vectors_1}
|
|
|
6561
|
|
|
6562 Bit vectors are also one of the rare types that are @code{malloc}ed
|
|
|
6563 individually. Consequently, while sweeping, all further needless
|
|
|
6564 bit vectors must be freed by hand. This is done, as one might imagine,
|
|
|
6565 the expected way: since they are all registered in a list called
|
|
|
6566 @code{all_bit_vectors}, all elements of that list are traversed,
|
|
442
|
6567 all unmarked bit vectors are unlinked by calling @code{xfree} and all of
|
|
428
|
6568 them become unmarked.
|
|
442
|
6569 In addition, the bookkeeping information used for garbage
|
|
428
|
6570 collector's output purposes is updated.
|
|
|
6571
|
|
462
|
6572 @node Integers and Characters
|
|
428
|
6573 @section Integers and Characters
|
|
462
|
6574 @cindex integers and characters
|
|
|
6575 @cindex characters, integers and
|
|
428
|
6576
|
|
|
6577 Integer and character Lisp objects are created from integers using the
|
|
|
6578 macros @code{XSETINT()} and @code{XSETCHAR()} or the equivalent
|
|
|
6579 functions @code{make_int()} and @code{make_char()}. (These are actually
|
|
|
6580 macros on most systems.) These functions basically just do some moving
|
|
|
6581 of bits around, since the integral value of the object is stored
|
|
|
6582 directly in the @code{Lisp_Object}.
|
|
|
6583
|
|
|
6584 @code{XSETINT()} and the like will truncate values given to them that
|
|
|
6585 are too big; i.e. you won't get the value you expected but the tag bits
|
|
|
6586 will at least be correct.
|
|
|
6587
|
|
462
|
6588 @node Allocation from Frob Blocks
|
|
428
|
6589 @section Allocation from Frob Blocks
|
|
462
|
6590 @cindex allocation from frob blocks
|
|
|
6591 @cindex frob blocks, allocation from
|
|
428
|
6592
|
|
|
6593 The uninitialized memory required by a @code{Lisp_Object} of a particular type
|
|
|
6594 is allocated using
|
|
|
6595 @code{ALLOCATE_FIXED_TYPE()}. This only occurs inside of the
|
|
|
6596 lowest-level object-creating functions in @file{alloc.c}:
|
|
|
6597 @code{Fcons()}, @code{make_float()}, @code{Fmake_byte_code()},
|
|
|
6598 @code{Fmake_symbol()}, @code{allocate_extent()},
|
|
|
6599 @code{allocate_event()}, @code{Fmake_marker()}, and
|
|
|
6600 @code{make_uninit_string()}. The idea is that, for each type, there are
|
|
|
6601 a number of frob blocks (each 2K in size); each frob block is divided up
|
|
|
6602 into object-sized chunks. Each frob block will have some of these
|
|
|
6603 chunks that are currently assigned to objects, and perhaps some that are
|
|
|
6604 free. (If a frob block has nothing but free chunks, it is freed at the
|
|
|
6605 end of the garbage collection cycle.) The free chunks are stored in a
|
|
|
6606 free list, which is chained by storing a pointer in the first four bytes
|
|
|
6607 of the chunk. (Except for the free chunks at the end of the last frob
|
|
|
6608 block, which are handled using an index which points past the end of the
|
|
|
6609 last-allocated chunk in the last frob block.)
|
|
|
6610 @code{ALLOCATE_FIXED_TYPE()} first tries to retrieve a chunk from the
|
|
|
6611 free list; if that fails, it calls
|
|
|
6612 @code{ALLOCATE_FIXED_TYPE_FROM_BLOCK()}, which looks at the end of the
|
|
|
6613 last frob block for space, and creates a new frob block if there is
|
|
|
6614 none. (There are actually two versions of these macros, one of which is
|
|
|
6615 more defensive but less efficient and is used for error-checking.)
|
|
|
6616
|
|
462
|
6617 @node lrecords
|
|
428
|
6618 @section lrecords
|
|
462
|
6619 @cindex lrecords
|
|
428
|
6620
|
|
|
6621 [see @file{lrecord.h}]
|
|
|
6622
|
|
|
6623 All lrecords have at the beginning of their structure a @code{struct
|
|
442
|
6624 lrecord_header}. This just contains a type number and some flags,
|
|
|
6625 including the mark bit. All builtin type numbers are defined as
|
|
|
6626 constants in @code{enum lrecord_type}, to allow the compiler to generate
|
|
|
6627 more efficient code for @code{@var{type}P}. The type number, thru the
|
|
|
6628 @code{lrecord_implementation_table}, gives access to a @code{struct
|
|
428
|
6629 lrecord_implementation}, which is a structure containing method pointers
|
|
|
6630 and such. There is one of these for each type, and it is a global,
|
|
|
6631 constant, statically-declared structure that is declared in the
|
|
442
|
6632 @code{DEFINE_LRECORD_IMPLEMENTATION()} macro.
|
|
|
6633
|
|
|
6634 Simple lrecords (of type (b) above) just have a @code{struct
|
|
428
|
6635 lrecord_header} at their beginning. lcrecords, however, actually have a
|
|
|
6636 @code{struct lcrecord_header}. This, in turn, has a @code{struct
|
|
|
6637 lrecord_header} at its beginning, so sanity is preserved; but it also
|
|
|
6638 has a pointer used to chain all lcrecords together, and a special ID
|
|
|
6639 field used to distinguish one lcrecord from another. (This field is used
|
|
|
6640 only for debugging and could be removed, but the space gain is not
|
|
|
6641 significant.)
|
|
|
6642
|
|
|
6643 Simple lrecords are created using @code{ALLOCATE_FIXED_TYPE()}, just
|
|
|
6644 like for other frob blocks. The only change is that the implementation
|
|
|
6645 pointer must be initialized correctly. (The implementation structure for
|
|
|
6646 an lrecord, or rather the pointer to it, is named @code{lrecord_float},
|
|
|
6647 @code{lrecord_extent}, @code{lrecord_buffer}, etc.)
|
|
|
6648
|
|
|
6649 lcrecords are created using @code{alloc_lcrecord()}. This takes a
|
|
|
6650 size to allocate and an implementation pointer. (The size needs to be
|
|
|
6651 passed because some lcrecords, such as window configurations, are of
|
|
|
6652 variable size.) This basically just @code{malloc()}s the storage,
|
|
|
6653 initializes the @code{struct lcrecord_header}, and chains the lcrecord
|
|
|
6654 onto the head of the list of all lcrecords, which is stored in the
|
|
|
6655 variable @code{all_lcrecords}. The calls to @code{alloc_lcrecord()}
|
|
|
6656 generally occur in the lowest-level allocation function for each lrecord
|
|
|
6657 type.
|
|
|
6658
|
|
|
6659 Whenever you create an lrecord, you need to call either
|
|
|
6660 @code{DEFINE_LRECORD_IMPLEMENTATION()} or
|
|
|
6661 @code{DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION()}. This needs to be
|
|
442
|
6662 specified in a @file{.c} file, at the top level. What this actually
|
|
|
6663 does is define and initialize the implementation structure for the
|
|
|
6664 lrecord. (And possibly declares a function @code{error_check_foo()} that
|
|
|
6665 implements the @code{XFOO()} macro when error-checking is enabled.) The
|
|
|
6666 arguments to the macros are the actual type name (this is used to
|
|
|
6667 construct the C variable name of the lrecord implementation structure
|
|
|
6668 and related structures using the @samp{##} macro concatenation
|
|
|
6669 operator), a string that names the type on the Lisp level (this may not
|
|
|
6670 be the same as the C type name; typically, the C type name has
|
|
|
6671 underscores, while the Lisp string has dashes), various method pointers,
|
|
|
6672 and the name of the C structure that contains the object. The methods
|
|
|
6673 are used to encapsulate type-specific information about the object, such
|
|
|
6674 as how to print it or mark it for garbage collection, so that it's easy
|
|
|
6675 to add new object types without having to add a specific case for each
|
|
|
6676 new type in a bunch of different places.
|
|
428
|
6677
|
|
|
6678 The difference between @code{DEFINE_LRECORD_IMPLEMENTATION()} and
|
|
|
6679 @code{DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION()} is that the former is
|
|
|
6680 used for fixed-size object types and the latter is for variable-size
|
|
|
6681 object types. Most object types are fixed-size; some complex
|
|
|
6682 types, however (e.g. window configurations), are variable-size.
|
|
|
6683 Variable-size object types have an extra method, which is called
|
|
|
6684 to determine the actual size of a particular object of that type.
|
|
|
6685 (Currently this is only used for keeping allocation statistics.)
|
|
|
6686
|
|
|
6687 For the purpose of keeping allocation statistics, the allocation
|
|
|
6688 engine keeps a list of all the different types that exist. Note that,
|
|
|
6689 since @code{DEFINE_LRECORD_IMPLEMENTATION()} is a macro that is
|
|
442
|
6690 specified at top-level, there is no way for it to initialize the global
|
|
|
6691 data structures containing type information, like
|
|
|
6692 @code{lrecord_implementations_table}. For this reason a call to
|
|
|
6693 @code{INIT_LRECORD_IMPLEMENTATION} must be added to the same source file
|
|
|
6694 containing @code{DEFINE_LRECORD_IMPLEMENTATION}, but instead of to the
|
|
|
6695 top level, to one of the init functions, typically
|
|
|
6696 @code{syms_of_@var{foo}.c}. @code{INIT_LRECORD_IMPLEMENTATION} must be
|
|
|
6697 called before an object of this type is used.
|
|
|
6698
|
|
|
6699 The type number is also used to index into an array holding the number
|
|
|
6700 of objects of each type and the total memory allocated for objects of
|
|
|
6701 that type. The statistics in this array are computed during the sweep
|
|
|
6702 stage. These statistics are returned by the call to
|
|
|
6703 @code{garbage-collect}.
|
|
428
|
6704
|
|
|
6705 Note that for every type defined with a @code{DEFINE_LRECORD_*()}
|
|
|
6706 macro, there needs to be a @code{DECLARE_LRECORD_IMPLEMENTATION()}
|
|
|
6707 somewhere in a @file{.h} file, and this @file{.h} file needs to be
|
|
|
6708 included by @file{inline.c}.
|
|
|
6709
|
|
|
6710 Furthermore, there should generally be a set of @code{XFOOBAR()},
|
|
|
6711 @code{FOOBARP()}, etc. macros in a @file{.h} (or occasionally @file{.c})
|
|
|
6712 file. To create one of these, copy an existing model and modify as
|
|
|
6713 necessary.
|
|
|
6714
|
|
442
|
6715 @strong{Please note:} If you define an lrecord in an external
|
|
|
6716 dynamically-loaded module, you must use @code{DECLARE_EXTERNAL_LRECORD},
|
|
|
6717 @code{DEFINE_EXTERNAL_LRECORD_IMPLEMENTATION}, and
|
|
|
6718 @code{DEFINE_EXTERNAL_LRECORD_SEQUENCE_IMPLEMENTATION} instead of the
|
|
|
6719 non-EXTERNAL forms. These macros will dynamically add new type numbers
|
|
|
6720 to the global enum that records them, whereas the non-EXTERNAL forms
|
|
|
6721 assume that the programmer has already inserted the correct type numbers
|
|
|
6722 into the enum's code at compile-time.
|
|
|
6723
|
|
428
|
6724 The various methods in the lrecord implementation structure are:
|
|
|
6725
|
|
|
6726 @enumerate
|
|
|
6727 @item
|
|
|
6728 @cindex mark method
|
|
|
6729 A @dfn{mark} method. This is called during the marking stage and passed
|
|
|
6730 a function pointer (usually the @code{mark_object()} function), which is
|
|
|
6731 used to mark an object. All Lisp objects that are contained within the
|
|
|
6732 object need to be marked by applying this function to them. The mark
|
|
444
|
6733 method should also return a Lisp object, which should be either @code{nil} or
|
|
428
|
6734 an object to mark. (This can be used in lieu of calling
|
|
|
6735 @code{mark_object()} on the object, to reduce the recursion depth, and
|
|
|
6736 consequently should be the most heavily nested sub-object, such as a
|
|
|
6737 long list.)
|
|
|
6738
|
|
|
6739 @strong{Please note:} When the mark method is called, garbage collection
|
|
|
6740 is in progress, and special precautions need to be taken when accessing
|
|
|
6741 objects; see section (B) above.
|
|
|
6742
|
|
|
6743 If your mark method does not need to do anything, it can be
|
|
|
6744 @code{NULL}.
|
|
|
6745
|
|
|
6746 @item
|
|
|
6747 A @dfn{print} method. This is called to create a printed representation
|
|
|
6748 of the object, whenever @code{princ}, @code{prin1}, or the like is
|
|
|
6749 called. It is passed the object, a stream to which the output is to be
|
|
|
6750 directed, and an @code{escapeflag} which indicates whether the object's
|
|
|
6751 printed representation should be @dfn{escaped} so that it is
|
|
|
6752 readable. (This corresponds to the difference between @code{princ} and
|
|
|
6753 @code{prin1}.) Basically, @dfn{escaped} means that strings will have
|
|
|
6754 quotes around them and confusing characters in the strings such as
|
|
|
6755 quotes, backslashes, and newlines will be backslashed; and that special
|
|
|
6756 care will be taken to make symbols print in a readable fashion
|
|
|
6757 (e.g. symbols that look like numbers will be backslashed). Other
|
|
|
6758 readable objects should perhaps pass @code{escapeflag} on when
|
|
|
6759 sub-objects are printed, so that readability is preserved when necessary
|
|
|
6760 (or if not, always pass in a 1 for @code{escapeflag}). Non-readable
|
|
|
6761 objects should in general ignore @code{escapeflag}, except that some use
|
|
|
6762 it as an indication that more verbose output should be given.
|
|
|
6763
|
|
|
6764 Sub-objects are printed using @code{print_internal()}, which takes
|
|
|
6765 exactly the same arguments as are passed to the print method.
|
|
|
6766
|
|
|
6767 Literal C strings should be printed using @code{write_c_string()},
|
|
|
6768 or @code{write_string_1()} for non-null-terminated strings.
|
|
|
6769
|
|
|
6770 Functions that do not have a readable representation should check the
|
|
|
6771 @code{print_readably} flag and signal an error if it is set.
|
|
|
6772
|
|
|
6773 If you specify NULL for the print method, the
|
|
|
6774 @code{default_object_printer()} will be used.
|
|
|
6775
|
|
|
6776 @item
|
|
|
6777 A @dfn{finalize} method. This is called at the beginning of the sweep
|
|
|
6778 stage on lcrecords that are about to be freed, and should be used to
|
|
|
6779 perform any extra object cleanup. This typically involves freeing any
|
|
|
6780 extra @code{malloc()}ed memory associated with the object, releasing any
|
|
|
6781 operating-system and window-system resources associated with the object
|
|
|
6782 (e.g. pixmaps, fonts), etc.
|
|
|
6783
|
|
|
6784 The finalize method can be NULL if nothing needs to be done.
|
|
|
6785
|
|
|
6786 WARNING #1: The finalize method is also called at the end of the dump
|
|
|
6787 phase; this time with the for_disksave parameter set to non-zero. The
|
|
|
6788 object is @emph{not} about to disappear, so you have to make sure to
|
|
|
6789 @emph{not} free any extra @code{malloc()}ed memory if you're going to
|
|
|
6790 need it later. (Also, signal an error if there are any operating-system
|
|
|
6791 and window-system resources here, because they can't be dumped.)
|
|
|
6792
|
|
|
6793 Finalize methods should, as a rule, set to zero any pointers after
|
|
|
6794 they've been freed, and check to make sure pointers are not zero before
|
|
|
6795 freeing. Although I'm pretty sure that finalize methods are not called
|
|
|
6796 twice on the same object (except for the @code{for_disksave} proviso),
|
|
|
6797 we've gotten nastily burned in some cases by not doing this.
|
|
|
6798
|
|
|
6799 WARNING #2: The finalize method is @emph{only} called for
|
|
|
6800 lcrecords, @emph{not} for simply lrecords. If you need a
|
|
|
6801 finalize method for simple lrecords, you have to stick
|
|
|
6802 it in the @code{ADDITIONAL_FREE_foo()} macro in @file{alloc.c}.
|
|
|
6803
|
|
|
6804 WARNING #3: Things are in an @emph{extremely} bizarre state
|
|
|
6805 when @code{ADDITIONAL_FREE_foo()} is called, so you have to
|
|
|
6806 be incredibly careful when writing one of these functions.
|
|
|
6807 See the comment in @code{gc_sweep()}. If you ever have to add
|
|
|
6808 one of these, consider using an lcrecord or dealing with
|
|
|
6809 the problem in a different fashion.
|
|
|
6810
|
|
|
6811 @item
|
|
|
6812 An @dfn{equal} method. This compares the two objects for similarity,
|
|
|
6813 when @code{equal} is called. It should compare the contents of the
|
|
|
6814 objects in some reasonable fashion. It is passed the two objects and a
|
|
|
6815 @dfn{depth} value, which is used to catch circular objects. To compare
|
|
|
6816 sub-Lisp-objects, call @code{internal_equal()} and bump the depth value
|
|
|
6817 by one. If this value gets too high, a @code{circular-object} error
|
|
|
6818 will be signaled.
|
|
|
6819
|
|
|
6820 If this is NULL, objects are @code{equal} only when they are @code{eq},
|
|
|
6821 i.e. identical.
|
|
|
6822
|
|
|
6823 @item
|
|
|
6824 A @dfn{hash} method. This is used to hash objects when they are to be
|
|
|
6825 compared with @code{equal}. The rule here is that if two objects are
|
|
|
6826 @code{equal}, they @emph{must} hash to the same value; i.e. your hash
|
|
|
6827 function should use some subset of the sub-fields of the object that are
|
|
|
6828 compared in the ``equal'' method. If you specify this method as
|
|
|
6829 @code{NULL}, the object's pointer will be used as the hash, which will
|
|
|
6830 @emph{fail} if the object has an @code{equal} method, so don't do this.
|
|
|
6831
|
|
|
6832 To hash a sub-Lisp-object, call @code{internal_hash()}. Bump the
|
|
|
6833 depth by one, just like in the ``equal'' method.
|
|
|
6834
|
|
|
6835 To convert a Lisp object directly into a hash value (using
|
|
|
6836 its pointer), use @code{LISP_HASH()}. This is what happens when
|
|
|
6837 the hash method is NULL.
|
|
|
6838
|
|
|
6839 To hash two or more values together into a single value, use
|
|
|
6840 @code{HASH2()}, @code{HASH3()}, @code{HASH4()}, etc.
|
|
|
6841
|
|
|
6842 @item
|
|
|
6843 @dfn{getprop}, @dfn{putprop}, @dfn{remprop}, and @dfn{plist} methods.
|
|
|
6844 These are used for object types that have properties. I don't feel like
|
|
|
6845 documenting them here. If you create one of these objects, you have to
|
|
|
6846 use different macros to define them,
|
|
|
6847 i.e. @code{DEFINE_LRECORD_IMPLEMENTATION_WITH_PROPS()} or
|
|
|
6848 @code{DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION_WITH_PROPS()}.
|
|
|
6849
|
|
|
6850 @item
|
|
|
6851 A @dfn{size_in_bytes} method, when the object is of variable-size.
|
|
|
6852 (i.e. declared with a @code{_SEQUENCE_IMPLEMENTATION} macro.) This should
|
|
|
6853 simply return the object's size in bytes, exactly as you might expect.
|
|
|
6854 For an example, see the methods for window configurations and opaques.
|
|
|
6855 @end enumerate
|
|
|
6856
|
|
462
|
6857 @node Low-level allocation
|
|
428
|
6858 @section Low-level allocation
|
|
462
|
6859 @cindex low-level allocation
|
|
|
6860 @cindex allocation, low-level
|
|
428
|
6861
|
|
|
6862 Memory that you want to allocate directly should be allocated using
|
|
|
6863 @code{xmalloc()} rather than @code{malloc()}. This implements
|
|
|
6864 error-checking on the return value, and once upon a time did some more
|
|
|
6865 vital stuff (i.e. @code{BLOCK_INPUT}, which is no longer necessary).
|
|
|
6866 Free using @code{xfree()}, and realloc using @code{xrealloc()}. Note
|
|
|
6867 that @code{xmalloc()} will do a non-local exit if the memory can't be
|
|
|
6868 allocated. (Many functions, however, do not expect this, and thus XEmacs
|
|
|
6869 will likely crash if this happens. @strong{This is a bug.} If you can,
|
|
|
6870 you should strive to make your function handle this OK. However, it's
|
|
|
6871 difficult in the general circumstance, perhaps requiring extra
|
|
|
6872 unwind-protects and such.)
|
|
|
6873
|
|
|
6874 Note that XEmacs provides two separate replacements for the standard
|
|
|
6875 @code{malloc()} library function. These are called @dfn{old GNU malloc}
|
|
|
6876 (@file{malloc.c}) and @dfn{new GNU malloc} (@file{gmalloc.c}),
|
|
|
6877 respectively. New GNU malloc is better in pretty much every way than
|
|
|
6878 old GNU malloc, and should be used if possible. (It used to be that on
|
|
|
6879 some systems, the old one worked but the new one didn't. I think this
|
|
|
6880 was due specifically to a bug in SunOS, which the new one now works
|
|
|
6881 around; so I don't think the old one ever has to be used any more.) The
|
|
|
6882 primary difference between both of these mallocs and the standard system
|
|
|
6883 malloc is that they are much faster, at the expense of increased space.
|
|
|
6884 The basic idea is that memory is allocated in fixed chunks of powers of
|
|
|
6885 two. This allows for basically constant malloc time, since the various
|
|
|
6886 chunks can just be kept on a number of free lists. (The standard system
|
|
|
6887 malloc typically allocates arbitrary-sized chunks and has to spend some
|
|
|
6888 time, sometimes a significant amount of time, walking the heap looking
|
|
|
6889 for a free block to use and cleaning things up.) The new GNU malloc
|
|
|
6890 improves on things by allocating large objects in chunks of 4096 bytes
|
|
|
6891 rather than in ever larger powers of two, which results in ever larger
|
|
|
6892 wastage. There is a slight speed loss here, but it's of doubtful
|
|
|
6893 significance.
|
|
|
6894
|
|
|
6895 NOTE: Apparently there is a third-generation GNU malloc that is
|
|
|
6896 significantly better than the new GNU malloc, and should probably
|
|
|
6897 be included in XEmacs.
|
|
|
6898
|
|
|
6899 There is also the relocating allocator, @file{ralloc.c}. This actually
|
|
|
6900 moves blocks of memory around so that the @code{sbrk()} pointer shrunk
|
|
|
6901 and virtual memory released back to the system. On some systems,
|
|
|
6902 this is a big win. On all systems, it causes a noticeable (and
|
|
|
6903 sometimes huge) speed penalty, so I turn it off by default.
|
|
|
6904 @file{ralloc.c} only works with the new GNU malloc in @file{gmalloc.c}.
|
|
|
6905 There are also two versions of @file{ralloc.c}, one that uses @code{mmap()}
|
|
|
6906 rather than block copies to move data around. This purports to
|
|
|
6907 be faster, although that depends on the amount of data that would
|
|
|
6908 have had to be block copied and the system-call overhead for
|
|
|
6909 @code{mmap()}. I don't know exactly how this works, except that the
|
|
|
6910 relocating-allocation routines are pretty much used only for
|
|
|
6911 the memory allocated for a buffer, which is the biggest consumer
|
|
|
6912 of space, esp. of space that may get freed later.
|
|
|
6913
|
|
|
6914 Note that the GNU mallocs have some ``memory warning'' facilities.
|
|
|
6915 XEmacs taps into them and issues a warning through the standard
|
|
|
6916 warning system, when memory gets to 75%, 85%, and 95% full.
|
|
|
6917 (On some systems, the memory warnings are not functional.)
|
|
|
6918
|
|
|
6919 Allocated memory that is going to be used to make a Lisp object
|
|
442
|
6920 is created using @code{allocate_lisp_storage()}. This just calls
|
|
|
6921 @code{xmalloc()}. It used to verify that the pointer to the memory can
|
|
|
6922 fit into a Lisp word, before the current Lisp object representation was
|
|
|
6923 introduced. @code{allocate_lisp_storage()} is called by
|
|
|
6924 @code{alloc_lcrecord()}, @code{ALLOCATE_FIXED_TYPE()}, and the vector
|
|
|
6925 and bit-vector creation routines. These routines also call
|
|
|
6926 @code{INCREMENT_CONS_COUNTER()} at the appropriate times; this keeps
|
|
|
6927 statistics on how much memory is allocated, so that garbage-collection
|
|
|
6928 can be invoked when the threshold is reached.
|
|
|
6929
|
|
462
|
6930 @node Cons
|
|
428
|
6931 @section Cons
|
|
462
|
6932 @cindex cons
|
|
428
|
6933
|
|
|
6934 Conses are allocated in standard frob blocks. The only thing to
|
|
|
6935 note is that conses can be explicitly freed using @code{free_cons()}
|
|
|
6936 and associated functions @code{free_list()} and @code{free_alist()}. This
|
|
|
6937 immediately puts the conses onto the cons free list, and decrements
|
|
|
6938 the statistics on memory allocation appropriately. This is used
|
|
|
6939 to good effect by some extremely commonly-used code, to avoid
|
|
|
6940 generating extra objects and thereby triggering GC sooner.
|
|
|
6941 However, you have to be @emph{extremely} careful when doing this.
|
|
|
6942 If you mess this up, you will get BADLY BURNED, and it has happened
|
|
|
6943 before.
|
|
|
6944
|
|
462
|
6945 @node Vector
|
|
428
|
6946 @section Vector
|
|
462
|
6947 @cindex vector
|
|
428
|
6948
|
|
|
6949 As mentioned above, each vector is @code{malloc()}ed individually, and
|
|
|
6950 all are threaded through the variable @code{all_vectors}. Vectors are
|
|
|
6951 marked strangely during garbage collection, by kludging the size field.
|
|
|
6952 Note that the @code{struct Lisp_Vector} is declared with its
|
|
|
6953 @code{contents} field being a @emph{stretchy} array of one element. It
|
|
|
6954 is actually @code{malloc()}ed with the right size, however, and access
|
|
|
6955 to any element through the @code{contents} array works fine.
|
|
|
6956
|
|
462
|
6957 @node Bit Vector
|
|
428
|
6958 @section Bit Vector
|
|
462
|
6959 @cindex bit vector
|
|
|
6960 @cindex vector, bit
|
|
428
|
6961
|
|
|
6962 Bit vectors work exactly like vectors, except for more complicated
|
|
|
6963 code to access an individual bit, and except for the fact that bit
|
|
|
6964 vectors are lrecords while vectors are not. (The only difference here is
|
|
|
6965 that there's an lrecord implementation pointer at the beginning and the
|
|
|
6966 tag field in bit vector Lisp words is ``lrecord'' rather than
|
|
|
6967 ``vector''.)
|
|
|
6968
|
|
462
|
6969 @node Symbol
|
|
428
|
6970 @section Symbol
|
|
462
|
6971 @cindex symbol
|
|
428
|
6972
|
|
442
|
6973 Symbols are also allocated in frob blocks. Symbols in the awful
|
|
|
6974 horrible obarray structure are chained through their @code{next} field.
|
|
428
|
6975
|
|
|
6976 Remember that @code{intern} looks up a symbol in an obarray, creating
|
|
|
6977 one if necessary.
|
|
|
6978
|
|
462
|
6979 @node Marker
|
|
428
|
6980 @section Marker
|
|
462
|
6981 @cindex marker
|
|
428
|
6982
|
|
|
6983 Markers are allocated in frob blocks, as usual. They are kept
|
|
|
6984 in a buffer unordered, but in a doubly-linked list so that they
|
|
|
6985 can easily be removed. (Formerly this was a singly-linked list,
|
|
|
6986 but in some cases garbage collection took an extraordinarily
|
|
|
6987 long time due to the O(N^2) time required to remove lots of
|
|
|
6988 markers from a buffer.) Markers are removed from a buffer in
|
|
|
6989 the finalize stage, in @code{ADDITIONAL_FREE_marker()}.
|
|
|
6990
|
|
462
|
6991 @node String
|
|
428
|
6992 @section String
|
|
462
|
6993 @cindex string
|
|
428
|
6994
|
|
|
6995 As mentioned above, strings are a special case. A string is logically
|
|
|
6996 two parts, a fixed-size object (containing the length, property list,
|
|
|
6997 and a pointer to the actual data), and the actual data in the string.
|
|
|
6998 The fixed-size object is a @code{struct Lisp_String} and is allocated in
|
|
|
6999 frob blocks, as usual. The actual data is stored in special
|
|
|
7000 @dfn{string-chars blocks}, which are 8K blocks of memory.
|
|
|
7001 Currently-allocated strings are simply laid end to end in these
|
|
|
7002 string-chars blocks, with a pointer back to the @code{struct Lisp_String}
|
|
|
7003 stored before each string in the string-chars block. When a new string
|
|
|
7004 needs to be allocated, the remaining space at the end of the last
|
|
|
7005 string-chars block is used if there's enough, and a new string-chars
|
|
|
7006 block is created otherwise.
|
|
|
7007
|
|
|
7008 There are never any holes in the string-chars blocks due to the string
|
|
|
7009 compaction and relocation that happens at the end of garbage collection.
|
|
|
7010 During the sweep stage of garbage collection, when objects are
|
|
|
7011 reclaimed, the garbage collector goes through all string-chars blocks,
|
|
|
7012 looking for unused strings. Each chunk of string data is preceded by a
|
|
|
7013 pointer to the corresponding @code{struct Lisp_String}, which indicates
|
|
|
7014 both whether the string is used and how big the string is, i.e. how to
|
|
|
7015 get to the next chunk of string data. Holes are compressed by
|
|
|
7016 block-copying the next string into the empty space and relocating the
|
|
|
7017 pointer stored in the corresponding @code{struct Lisp_String}.
|
|
|
7018 @strong{This means you have to be careful with strings in your code.}
|
|
|
7019 See the section above on @code{GCPRO}ing.
|
|
|
7020
|
|
|
7021 Note that there is one situation not handled: a string that is too big
|
|
|
7022 to fit into a string-chars block. Such strings, called @dfn{big
|
|
|
7023 strings}, are all @code{malloc()}ed as their own block. (#### Although it
|
|
|
7024 would make more sense for the threshold for big strings to be somewhat
|
|
|
7025 lower, e.g. 1/2 or 1/4 the size of a string-chars block. It seems that
|
|
440
|
7026 this was indeed the case formerly---indeed, the threshold was set at
|
|
|
7027 1/8---but Mly forgot about this when rewriting things for 19.8.)
|
|
428
|
7028
|
|
|
7029 Note also that the string data in string-chars blocks is padded as
|
|
|
7030 necessary so that proper alignment constraints on the @code{struct
|
|
|
7031 Lisp_String} back pointers are maintained.
|
|
|
7032
|
|
|
7033 Finally, strings can be resized. This happens in Mule when a
|
|
|
7034 character is substituted with a different-length character, or during
|
|
|
7035 modeline frobbing. (You could also export this to Lisp, but it's not
|
|
|
7036 done so currently.) Resizing a string is a potentially tricky process.
|
|
|
7037 If the change is small enough that the padding can absorb it, nothing
|
|
|
7038 other than a simple memory move needs to be done. Keep in mind,
|
|
|
7039 however, that the string can't shrink too much because the offset to the
|
|
|
7040 next string in the string-chars block is computed by looking at the
|
|
|
7041 length and rounding to the nearest multiple of four or eight. If the
|
|
|
7042 string would shrink or expand beyond the correct padding, new string
|
|
|
7043 data needs to be allocated at the end of the last string-chars block and
|
|
|
7044 the data moved appropriately. This leaves some dead string data, which
|
|
|
7045 is marked by putting a special marker of 0xFFFFFFFF in the @code{struct
|
|
|
7046 Lisp_String} pointer before the data (there's no real @code{struct
|
|
|
7047 Lisp_String} to point to and relocate), and storing the size of the dead
|
|
|
7048 string data (which would normally be obtained from the now-non-existent
|
|
|
7049 @code{struct Lisp_String}) at the beginning of the dead string data gap.
|
|
|
7050 The string compactor recognizes this special 0xFFFFFFFF marker and
|
|
|
7051 handles it correctly.
|
|
|
7052
|
|
462
|
7053 @node Compiled Function
|
|
428
|
7054 @section Compiled Function
|
|
462
|
7055 @cindex compiled function
|
|
|
7056 @cindex function, compiled
|
|
428
|
7057
|
|
|
7058 Not yet documented.
|
|
|
7059
|
|
442
|
7060
|
|
|
7061 @node Dumping, Events and the Event Loop, Allocation of Objects in XEmacs Lisp, Top
|
|
|
7062 @chapter Dumping
|
|
462
|
7063 @cindex dumping
|
|
442
|
7064
|
|
|
7065 @section What is dumping and its justification
|
|
462
|
7066 @cindex dumping and its justification, what is
|
|
442
|
7067
|
|
|
7068 The C code of XEmacs is just a Lisp engine with a lot of built-in
|
|
|
7069 primitives useful for writing an editor. The editor itself is written
|
|
|
7070 mostly in Lisp, and represents around 100K lines of code. Loading and
|
|
|
7071 executing the initialization of all this code takes a bit a time (five
|
|
|
7072 to ten times the usual startup time of current xemacs) and requires
|
|
|
7073 having all the lisp source files around. Having to reload them each
|
|
|
7074 time the editor is started would not be acceptable.
|
|
|
7075
|
|
|
7076 The traditional solution to this problem is called dumping: the build
|
|
|
7077 process first creates the lisp engine under the name @file{temacs}, then
|
|
|
7078 runs it until it has finished loading and initializing all the lisp
|
|
|
7079 code, and eventually creates a new executable called @file{xemacs}
|
|
|
7080 including both the object code in @file{temacs} and all the contents of
|
|
|
7081 the memory after the initialization.
|
|
|
7082
|
|
|
7083 This solution, while working, has a huge problem: the creation of the
|
|
|
7084 new executable from the actual contents of memory is an extremely
|
|
|
7085 system-specific process, quite error-prone, and which interferes with a
|
|
|
7086 lot of system libraries (like malloc). It is even getting worse
|
|
|
7087 nowadays with libraries using constructors which are automatically
|
|
|
7088 called when the program is started (even before main()) which tend to
|
|
|
7089 crash when they are called multiple times, once before dumping and once
|
|
|
7090 after (IRIX 6.x libz.so pulls in some C++ image libraries thru
|
|
|
7091 dependencies which have this problem). Writing the dumper is also one
|
|
|
7092 of the most difficult parts of porting XEmacs to a new operating system.
|
|
|
7093 Basically, `dumping' is an operation that is just not officially
|
|
|
7094 supported on many operating systems.
|
|
|
7095
|
|
|
7096 The aim of the portable dumper is to solve the same problem as the
|
|
|
7097 system-specific dumper, that is to be able to reload quickly, using only
|
|
|
7098 a small number of files, the fully initialized lisp part of the editor,
|
|
|
7099 without any system-specific hacks.
|
|
|
7100
|
|
|
7101 @menu
|
|
|
7102 * Overview::
|
|
|
7103 * Data descriptions::
|
|
|
7104 * Dumping phase::
|
|
|
7105 * Reloading phase::
|
|
|
7106 * Remaining issues::
|
|
|
7107 @end menu
|
|
|
7108
|
|
462
|
7109 @node Overview
|
|
442
|
7110 @section Overview
|
|
462
|
7111 @cindex dumping overview
|
|
442
|
7112
|
|
|
7113 The portable dumping system has to:
|
|
|
7114
|
|
|
7115 @enumerate
|
|
|
7116 @item
|
|
|
7117 At dump time, write all initialized, non-quickly-rebuildable data to a
|
|
|
7118 file [Note: currently named @file{xemacs.dmp}, but the name will
|
|
|
7119 change], along with all informations needed for the reloading.
|
|
|
7120
|
|
|
7121 @item
|
|
|
7122 When starting xemacs, reload the dump file, relocate it to its new
|
|
|
7123 starting address if needed, and reinitialize all pointers to this
|
|
|
7124 data. Also, rebuild all the quickly rebuildable data.
|
|
|
7125 @end enumerate
|
|
|
7126
|
|
462
|
7127 @node Data descriptions
|
|
442
|
7128 @section Data descriptions
|
|
462
|
7129 @cindex dumping data descriptions
|
|
442
|
7130
|
|
|
7131 The more complex task of the dumper is to be able to write lisp objects
|
|
|
7132 (lrecords) and C structs to disk and reload them at a different address,
|
|
|
7133 updating all the pointers they include in the process. This is done by
|
|
|
7134 using external data descriptions that give information about the layout
|
|
|
7135 of the structures in memory.
|
|
|
7136
|
|
|
7137 The specification of these descriptions is in lrecord.h. A description
|
|
|
7138 of an lrecord is an array of struct lrecord_description. Each of these
|
|
|
7139 structs include a type, an offset in the structure and some optional
|
|
|
7140 parameters depending on the type. For instance, here is the string
|
|
|
7141 description:
|
|
|
7142
|
|
|
7143 @example
|
|
|
7144 static const struct lrecord_description string_description[] = @{
|
|
|
7145 @{ XD_BYTECOUNT, offsetof (Lisp_String, size) @},
|
|
|
7146 @{ XD_OPAQUE_DATA_PTR, offsetof (Lisp_String, data), XD_INDIRECT(0, 1) @},
|
|
|
7147 @{ XD_LISP_OBJECT, offsetof (Lisp_String, plist) @},
|
|
|
7148 @{ XD_END @}
|
|
|
7149 @};
|
|
|
7150 @end example
|
|
|
7151
|
|
|
7152 The first line indicates a member of type Bytecount, which is used by
|
|
|
7153 the next, indirect directive. The second means "there is a pointer to
|
|
|
7154 some opaque data in the field @code{data}". The length of said data is
|
|
|
7155 given by the expression @code{XD_INDIRECT(0, 1)}, which means "the value
|
|
|
7156 in the 0th line of the description (welcome to C) plus one". The third
|
|
|
7157 line means "there is a Lisp_Object member @code{plist} in the Lisp_String
|
|
|
7158 structure". @code{XD_END} then ends the description.
|
|
|
7159
|
|
|
7160 This gives us all the information we need to move around what is pointed
|
|
|
7161 to by a structure (C or lrecord) and, by transitivity, everything that
|
|
|
7162 it points to. The only missing information for dumping is the size of
|
|
|
7163 the structure. For lrecords, this is part of the
|
|
|
7164 lrecord_implementation, so we don't need to duplicate it. For C
|
|
|
7165 structures we use a struct struct_description, which includes a size
|
|
|
7166 field and a pointer to an associated array of lrecord_description.
|
|
|
7167
|
|
462
|
7168 @node Dumping phase
|
|
442
|
7169 @section Dumping phase
|
|
462
|
7170 @cindex dumping phase
|
|
442
|
7171
|
|
|
7172 Dumping is done by calling the function pdump() (in dumper.c) which is
|
|
|
7173 invoked from Fdump_emacs (in emacs.c). This function performs a number
|
|
|
7174 of tasks.
|
|
|
7175
|
|
|
7176 @menu
|
|
|
7177 * Object inventory::
|
|
|
7178 * Address allocation::
|
|
|
7179 * The header::
|
|
|
7180 * Data dumping::
|
|
|
7181 * Pointers dumping::
|
|
|
7182 @end menu
|
|
|
7183
|
|
462
|
7184 @node Object inventory
|
|
442
|
7185 @subsection Object inventory
|
|
462
|
7186 @cindex dumping object inventory
|
|
442
|
7187
|
|
|
7188 The first task is to build the list of the objects to dump. This
|
|
|
7189 includes:
|
|
|
7190
|
|
|
7191 @itemize @bullet
|
|
|
7192 @item lisp objects
|
|
|
7193 @item C structures
|
|
|
7194 @end itemize
|
|
|
7195
|
|
|
7196 We end up with one @code{pdump_entry_list_elmt} per object group (arrays
|
|
|
7197 of C structs are kept together) which includes a pointer to the first
|
|
|
7198 object of the group, the per-object size and the count of objects in the
|
|
|
7199 group, along with some other information which is initialized later.
|
|
|
7200
|
|
|
7201 These entries are linked together in @code{pdump_entry_list} structures
|
|
|
7202 and can be enumerated thru either:
|
|
|
7203
|
|
|
7204 @enumerate
|
|
|
7205 @item
|
|
|
7206 the @code{pdump_object_table}, an array of @code{pdump_entry_list}, one
|
|
|
7207 per lrecord type, indexed by type number.
|
|
|
7208
|
|
|
7209 @item
|
|
|
7210 the @code{pdump_opaque_data_list}, used for the opaque data which does
|
|
|
7211 not include pointers, and hence does not need descriptions.
|
|
|
7212
|
|
|
7213 @item
|
|
|
7214 the @code{pdump_struct_table}, which is a vector of
|
|
|
7215 @code{struct_description}/@code{pdump_entry_list} pairs, used for
|
|
|
7216 non-opaque C structures.
|
|
|
7217 @end enumerate
|
|
|
7218
|
|
|
7219 This uses a marking strategy similar to the garbage collector. Some
|
|
|
7220 differences though:
|
|
|
7221
|
|
|
7222 @enumerate
|
|
|
7223 @item
|
|
|
7224 We do not use the mark bit (which does not exist for C structures
|
|
448
|
7225 anyway); we use a big hash table instead.
|
|
442
|
7226
|
|
|
7227 @item
|
|
|
7228 We do not use the mark function of lrecords but instead rely on the
|
|
|
7229 external descriptions. This happens essentially because we need to
|
|
|
7230 follow pointers to C structures and opaque data in addition to
|
|
|
7231 Lisp_Object members.
|
|
|
7232 @end enumerate
|
|
|
7233
|
|
452
|
7234 This is done by @code{pdump_register_object()}, which handles Lisp_Object
|
|
|
7235 variables, and @code{pdump_register_struct()} which handles C structures,
|
|
|
7236 which both delegate the description management to @code{pdump_register_sub()}.
|
|
442
|
7237
|
|
|
7238 The hash table doubles as a map object to pdump_entry_list_elmt (i.e.
|
|
|
7239 allows us to look up a pdump_entry_list_elmt with the object it points
|
|
|
7240 to). Entries are added with @code{pdump_add_entry()} and looked up with
|
|
|
7241 @code{pdump_get_entry()}. There is no need for entry removal. The hash
|
|
448
|
7242 value is computed quite simply from the object pointer by
|
|
442
|
7243 @code{pdump_make_hash()}.
|
|
|
7244
|
|
|
7245 The roots for the marking are:
|
|
|
7246
|
|
|
7247 @enumerate
|
|
|
7248 @item
|
|
|
7249 the @code{staticpro}'ed variables (there is a special @code{staticpro_nodump()}
|
|
|
7250 call for protected variables we do not want to dump).
|
|
|
7251
|
|
|
7252 @item
|
|
452
|
7253 the variables registered via @code{dump_add_root_object}
|
|
|
7254 (@code{staticpro()} is equivalent to @code{staticpro_nodump()} +
|
|
|
7255 @code{dump_add_root_object()}).
|
|
|
7256
|
|
|
7257 @item
|
|
|
7258 the variables registered via @code{dump_add_root_struct_ptr}, each of
|
|
|
7259 which points to a C structure.
|
|
442
|
7260 @end enumerate
|
|
|
7261
|
|
|
7262 This does not include the GCPRO'ed variables, the specbinds, the
|
|
|
7263 catchtags, the backlist, the redisplay or the profiling info, since we
|
|
|
7264 do not want to rebuild the actual chain of lisp calls which end up to
|
|
|
7265 the dump-emacs call, only the global variables.
|
|
|
7266
|
|
|
7267 Weak lists and weak hash tables are dumped as if they were their
|
|
|
7268 non-weak equivalent (without changing their type, of course). This has
|
|
|
7269 not yet been a problem.
|
|
|
7270
|
|
462
|
7271 @node Address allocation
|
|
442
|
7272 @subsection Address allocation
|
|
462
|
7273 @cindex dumping address allocation
|
|
442
|
7274
|
|
|
7275
|
|
|
7276 The next step is to allocate the offsets of each of the objects in the
|
|
|
7277 final dump file. This is done by @code{pdump_allocate_offset()} which
|
|
|
7278 is called indirectly by @code{pdump_scan_by_alignment()}.
|
|
|
7279
|
|
|
7280 The strategy to deal with alignment problems uses these facts:
|
|
|
7281
|
|
|
7282 @enumerate
|
|
|
7283 @item
|
|
|
7284 real world alignment requirements are powers of two.
|
|
|
7285
|
|
|
7286 @item
|
|
|
7287 the C compiler is required to adjust the size of a struct so that you
|
|
448
|
7288 can have an array of them next to each other. This means you can have an
|
|
442
|
7289 upper bound of the alignment requirements of a given structure by
|
|
|
7290 looking at which power of two its size is a multiple.
|
|
|
7291
|
|
|
7292 @item
|
|
|
7293 the non-variant part of variable size lrecords has an alignment
|
|
|
7294 requirement of 4.
|
|
|
7295 @end enumerate
|
|
|
7296
|
|
|
7297 Hence, for each lrecord type, C struct type or opaque data block the
|
|
|
7298 alignment requirement is computed as a power of two, with a minimum of
|
|
|
7299 2^2 for lrecords. @code{pdump_scan_by_alignment()} then scans all the
|
|
|
7300 @code{pdump_entry_list_elmt}'s, the ones with the highest requirements
|
|
|
7301 first. This ensures the best packing.
|
|
|
7302
|
|
|
7303 The maximum alignment requirement we take into account is 2^8.
|
|
|
7304
|
|
|
7305 @code{pdump_allocate_offset()} only has to do a linear allocation,
|
|
448
|
7306 starting at offset 256 (this leaves room for the header and keeps the
|
|
442
|
7307 alignments happy).
|
|
|
7308
|
|
462
|
7309 @node The header
|
|
442
|
7310 @subsection The header
|
|
462
|
7311 @cindex dumping, the header
|
|
442
|
7312
|
|
|
7313 The next step creates the file and writes a header with a signature and
|
|
452
|
7314 some random information in it. The @code{reloc_address} field, which
|
|
|
7315 indicates at which address the file should be loaded if we want to avoid
|
|
|
7316 post-reload relocation, is set to 0. It then seeks to offset 256 (base
|
|
|
7317 offset for the objects).
|
|
442
|
7318
|
|
462
|
7319 @node Data dumping
|
|
442
|
7320 @subsection Data dumping
|
|
462
|
7321 @cindex data dumping
|
|
|
7322 @cindex dumping, data
|
|
442
|
7323
|
|
|
7324 The data is dumped in the same order as the addresses were allocated by
|
|
|
7325 @code{pdump_dump_data()}, called from @code{pdump_scan_by_alignment()}.
|
|
|
7326 This function copies the data to a temporary buffer, relocates all
|
|
|
7327 pointers in the object to the addresses allocated in step Address
|
|
|
7328 Allocation, and writes it to the file. Using the same order means that,
|
|
|
7329 if we are careful with lrecords whose size is not a multiple of 4, we
|
|
|
7330 are ensured that the object is always written at the offset in the file
|
|
|
7331 allocated in step Address Allocation.
|
|
|
7332
|
|
462
|
7333 @node Pointers dumping
|
|
442
|
7334 @subsection Pointers dumping
|
|
462
|
7335 @cindex pointers dumping
|
|
|
7336 @cindex dumping, pointers
|
|
442
|
7337
|
|
|
7338 A bunch of tables needed to reassign properly the global pointers are
|
|
|
7339 then written. They are:
|
|
|
7340
|
|
|
7341 @enumerate
|
|
|
7342 @item
|
|
452
|
7343 the pdump_root_struct_ptrs dynarr
|
|
|
7344 @item
|
|
|
7345 the pdump_opaques dynarr
|
|
442
|
7346 @item
|
|
|
7347 a vector of all the offsets to the objects in the file that include a
|
|
|
7348 description (for faster relocation at reload time)
|
|
|
7349 @item
|
|
452
|
7350 the pdump_root_objects and pdump_weak_object_chains dynarrs.
|
|
442
|
7351 @end enumerate
|
|
|
7352
|
|
452
|
7353 For each of the dynarrs we write both the pointer to the variables and
|
|
442
|
7354 the relocated offset of the object they point to. Since these variables
|
|
|
7355 are global, the pointers are still valid when restarting the program and
|
|
|
7356 are used to regenerate the global pointers.
|
|
|
7357
|
|
452
|
7358 The @code{pdump_weak_object_chains} dynarr is a special case. The
|
|
|
7359 variables it points to are the head of weak linked lists of lisp objects
|
|
|
7360 of the same type. Not all objects of this list are dumped so the
|
|
|
7361 relocated pointer we associate with them points to the first dumped
|
|
|
7362 object of the list, or Qnil if none is available. This is also the
|
|
|
7363 reason why they are not used as roots for the purpose of object
|
|
|
7364 enumeration.
|
|
|
7365
|
|
|
7366 Some very important information like the @code{staticpros} and
|
|
|
7367 @code{lrecord_implementations_table} are handled indirectly using
|
|
|
7368 @code{dump_add_opaque} or @code{dump_add_root_struct_ptr}.
|
|
442
|
7369
|
|
|
7370 This is the end of the dumping part.
|
|
|
7371
|
|
462
|
7372 @node Reloading phase
|
|
442
|
7373 @section Reloading phase
|
|
462
|
7374 @cindex reloading phase
|
|
|
7375 @cindex dumping, reloading phase
|
|
442
|
7376
|
|
|
7377 @subsection File loading
|
|
462
|
7378 @cindex dumping, file loading
|
|
442
|
7379
|
|
|
7380 The file is mmap'ed in memory (which ensures a PAGESIZE alignment, at
|
|
|
7381 least 4096), or if mmap is unavailable or fails, a 256-bytes aligned
|
|
|
7382 malloc is done and the file is loaded.
|
|
|
7383
|
|
|
7384 Some variables are reinitialized from the values found in the header.
|
|
|
7385
|
|
|
7386 The difference between the actual loading address and the reloc_address
|
|
|
7387 is computed and will be used for all the relocations.
|
|
|
7388
|
|
|
7389
|
|
452
|
7390 @subsection Putting back the pdump_opaques
|
|
462
|
7391 @cindex dumping, putting back the pdump_opaques
|
|
452
|
7392
|
|
|
7393 The memory contents are restored in the obvious and trivial way.
|
|
|
7394
|
|
|
7395
|
|
|
7396 @subsection Putting back the pdump_root_struct_ptrs
|
|
462
|
7397 @cindex dumping, putting back the pdump_root_struct_ptrs
|
|
452
|
7398
|
|
|
7399 The variables pointed to by pdump_root_struct_ptrs in the dump phase are
|
|
|
7400 reset to the right relocated object addresses.
|
|
442
|
7401
|
|
|
7402
|
|
|
7403 @subsection Object relocation
|
|
462
|
7404 @cindex dumping, object relocation
|
|
442
|
7405
|
|
|
7406 All the objects are relocated using their description and their offset
|
|
|
7407 by @code{pdump_reloc_one}. This step is unnecessary if the
|
|
|
7408 reloc_address is equal to the file loading address.
|
|
|
7409
|
|
|
7410
|
|
452
|
7411 @subsection Putting back the pdump_root_objects and pdump_weak_object_chains
|
|
462
|
7412 @cindex dumping, putting back the pdump_root_objects and pdump_weak_object_chains
|
|
452
|
7413
|
|
|
7414 Same as Putting back the pdump_root_struct_ptrs.
|
|
442
|
7415
|
|
|
7416
|
|
|
7417 @subsection Reorganize the hash tables
|
|
462
|
7418 @cindex dumping, reorganize the hash tables
|
|
442
|
7419
|
|
|
7420 Since some of the hash values in the lisp hash tables are
|
|
|
7421 address-dependent, their layout is now wrong. So we go through each of
|
|
|
7422 them and have them resorted by calling @code{pdump_reorganize_hash_table}.
|
|
|
7423
|
|
462
|
7424 @node Remaining issues
|
|
442
|
7425 @section Remaining issues
|
|
462
|
7426 @cindex dumping, remaining issues
|
|
442
|
7427
|
|
|
7428 The build process will have to start a post-dump xemacs, ask it the
|
|
|
7429 loading address (which will, hopefully, be always the same between
|
|
|
7430 different xemacs invocations) and relocate the file to the new address.
|
|
|
7431 This way the object relocation phase will not have to be done, which
|
|
|
7432 means no writes in the objects and that, because of the use of mmap, the
|
|
|
7433 dumped data will be shared between all the xemacs running on the
|
|
|
7434 computer.
|
|
|
7435
|
|
|
7436 Some executable signature will be necessary to ensure that a given dump
|
|
|
7437 file is really associated with a given executable, or random crashes
|
|
|
7438 will occur. Maybe a random number set at compile or configure time thru
|
|
|
7439 a define. This will also allow for having differently-compiled xemacsen
|
|
|
7440 on the same system (mule and no-mule comes to mind).
|
|
|
7441
|
|
|
7442 The DOC file contents should probably end up in the dump file.
|
|
|
7443
|
|
|
7444
|
|
|
7445 @node Events and the Event Loop, Evaluation; Stack Frames; Bindings, Dumping, Top
|
|
428
|
7446 @chapter Events and the Event Loop
|
|
462
|
7447 @cindex events and the event loop
|
|
|
7448 @cindex event loop, events and the
|
|
428
|
7449
|
|
|
7450 @menu
|
|
|
7451 * Introduction to Events::
|
|
|
7452 * Main Loop::
|
|
|
7453 * Specifics of the Event Gathering Mechanism::
|
|
|
7454 * Specifics About the Emacs Event::
|
|
|
7455 * The Event Stream Callback Routines::
|
|
|
7456 * Other Event Loop Functions::
|
|
|
7457 * Converting Events::
|
|
|
7458 * Dispatching Events; The Command Builder::
|
|
|
7459 @end menu
|
|
|
7460
|
|
462
|
7461 @node Introduction to Events
|
|
428
|
7462 @section Introduction to Events
|
|
462
|
7463 @cindex events, introduction to
|
|
428
|
7464
|
|
|
7465 An event is an object that encapsulates information about an
|
|
|
7466 interesting occurrence in the operating system. Events are
|
|
|
7467 generated either by user action, direct (e.g. typing on the
|
|
|
7468 keyboard or moving the mouse) or indirect (moving another
|
|
|
7469 window, thereby generating an expose event on an Emacs frame),
|
|
|
7470 or as a result of some other typically asynchronous action happening,
|
|
|
7471 such as output from a subprocess being ready or a timer expiring.
|
|
|
7472 Events come into the system in an asynchronous fashion (typically
|
|
|
7473 through a callback being called) and are converted into a
|
|
|
7474 synchronous event queue (first-in, first-out) in a process that
|
|
|
7475 we will call @dfn{collection}.
|
|
|
7476
|
|
|
7477 Note that each application has its own event queue. (It is
|
|
|
7478 immaterial whether the collection process directly puts the
|
|
|
7479 events in the proper application's queue, or puts them into
|
|
|
7480 a single system queue, which is later split up.)
|
|
|
7481
|
|
|
7482 The most basic level of event collection is done by the
|
|
|
7483 operating system or window system. Typically, XEmacs does
|
|
|
7484 its own event collection as well. Often there are multiple
|
|
|
7485 layers of collection in XEmacs, with events from various
|
|
|
7486 sources being collected into a queue, which is then combined
|
|
|
7487 with other sources to go into another queue (i.e. a second
|
|
|
7488 level of collection), with perhaps another level on top of
|
|
|
7489 this, etc.
|
|
|
7490
|
|
|
7491 XEmacs has its own types of events (called @dfn{Emacs events}),
|
|
|
7492 which provides an abstract layer on top of the system-dependent
|
|
|
7493 nature of the most basic events that are received. Part of the
|
|
|
7494 complex nature of the XEmacs event collection process involves
|
|
|
7495 converting from the operating-system events into the proper
|
|
440
|
7496 Emacs events---there may not be a one-to-one correspondence.
|
|
428
|
7497
|
|
|
7498 Emacs events are documented in @file{events.h}; I'll discuss them
|
|
|
7499 later.
|
|
|
7500
|
|
462
|
7501 @node Main Loop
|
|
428
|
7502 @section Main Loop
|
|
462
|
7503 @cindex main loop
|
|
|
7504 @cindex events, main loop
|
|
428
|
7505
|
|
|
7506 The @dfn{command loop} is the top-level loop that the editor is always
|
|
|
7507 running. It loops endlessly, calling @code{next-event} to retrieve an
|
|
|
7508 event and @code{dispatch-event} to execute it. @code{dispatch-event} does
|
|
|
7509 the appropriate thing with non-user events (process, timeout,
|
|
|
7510 magic, eval, mouse motion); this involves calling a Lisp handler
|
|
|
7511 function, redrawing a newly-exposed part of a frame, reading
|
|
|
7512 subprocess output, etc. For user events, @code{dispatch-event}
|
|
|
7513 looks up the event in relevant keymaps or menubars; when a
|
|
|
7514 full key sequence or menubar selection is reached, the appropriate
|
|
|
7515 function is executed. @code{dispatch-event} may have to keep state
|
|
|
7516 across calls; this is done in the ``command-builder'' structure
|
|
|
7517 associated with each console (remember, there's usually only
|
|
|
7518 one console), and the engine that looks up keystrokes and
|
|
|
7519 constructs full key sequences is called the @dfn{command builder}.
|
|
|
7520 This is documented elsewhere.
|
|
|
7521
|
|
|
7522 The guts of the command loop are in @code{command_loop_1()}. This
|
|
440
|
7523 function doesn't catch errors, though---that's the job of
|
|
428
|
7524 @code{command_loop_2()}, which is a condition-case (i.e. error-trapping)
|
|
|
7525 wrapper around @code{command_loop_1()}. @code{command_loop_1()} never
|
|
|
7526 returns, but may get thrown out of.
|
|
|
7527
|
|
|
7528 When an error occurs, @code{cmd_error()} is called, which usually
|
|
|
7529 invokes the Lisp error handler in @code{command-error}; however, a
|
|
|
7530 default error handler is provided if @code{command-error} is @code{nil}
|
|
|
7531 (e.g. during startup). The purpose of the error handler is simply to
|
|
|
7532 display the error message and do associated cleanup; it does not need to
|
|
|
7533 throw anywhere. When the error handler finishes, the condition-case in
|
|
|
7534 @code{command_loop_2()} will finish and @code{command_loop_2()} will
|
|
|
7535 reinvoke @code{command_loop_1()}.
|
|
|
7536
|
|
|
7537 @code{command_loop_2()} is invoked from three places: from
|
|
|
7538 @code{initial_command_loop()} (called from @code{main()} at the end of
|
|
|
7539 internal initialization), from the Lisp function @code{recursive-edit},
|
|
|
7540 and from @code{call_command_loop()}.
|
|
|
7541
|
|
|
7542 @code{call_command_loop()} is called when a macro is started and when
|
|
|
7543 the minibuffer is entered; normal termination of the macro or minibuffer
|
|
|
7544 causes a throw out of the recursive command loop. (To
|
|
|
7545 @code{execute-kbd-macro} for macros and @code{exit} for minibuffers.
|
|
|
7546 Note also that the low-level minibuffer-entering function,
|
|
|
7547 @code{read-minibuffer-internal}, provides its own error handling and
|
|
|
7548 does not need @code{command_loop_2()}'s error encapsulation; so it tells
|
|
|
7549 @code{call_command_loop()} to invoke @code{command_loop_1()} directly.)
|
|
|
7550
|
|
|
7551 Note that both read-minibuffer-internal and recursive-edit set up a
|
|
|
7552 catch for @code{exit}; this is why @code{abort-recursive-edit}, which
|
|
|
7553 throws to this catch, exits out of either one.
|
|
|
7554
|
|
|
7555 @code{initial_command_loop()}, called from @code{main()}, sets up a
|
|
|
7556 catch for @code{top-level} when invoking @code{command_loop_2()},
|
|
|
7557 allowing functions to throw all the way to the top level if they really
|
|
|
7558 need to. Before invoking @code{command_loop_2()},
|
|
|
7559 @code{initial_command_loop()} calls @code{top_level_1()}, which handles
|
|
|
7560 all of the startup stuff (creating the initial frame, handling the
|
|
|
7561 command-line options, loading the user's @file{.emacs} file, etc.). The
|
|
|
7562 function that actually does this is in Lisp and is pointed to by the
|
|
|
7563 variable @code{top-level}; normally this function is
|
|
|
7564 @code{normal-top-level}. @code{top_level_1()} is just an error-handling
|
|
|
7565 wrapper similar to @code{command_loop_2()}. Note also that
|
|
|
7566 @code{initial_command_loop()} sets up a catch for @code{top-level} when
|
|
|
7567 invoking @code{top_level_1()}, just like when it invokes
|
|
|
7568 @code{command_loop_2()}.
|
|
|
7569
|
|
462
|
7570 @node Specifics of the Event Gathering Mechanism
|
|
428
|
7571 @section Specifics of the Event Gathering Mechanism
|
|
462
|
7572 @cindex event gathering mechanism, specifics of the
|
|
428
|
7573
|
|
|
7574 Here is an approximate diagram of the collection processes
|
|
|
7575 at work in XEmacs, under TTY's (TTY's are simpler than X
|
|
|
7576 so we'll look at this first):
|
|
|
7577
|
|
|
7578 @noindent
|
|
|
7579 @example
|
|
|
7580 asynch. asynch. asynch. asynch. [Collectors in
|
|
|
7581 kbd events kbd events process process the OS]
|
|
|
7582 | | output output
|
|
|
7583 | | | |
|
|
|
7584 | | | | SIGINT, [signal handlers
|
|
|
7585 | | | | SIGQUIT, in XEmacs]
|
|
|
7586 V V V V SIGWINCH,
|
|
|
7587 file file file file SIGALRM
|
|
|
7588 desc. desc. desc. desc. |
|
|
|
7589 (TTY) (TTY) (pipe) (pipe) |
|
|
|
7590 | | | | fake timeouts
|
|
|
7591 | | | | file |
|
|
|
7592 | | | | desc. |
|
|
|
7593 | | | | (pipe) |
|
|
|
7594 | | | | | |
|
|
|
7595 | | | | | |
|
|
|
7596 | | | | | |
|
|
|
7597 V V V V V V
|
|
|
7598 ------>-----------<----------------<----------------
|
|
|
7599 |
|
|
|
7600 |
|
|
|
7601 | [collected using select() in emacs_tty_next_event()
|
|
|
7602 | and converted to the appropriate Emacs event]
|
|
|
7603 |
|
|
|
7604 |
|
|
|
7605 V (above this line is TTY-specific)
|
|
|
7606 Emacs -----------------------------------------------
|
|
|
7607 event (below this line is the generic event mechanism)
|
|
|
7608 |
|
|
|
7609 |
|
|
|
7610 was there if not, call
|
|
|
7611 a SIGINT? emacs_tty_next_event()
|
|
|
7612 | |
|
|
|
7613 | |
|
|
|
7614 | |
|
|
|
7615 V V
|
|
|
7616 --->------<----
|
|
|
7617 |
|
|
|
7618 | [collected in event_stream_next_event();
|
|
|
7619 | SIGINT is converted using maybe_read_quit_event()]
|
|
|
7620 V
|
|
|
7621 Emacs
|
|
|
7622 event
|
|
|
7623 |
|
|
|
7624 \---->------>----- maybe_kbd_translate() ---->---\
|
|
|
7625 |
|
|
|
7626 |
|
|
|
7627 |
|
|
|
7628 command event queue |
|
|
|
7629 if not from command
|
|
|
7630 (contains events that were event queue, call
|
|
|
7631 read earlier but not processed, event_stream_next_event()
|
|
|
7632 typically when waiting in a |
|
|
|
7633 sit-for, sleep-for, etc. for |
|
|
|
7634 a particular event to be received) |
|
|
|
7635 | |
|
|
|
7636 | |
|
|
|
7637 V V
|
|
|
7638 ---->------------------------------------<----
|
|
|
7639 |
|
|
|
7640 | [collected in
|
|
|
7641 | next_event_internal()]
|
|
|
7642 |
|
|
|
7643 unread- unread- event from |
|
|
|
7644 command- command- keyboard else, call
|
|
|
7645 events event macro next_event_internal()
|
|
|
7646 | | | |
|
|
|
7647 | | | |
|
|
|
7648 | | | |
|
|
|
7649 V V V V
|
|
|
7650 --------->----------------------<------------
|
|
|
7651 |
|
|
|
7652 | [collected in `next-event', which may loop
|
|
|
7653 | more than once if the event it gets is on
|
|
|
7654 | a dead frame, device, etc.]
|
|
|
7655 |
|
|
|
7656 |
|
|
|
7657 V
|
|
|
7658 feed into top-level event loop,
|
|
|
7659 which repeatedly calls `next-event'
|
|
|
7660 and then dispatches the event
|
|
|
7661 using `dispatch-event'
|
|
|
7662 @end example
|
|
|
7663
|
|
|
7664 Notice the separation between TTY-specific and generic event mechanism.
|
|
|
7665 When using the Xt-based event loop, the TTY-specific stuff is replaced
|
|
|
7666 but the rest stays the same.
|
|
|
7667
|
|
|
7668 It's also important to realize that only one different kind of
|
|
|
7669 system-specific event loop can be operating at a time, and must be able
|
|
|
7670 to receive all kinds of events simultaneously. For the two existing
|
|
|
7671 event loops (implemented in @file{event-tty.c} and @file{event-Xt.c},
|
|
|
7672 respectively), the TTY event loop @emph{only} handles TTY consoles,
|
|
|
7673 while the Xt event loop handles @emph{both} TTY and X consoles. This
|
|
|
7674 situation is different from all of the output handlers, where you simply
|
|
|
7675 have one per console type.
|
|
|
7676
|
|
|
7677 Here's the Xt Event Loop Diagram (notice that below a certain point,
|
|
|
7678 it's the same as the above diagram):
|
|
|
7679
|
|
|
7680 @example
|
|
|
7681 asynch. asynch. asynch. asynch. [Collectors in
|
|
|
7682 kbd kbd process process the OS]
|
|
|
7683 events events output output
|
|
|
7684 | | | |
|
|
|
7685 | | | | asynch. asynch. [Collectors in the
|
|
|
7686 | | | | X X OS and X Window System]
|
|
|
7687 | | | | events events
|
|
|
7688 | | | | | |
|
|
|
7689 | | | | | |
|
|
|
7690 | | | | | | SIGINT, [signal handlers
|
|
|
7691 | | | | | | SIGQUIT, in XEmacs]
|
|
|
7692 | | | | | | SIGWINCH,
|
|
|
7693 | | | | | | SIGALRM
|
|
|
7694 | | | | | | |
|
|
|
7695 | | | | | | |
|
|
|
7696 | | | | | | | timeouts
|
|
|
7697 | | | | | | | |
|
|
|
7698 | | | | | | | |
|
|
|
7699 | | | | | | V |
|
|
|
7700 V V V V V V fake |
|
|
|
7701 file file file file file file file |
|
|
|
7702 desc. desc. desc. desc. desc. desc. desc. |
|
|
|
7703 (TTY) (TTY) (pipe) (pipe) (socket) (socket) (pipe) |
|
|
|
7704 | | | | | | | |
|
|
|
7705 | | | | | | | |
|
|
|
7706 | | | | | | | |
|
|
|
7707 V V V V V V V V
|
|
|
7708 --->----------------------------------------<---------<------
|
|
|
7709 | | |
|
|
|
7710 | | |[collected using select() in
|
|
|
7711 | | | _XtWaitForSomething(), called
|
|
|
7712 | | | from XtAppProcessEvent(), called
|
|
|
7713 | | | in emacs_Xt_next_event();
|
|
|
7714 | | | dispatched to various callbacks]
|
|
|
7715 | | |
|
|
|
7716 | | |
|
|
|
7717 emacs_Xt_ p_s_callback(), | [popup_selection_callback]
|
|
|
7718 event_handler() x_u_v_s_callback(),| [x_update_vertical_scrollbar_
|
|
|
7719 | x_u_h_s_callback(),| callback]
|
|
|
7720 | search_callback() | [x_update_horizontal_scrollbar_
|
|
|
7721 | | | callback]
|
|
|
7722 | | |
|
|
|
7723 | | |
|
|
|
7724 enqueue_Xt_ signal_special_ |
|
|
|
7725 dispatch_event() Xt_user_event() |
|
|
|
7726 [maybe multiple | |
|
|
|
7727 times, maybe 0 | |
|
|
|
7728 times] | |
|
|
|
7729 | enqueue_Xt_ |
|
|
|
7730 | dispatch_event() |
|
|
|
7731 | | |
|
|
|
7732 | | |
|
|
|
7733 V V |
|
|
|
7734 -->----------<-- |
|
|
|
7735 | |
|
|
|
7736 | |
|
|
|
7737 dispatch Xt_what_callback()
|
|
|
7738 event sets flags
|
|
|
7739 queue |
|
|
|
7740 | |
|
|
|
7741 | |
|
|
|
7742 | |
|
|
|
7743 | |
|
|
|
7744 ---->-----------<--------
|
|
|
7745 |
|
|
|
7746 |
|
|
|
7747 | [collected and converted as appropriate in
|
|
|
7748 | emacs_Xt_next_event()]
|
|
|
7749 |
|
|
|
7750 |
|
|
|
7751 V (above this line is Xt-specific)
|
|
|
7752 Emacs ------------------------------------------------
|
|
|
7753 event (below this line is the generic event mechanism)
|
|
|
7754 |
|
|
|
7755 |
|
|
|
7756 was there if not, call
|
|
|
7757 a SIGINT? emacs_Xt_next_event()
|
|
|
7758 | |
|
|
|
7759 | |
|
|
|
7760 | |
|
|
|
7761 V V
|
|
|
7762 --->-------<----
|
|
|
7763 |
|
|
|
7764 | [collected in event_stream_next_event();
|
|
|
7765 | SIGINT is converted using maybe_read_quit_event()]
|
|
|
7766 V
|
|
|
7767 Emacs
|
|
|
7768 event
|
|
|
7769 |
|
|
|
7770 \---->------>----- maybe_kbd_translate() -->-----\
|
|
|
7771 |
|
|
|
7772 |
|
|
|
7773 |
|
|
|
7774 command event queue |
|
|
|
7775 if not from command
|
|
|
7776 (contains events that were event queue, call
|
|
|
7777 read earlier but not processed, event_stream_next_event()
|
|
|
7778 typically when waiting in a |
|
|
|
7779 sit-for, sleep-for, etc. for |
|
|
|
7780 a particular event to be received) |
|
|
|
7781 | |
|
|
|
7782 | |
|
|
|
7783 V V
|
|
|
7784 ---->----------------------------------<------
|
|
|
7785 |
|
|
|
7786 | [collected in
|
|
|
7787 | next_event_internal()]
|
|
|
7788 |
|
|
|
7789 unread- unread- event from |
|
|
|
7790 command- command- keyboard else, call
|
|
|
7791 events event macro next_event_internal()
|
|
|
7792 | | | |
|
|
|
7793 | | | |
|
|
|
7794 | | | |
|
|
|
7795 V V V V
|
|
|
7796 --------->----------------------<------------
|
|
|
7797 |
|
|
|
7798 | [collected in `next-event', which may loop
|
|
|
7799 | more than once if the event it gets is on
|
|
|
7800 | a dead frame, device, etc.]
|
|
|
7801 |
|
|
|
7802 |
|
|
|
7803 V
|
|
|
7804 feed into top-level event loop,
|
|
|
7805 which repeatedly calls `next-event'
|
|
|
7806 and then dispatches the event
|
|
|
7807 using `dispatch-event'
|
|
|
7808 @end example
|
|
|
7809
|
|
462
|
7810 @node Specifics About the Emacs Event
|
|
428
|
7811 @section Specifics About the Emacs Event
|
|
462
|
7812 @cindex event, specifics about the Lisp object
|
|
|
7813
|
|
|
7814 @node The Event Stream Callback Routines
|
|
428
|
7815 @section The Event Stream Callback Routines
|
|
462
|
7816 @cindex event stream callback routines, the
|
|
|
7817 @cindex callback routines, the event stream
|
|
|
7818
|
|
|
7819 @node Other Event Loop Functions
|
|
428
|
7820 @section Other Event Loop Functions
|
|
462
|
7821 @cindex event loop functions, other
|
|
428
|
7822
|
|
|
7823 @code{detect_input_pending()} and @code{input-pending-p} look for
|
|
|
7824 input by calling @code{event_stream->event_pending_p} and looking in
|
|
|
7825 @code{[V]unread-command-event} and the @code{command_event_queue} (they
|
|
|
7826 do not check for an executing keyboard macro, though).
|
|
|
7827
|
|
|
7828 @code{discard-input} cancels any command events pending (and any
|
|
|
7829 keyboard macros currently executing), and puts the others onto the
|
|
|
7830 @code{command_event_queue}. There is a comment about a ``race
|
|
|
7831 condition'', which is not a good sign.
|
|
|
7832
|
|
|
7833 @code{next-command-event} and @code{read-char} are higher-level
|
|
|
7834 interfaces to @code{next-event}. @code{next-command-event} gets the
|
|
|
7835 next @dfn{command} event (i.e. keypress, mouse event, menu selection,
|
|
|
7836 or scrollbar action), calling @code{dispatch-event} on any others.
|
|
|
7837 @code{read-char} calls @code{next-command-event} and uses
|
|
|
7838 @code{event_to_character()} to return the character equivalent. With
|
|
|
7839 the right kind of input method support, it is possible for (read-char)
|
|
|
7840 to return a Kanji character.
|
|
|
7841
|
|
462
|
7842 @node Converting Events
|
|
428
|
7843 @section Converting Events
|
|
462
|
7844 @cindex converting events
|
|
|
7845 @cindex events, converting
|
|
428
|
7846
|
|
|
7847 @code{character_to_event()}, @code{event_to_character()},
|
|
|
7848 @code{event-to-character}, and @code{character-to-event} convert between
|
|
|
7849 characters and keypress events corresponding to the characters. If the
|
|
|
7850 event was not a keypress, @code{event_to_character()} returns -1 and
|
|
|
7851 @code{event-to-character} returns @code{nil}. These functions convert
|
|
|
7852 between character representation and the split-up event representation
|
|
|
7853 (keysym plus mod keys).
|
|
|
7854
|
|
462
|
7855 @node Dispatching Events; The Command Builder
|
|
428
|
7856 @section Dispatching Events; The Command Builder
|
|
462
|
7857 @cindex dispatching events; the command builder
|
|
|
7858 @cindex events; the command builder, dispatching
|
|
|
7859 @cindex command builder, dispatching events; the
|
|
428
|
7860
|
|
|
7861 Not yet documented.
|
|
|
7862
|
|
|
7863 @node Evaluation; Stack Frames; Bindings, Symbols and Variables, Events and the Event Loop, Top
|
|
|
7864 @chapter Evaluation; Stack Frames; Bindings
|
|
462
|
7865 @cindex evaluation; stack frames; bindings
|
|
|
7866 @cindex stack frames; bindings, evaluation;
|
|
|
7867 @cindex bindings, evaluation; stack frames;
|
|
428
|
7868
|
|
|
7869 @menu
|
|
|
7870 * Evaluation::
|
|
|
7871 * Dynamic Binding; The specbinding Stack; Unwind-Protects::
|
|
|
7872 * Simple Special Forms::
|
|
|
7873 * Catch and Throw::
|
|
|
7874 @end menu
|
|
|
7875
|
|
462
|
7876 @node Evaluation
|
|
428
|
7877 @section Evaluation
|
|
462
|
7878 @cindex evaluation
|
|
428
|
7879
|
|
|
7880 @code{Feval()} evaluates the form (a Lisp object) that is passed to
|
|
|
7881 it. Note that evaluation is only non-trivial for two types of objects:
|
|
|
7882 symbols and conses. A symbol is evaluated simply by calling
|
|
|
7883 @code{symbol-value} on it and returning the value.
|
|
|
7884
|
|
|
7885 Evaluating a cons means calling a function. First, @code{eval} checks
|
|
|
7886 to see if garbage-collection is necessary, and calls
|
|
|
7887 @code{garbage_collect_1()} if so. It then increases the evaluation
|
|
|
7888 depth by 1 (@code{lisp_eval_depth}, which is always less than
|
|
|
7889 @code{max_lisp_eval_depth}) and adds an element to the linked list of
|
|
|
7890 @code{struct backtrace}'s (@code{backtrace_list}). Each such structure
|
|
|
7891 contains a pointer to the function being called plus a list of the
|
|
|
7892 function's arguments. Originally these values are stored unevalled, and
|
|
|
7893 as they are evaluated, the backtrace structure is updated. Garbage
|
|
|
7894 collection pays attention to the objects pointed to in the backtrace
|
|
|
7895 structures (garbage collection might happen while a function is being
|
|
|
7896 called or while an argument is being evaluated, and there could easily
|
|
|
7897 be no other references to the arguments in the argument list; once an
|
|
|
7898 argument is evaluated, however, the unevalled version is not needed by
|
|
|
7899 eval, and so the backtrace structure is changed).
|
|
|
7900
|
|
|
7901 At this point, the function to be called is determined by looking at
|
|
|
7902 the car of the cons (if this is a symbol, its function definition is
|
|
|
7903 retrieved and the process repeated). The function should then consist
|
|
|
7904 of either a @code{Lisp_Subr} (built-in function written in C), a
|
|
|
7905 @code{Lisp_Compiled_Function} object, or a cons whose car is one of the
|
|
|
7906 symbols @code{autoload}, @code{macro} or @code{lambda}.
|
|
|
7907
|
|
|
7908 If the function is a @code{Lisp_Subr}, the lisp object points to a
|
|
|
7909 @code{struct Lisp_Subr} (created by @code{DEFUN()}), which contains a
|
|
|
7910 pointer to the C function, a minimum and maximum number of arguments
|
|
|
7911 (or possibly the special constants @code{MANY} or @code{UNEVALLED}), a
|
|
|
7912 pointer to the symbol referring to that subr, and a couple of other
|
|
|
7913 things. If the subr wants its arguments @code{UNEVALLED}, they are
|
|
|
7914 passed raw as a list. Otherwise, an array of evaluated arguments is
|
|
|
7915 created and put into the backtrace structure, and either passed whole
|
|
|
7916 (@code{MANY}) or each argument is passed as a C argument.
|
|
|
7917
|
|
|
7918 If the function is a @code{Lisp_Compiled_Function},
|
|
|
7919 @code{funcall_compiled_function()} is called. If the function is a
|
|
|
7920 lambda list, @code{funcall_lambda()} is called. If the function is a
|
|
|
7921 macro, [..... fill in] is done. If the function is an autoload,
|
|
|
7922 @code{do_autoload()} is called to load the definition and then eval
|
|
|
7923 starts over [explain this more].
|
|
|
7924
|
|
|
7925 When @code{Feval()} exits, the evaluation depth is reduced by one, the
|
|
|
7926 debugger is called if appropriate, and the current backtrace structure
|
|
|
7927 is removed from the list.
|
|
|
7928
|
|
|
7929 Both @code{funcall_compiled_function()} and @code{funcall_lambda()} need
|
|
|
7930 to go through the list of formal parameters to the function and bind
|
|
|
7931 them to the actual arguments, checking for @code{&rest} and
|
|
|
7932 @code{&optional} symbols in the formal parameters and making sure the
|
|
|
7933 number of actual arguments is correct.
|
|
|
7934 @code{funcall_compiled_function()} can do this a little more
|
|
|
7935 efficiently, since the formal parameter list can be checked for sanity
|
|
|
7936 when the compiled function object is created.
|
|
|
7937
|
|
|
7938 @code{funcall_lambda()} simply calls @code{Fprogn} to execute the code
|
|
|
7939 in the lambda list.
|
|
|
7940
|
|
|
7941 @code{funcall_compiled_function()} calls the real byte-code interpreter
|
|
|
7942 @code{execute_optimized_program()} on the byte-code instructions, which
|
|
|
7943 are converted into an internal form for faster execution.
|
|
|
7944
|
|
|
7945 When a compiled function is executed for the first time by
|
|
442
|
7946 @code{funcall_compiled_function()}, or during the dump phase of building
|
|
|
7947 XEmacs, the byte-code instructions are converted from a
|
|
|
7948 @code{Lisp_String} (which is inefficient to access, especially in the
|
|
|
7949 presence of MULE) into a @code{Lisp_Opaque} object containing an array
|
|
|
7950 of unsigned char, which can be directly executed by the byte-code
|
|
|
7951 interpreter. At this time the byte code is also analyzed for validity
|
|
|
7952 and transformed into a more optimized form, so that
|
|
428
|
7953 @code{execute_optimized_program()} can really fly.
|
|
|
7954
|
|
|
7955 Here are some of the optimizations performed by the internal byte-code
|
|
|
7956 transformer:
|
|
|
7957 @enumerate
|
|
|
7958 @item
|
|
|
7959 References to the @code{constants} array are checked for out-of-range
|
|
|
7960 indices, so that the byte interpreter doesn't have to.
|
|
|
7961 @item
|
|
|
7962 References to the @code{constants} array that will be used as a Lisp
|
|
|
7963 variable are checked for being correct non-constant (i.e. not @code{t},
|
|
|
7964 @code{nil}, or @code{keywordp}) symbols, so that the byte interpreter
|
|
|
7965 doesn't have to.
|
|
|
7966 @item
|
|
442
|
7967 The maximum number of variable bindings in the byte-code is
|
|
428
|
7968 pre-computed, so that space on the @code{specpdl} stack can be
|
|
|
7969 pre-reserved once for the whole function execution.
|
|
|
7970 @item
|
|
|
7971 All byte-code jumps are relative to the current program counter instead
|
|
|
7972 of the start of the program, thereby saving a register.
|
|
|
7973 @item
|
|
|
7974 One-byte relative jumps are converted from the byte-code form of unsigned
|
|
|
7975 chars offset by 127 to machine-friendly signed chars.
|
|
|
7976 @end enumerate
|
|
|
7977
|
|
|
7978 Of course, this transformation of the @code{instructions} should not be
|
|
|
7979 visible to the user, so @code{Fcompiled_function_instructions()} needs
|
|
|
7980 to know how to convert the optimized opaque object back into a Lisp
|
|
|
7981 string that is identical to the original string from the @file{.elc}
|
|
|
7982 file. (Actually, the resulting string may (rarely) contain slightly
|
|
|
7983 different, yet equivalent, byte code.)
|
|
|
7984
|
|
|
7985 @code{Ffuncall()} implements Lisp @code{funcall}. @code{(funcall fun
|
|
|
7986 x1 x2 x3 ...)} is equivalent to @code{(eval (list fun (quote x1) (quote
|
|
|
7987 x2) (quote x3) ...))}. @code{Ffuncall()} contains its own code to do
|
|
|
7988 the evaluation, however, and is very similar to @code{Feval()}.
|
|
|
7989
|
|
|
7990 From the performance point of view, it is worth knowing that most of the
|
|
|
7991 time in Lisp evaluation is spent executing @code{Lisp_Subr} and
|
|
|
7992 @code{Lisp_Compiled_Function} objects via @code{Ffuncall()} (not
|
|
|
7993 @code{Feval()}).
|
|
|
7994
|
|
|
7995 @code{Fapply()} implements Lisp @code{apply}, which is very similar to
|
|
|
7996 @code{funcall} except that if the last argument is a list, the result is the
|
|
|
7997 same as if each of the arguments in the list had been passed separately.
|
|
|
7998 @code{Fapply()} does some business to expand the last argument if it's a
|
|
|
7999 list, then calls @code{Ffuncall()} to do the work.
|
|
|
8000
|
|
|
8001 @code{apply1()}, @code{call0()}, @code{call1()}, @code{call2()}, and
|
|
|
8002 @code{call3()} call a function, passing it the argument(s) given (the
|
|
|
8003 arguments are given as separate C arguments rather than being passed as
|
|
|
8004 an array). @code{apply1()} uses @code{Fapply()} while the others use
|
|
|
8005 @code{Ffuncall()} to do the real work.
|
|
|
8006
|
|
462
|
8007 @node Dynamic Binding; The specbinding Stack; Unwind-Protects
|
|
428
|
8008 @section Dynamic Binding; The specbinding Stack; Unwind-Protects
|
|
462
|
8009 @cindex dynamic binding; the specbinding stack; unwind-protects
|
|
|
8010 @cindex binding; the specbinding stack; unwind-protects, dynamic
|
|
|
8011 @cindex specbinding stack; unwind-protects, dynamic binding; the
|
|
|
8012 @cindex unwind-protects, dynamic binding; the specbinding stack;
|
|
428
|
8013
|
|
|
8014 @example
|
|
|
8015 struct specbinding
|
|
|
8016 @{
|
|
|
8017 Lisp_Object symbol;
|
|
|
8018 Lisp_Object old_value;
|
|
|
8019 Lisp_Object (*func) (Lisp_Object); /* for unwind-protect */
|
|
|
8020 @};
|
|
|
8021 @end example
|
|
|
8022
|
|
|
8023 @code{struct specbinding} is used for local-variable bindings and
|
|
|
8024 unwind-protects. @code{specpdl} holds an array of @code{struct specbinding}'s,
|
|
|
8025 @code{specpdl_ptr} points to the beginning of the free bindings in the
|
|
|
8026 array, @code{specpdl_size} specifies the total number of binding slots
|
|
|
8027 in the array, and @code{max_specpdl_size} specifies the maximum number
|
|
|
8028 of bindings the array can be expanded to hold. @code{grow_specpdl()}
|
|
|
8029 increases the size of the @code{specpdl} array, multiplying its size by
|
|
|
8030 2 but never exceeding @code{max_specpdl_size} (except that if this
|
|
|
8031 number is less than 400, it is first set to 400).
|
|
|
8032
|
|
|
8033 @code{specbind()} binds a symbol to a value and is used for local
|
|
|
8034 variables and @code{let} forms. The symbol and its old value (which
|
|
|
8035 might be @code{Qunbound}, indicating no prior value) are recorded in the
|
|
|
8036 specpdl array, and @code{specpdl_size} is increased by 1.
|
|
|
8037
|
|
|
8038 @code{record_unwind_protect()} implements an @dfn{unwind-protect},
|
|
|
8039 which, when placed around a section of code, ensures that some specified
|
|
|
8040 cleanup routine will be executed even if the code exits abnormally
|
|
|
8041 (e.g. through a @code{throw} or quit). @code{record_unwind_protect()}
|
|
|
8042 simply adds a new specbinding to the @code{specpdl} array and stores the
|
|
|
8043 appropriate information in it. The cleanup routine can either be a C
|
|
|
8044 function, which is stored in the @code{func} field, or a @code{progn}
|
|
|
8045 form, which is stored in the @code{old_value} field.
|
|
|
8046
|
|
|
8047 @code{unbind_to()} removes specbindings from the @code{specpdl} array
|
|
|
8048 until the specified position is reached. Each specbinding can be one of
|
|
|
8049 three types:
|
|
|
8050
|
|
|
8051 @enumerate
|
|
|
8052 @item
|
|
|
8053 an unwind-protect with a C cleanup function (@code{func} is not 0, and
|
|
|
8054 @code{old_value} holds an argument to be passed to the function);
|
|
|
8055 @item
|
|
|
8056 an unwind-protect with a Lisp form (@code{func} is 0, @code{symbol}
|
|
|
8057 is @code{nil}, and @code{old_value} holds the form to be executed with
|
|
|
8058 @code{Fprogn()}); or
|
|
|
8059 @item
|
|
|
8060 a local-variable binding (@code{func} is 0, @code{symbol} is not
|
|
|
8061 @code{nil}, and @code{old_value} holds the old value, which is stored as
|
|
|
8062 the symbol's value).
|
|
|
8063 @end enumerate
|
|
|
8064
|
|
462
|
8065 @node Simple Special Forms
|
|
428
|
8066 @section Simple Special Forms
|
|
462
|
8067 @cindex special forms, simple
|
|
428
|
8068
|
|
|
8069 @code{or}, @code{and}, @code{if}, @code{cond}, @code{progn},
|
|
|
8070 @code{prog1}, @code{prog2}, @code{setq}, @code{quote}, @code{function},
|
|
|
8071 @code{let*}, @code{let}, @code{while}
|
|
|
8072
|
|
|
8073 All of these are very simple and work as expected, calling
|
|
|
8074 @code{Feval()} or @code{Fprogn()} as necessary and (in the case of
|
|
|
8075 @code{let} and @code{let*}) using @code{specbind()} to create bindings
|
|
|
8076 and @code{unbind_to()} to undo the bindings when finished.
|
|
|
8077
|
|
442
|
8078 Note that, with the exception of @code{Fprogn}, these functions are
|
|
428
|
8079 typically called in real life only in interpreted code, since the byte
|
|
|
8080 compiler knows how to convert calls to these functions directly into
|
|
|
8081 byte code.
|
|
|
8082
|
|
462
|
8083 @node Catch and Throw
|
|
428
|
8084 @section Catch and Throw
|
|
462
|
8085 @cindex catch and throw
|
|
|
8086 @cindex throw, catch and
|
|
428
|
8087
|
|
|
8088 @example
|
|
|
8089 struct catchtag
|
|
|
8090 @{
|
|
|
8091 Lisp_Object tag;
|
|
|
8092 Lisp_Object val;
|
|
|
8093 struct catchtag *next;
|
|
|
8094 struct gcpro *gcpro;
|
|
|
8095 jmp_buf jmp;
|
|
|
8096 struct backtrace *backlist;
|
|
|
8097 int lisp_eval_depth;
|
|
|
8098 int pdlcount;
|
|
|
8099 @};
|
|
|
8100 @end example
|
|
|
8101
|
|
|
8102 @code{catch} is a Lisp function that places a catch around a body of
|
|
|
8103 code. A catch is a means of non-local exit from the code. When a catch
|
|
|
8104 is created, a tag is specified, and executing a @code{throw} to this tag
|
|
|
8105 will exit from the body of code caught with this tag, and its value will
|
|
|
8106 be the value given in the call to @code{throw}. If there is no such
|
|
|
8107 call, the code will be executed normally.
|
|
|
8108
|
|
|
8109 Information pertaining to a catch is held in a @code{struct catchtag},
|
|
|
8110 which is placed at the head of a linked list pointed to by
|
|
|
8111 @code{catchlist}. @code{internal_catch()} is passed a C function to
|
|
|
8112 call (@code{Fprogn()} when Lisp @code{catch} is called) and arguments to
|
|
|
8113 give it, and places a catch around the function. Each @code{struct
|
|
|
8114 catchtag} is held in the stack frame of the @code{internal_catch()}
|
|
|
8115 instance that created the catch.
|
|
|
8116
|
|
|
8117 @code{internal_catch()} is fairly straightforward. It stores into the
|
|
|
8118 @code{struct catchtag} the tag name and the current values of
|
|
|
8119 @code{backtrace_list}, @code{lisp_eval_depth}, @code{gcprolist}, and the
|
|
|
8120 offset into the @code{specpdl} array, sets a jump point with @code{_setjmp()}
|
|
|
8121 (storing the jump point into the @code{struct catchtag}), and calls the
|
|
|
8122 function. Control will return to @code{internal_catch()} either when
|
|
|
8123 the function exits normally or through a @code{_longjmp()} to this jump
|
|
|
8124 point. In the latter case, @code{throw} will store the value to be
|
|
|
8125 returned into the @code{struct catchtag} before jumping. When it's
|
|
|
8126 done, @code{internal_catch()} removes the @code{struct catchtag} from
|
|
|
8127 the catchlist and returns the proper value.
|
|
|
8128
|
|
|
8129 @code{Fthrow()} goes up through the catchlist until it finds one with
|
|
|
8130 a matching tag. It then calls @code{unbind_catch()} to restore
|
|
|
8131 everything to what it was when the appropriate catch was set, stores the
|
|
|
8132 return value in the @code{struct catchtag}, and jumps (with
|
|
|
8133 @code{_longjmp()}) to its jump point.
|
|
|
8134
|
|
|
8135 @code{unbind_catch()} removes all catches from the catchlist until it
|
|
|
8136 finds the correct one. Some of the catches might have been placed for
|
|
|
8137 error-trapping, and if so, the appropriate entries on the handlerlist
|
|
|
8138 must be removed (see ``errors''). @code{unbind_catch()} also restores
|
|
|
8139 the values of @code{gcprolist}, @code{backtrace_list}, and
|
|
|
8140 @code{lisp_eval}, and calls @code{unbind_to()} to undo any specbindings
|
|
|
8141 created since the catch.
|
|
|
8142
|
|
|
8143
|
|
|
8144 @node Symbols and Variables, Buffers and Textual Representation, Evaluation; Stack Frames; Bindings, Top
|
|
|
8145 @chapter Symbols and Variables
|
|
462
|
8146 @cindex symbols and variables
|
|
|
8147 @cindex variables, symbols and
|
|
428
|
8148
|
|
|
8149 @menu
|
|
|
8150 * Introduction to Symbols::
|
|
|
8151 * Obarrays::
|
|
|
8152 * Symbol Values::
|
|
|
8153 @end menu
|
|
|
8154
|
|
462
|
8155 @node Introduction to Symbols
|
|
428
|
8156 @section Introduction to Symbols
|
|
462
|
8157 @cindex symbols, introduction to
|
|
428
|
8158
|
|
|
8159 A symbol is basically just an object with four fields: a name (a
|
|
|
8160 string), a value (some Lisp object), a function (some Lisp object), and
|
|
|
8161 a property list (usually a list of alternating keyword/value pairs).
|
|
|
8162 What makes symbols special is that there is usually only one symbol with
|
|
|
8163 a given name, and the symbol is referred to by name. This makes a
|
|
|
8164 symbol a convenient way of calling up data by name, i.e. of implementing
|
|
|
8165 variables. (The variable's value is stored in the @dfn{value slot}.)
|
|
|
8166 Similarly, functions are referenced by name, and the definition of the
|
|
|
8167 function is stored in a symbol's @dfn{function slot}. This means that
|
|
|
8168 there can be a distinct function and variable with the same name. The
|
|
|
8169 property list is used as a more general mechanism of associating
|
|
|
8170 additional values with particular names, and once again the namespace is
|
|
|
8171 independent of the function and variable namespaces.
|
|
|
8172
|
|
462
|
8173 @node Obarrays
|
|
428
|
8174 @section Obarrays
|
|
462
|
8175 @cindex obarrays
|
|
428
|
8176
|
|
|
8177 The identity of symbols with their names is accomplished through a
|
|
|
8178 structure called an obarray, which is just a poorly-implemented hash
|
|
|
8179 table mapping from strings to symbols whose name is that string. (I say
|
|
|
8180 ``poorly implemented'' because an obarray appears in Lisp as a vector
|
|
|
8181 with some hidden fields rather than as its own opaque type. This is an
|
|
|
8182 Emacs Lisp artifact that should be fixed.)
|
|
|
8183
|
|
|
8184 Obarrays are implemented as a vector of some fixed size (which should
|
|
|
8185 be a prime for best results), where each ``bucket'' of the vector
|
|
|
8186 contains one or more symbols, threaded through a hidden @code{next}
|
|
|
8187 field in the symbol. Lookup of a symbol in an obarray, and adding a
|
|
|
8188 symbol to an obarray, is accomplished through standard hash-table
|
|
|
8189 techniques.
|
|
|
8190
|
|
|
8191 The standard Lisp function for working with symbols and obarrays is
|
|
|
8192 @code{intern}. This looks up a symbol in an obarray given its name; if
|
|
|
8193 it's not found, a new symbol is automatically created with the specified
|
|
|
8194 name, added to the obarray, and returned. This is what happens when the
|
|
|
8195 Lisp reader encounters a symbol (or more precisely, encounters the name
|
|
|
8196 of a symbol) in some text that it is reading. There is a standard
|
|
|
8197 obarray called @code{obarray} that is used for this purpose, although
|
|
|
8198 the Lisp programmer is free to create his own obarrays and @code{intern}
|
|
|
8199 symbols in them.
|
|
|
8200
|
|
|
8201 Note that, once a symbol is in an obarray, it stays there until
|
|
|
8202 something is done about it, and the standard obarray @code{obarray}
|
|
|
8203 always stays around, so once you use any particular variable name, a
|
|
|
8204 corresponding symbol will stay around in @code{obarray} until you exit
|
|
|
8205 XEmacs.
|
|
|
8206
|
|
|
8207 Note that @code{obarray} itself is a variable, and as such there is a
|
|
|
8208 symbol in @code{obarray} whose name is @code{"obarray"} and which
|
|
|
8209 contains @code{obarray} as its value.
|
|
|
8210
|
|
|
8211 Note also that this call to @code{intern} occurs only when in the Lisp
|
|
|
8212 reader, not when the code is executed (at which point the symbol is
|
|
|
8213 already around, stored as such in the definition of the function).
|
|
|
8214
|
|
|
8215 You can create your own obarray using @code{make-vector} (this is
|
|
|
8216 horrible but is an artifact) and intern symbols into that obarray.
|
|
|
8217 Doing that will result in two or more symbols with the same name.
|
|
|
8218 However, at most one of these symbols is in the standard @code{obarray}:
|
|
|
8219 You cannot have two symbols of the same name in any particular obarray.
|
|
|
8220 Note that you cannot add a symbol to an obarray in any fashion other
|
|
|
8221 than using @code{intern}: i.e. you can't take an existing symbol and put
|
|
|
8222 it in an existing obarray. Nor can you change the name of an existing
|
|
|
8223 symbol. (Since obarrays are vectors, you can violate the consistency of
|
|
|
8224 things by storing directly into the vector, but let's ignore that
|
|
|
8225 possibility.)
|
|
|
8226
|
|
|
8227 Usually symbols are created by @code{intern}, but if you really want,
|
|
|
8228 you can explicitly create a symbol using @code{make-symbol}, giving it
|
|
|
8229 some name. The resulting symbol is not in any obarray (i.e. it is
|
|
|
8230 @dfn{uninterned}), and you can't add it to any obarray. Therefore its
|
|
|
8231 primary purpose is as a symbol to use in macros to avoid namespace
|
|
|
8232 pollution. It can also be used as a carrier of information, but cons
|
|
|
8233 cells could probably be used just as well.
|
|
|
8234
|
|
|
8235 You can also use @code{intern-soft} to look up a symbol but not create
|
|
|
8236 a new one, and @code{unintern} to remove a symbol from an obarray. This
|
|
|
8237 returns the removed symbol. (Remember: You can't put the symbol back
|
|
|
8238 into any obarray.) Finally, @code{mapatoms} maps over all of the symbols
|
|
|
8239 in an obarray.
|
|
|
8240
|
|
462
|
8241 @node Symbol Values
|
|
428
|
8242 @section Symbol Values
|
|
462
|
8243 @cindex symbol values
|
|
|
8244 @cindex values, symbol
|
|
428
|
8245
|
|
|
8246 The value field of a symbol normally contains a Lisp object. However,
|
|
|
8247 a symbol can be @dfn{unbound}, meaning that it logically has no value.
|
|
|
8248 This is internally indicated by storing a special Lisp object, called
|
|
|
8249 @dfn{the unbound marker} and stored in the global variable
|
|
|
8250 @code{Qunbound}. The unbound marker is of a special Lisp object type
|
|
|
8251 called @dfn{symbol-value-magic}. It is impossible for the Lisp
|
|
|
8252 programmer to directly create or access any object of this type.
|
|
|
8253
|
|
|
8254 @strong{You must not let any ``symbol-value-magic'' object escape to
|
|
|
8255 the Lisp level.} Printing any of these objects will cause the message
|
|
|
8256 @samp{INTERNAL EMACS BUG} to appear as part of the print representation.
|
|
|
8257 (You may see this normally when you call @code{debug_print()} from the
|
|
|
8258 debugger on a Lisp object.) If you let one of these objects escape to
|
|
|
8259 the Lisp level, you will violate a number of assumptions contained in
|
|
|
8260 the C code and make the unbound marker not function right.
|
|
|
8261
|
|
|
8262 When a symbol is created, its value field (and function field) are set
|
|
|
8263 to @code{Qunbound}. The Lisp programmer can restore these conditions
|
|
|
8264 later using @code{makunbound} or @code{fmakunbound}, and can query to
|
|
|
8265 see whether the value of function fields are @dfn{bound} (i.e. have a
|
|
|
8266 value other than @code{Qunbound}) using @code{boundp} and
|
|
|
8267 @code{fboundp}. The fields are set to a normal Lisp object using
|
|
|
8268 @code{set} (or @code{setq}) and @code{fset}.
|
|
|
8269
|
|
|
8270 Other symbol-value-magic objects are used as special markers to
|
|
|
8271 indicate variables that have non-normal properties. This includes any
|
|
|
8272 variables that are tied into C variables (setting the variable magically
|
|
|
8273 sets some global variable in the C code, and likewise for retrieving the
|
|
|
8274 variable's value), variables that magically tie into slots in the
|
|
|
8275 current buffer, variables that are buffer-local, etc. The
|
|
|
8276 symbol-value-magic object is stored in the value cell in place of
|
|
|
8277 a normal object, and the code to retrieve a symbol's value
|
|
|
8278 (i.e. @code{symbol-value}) knows how to do special things with them.
|
|
|
8279 This means that you should not just fetch the value cell directly if you
|
|
|
8280 want a symbol's value.
|
|
|
8281
|
|
|
8282 The exact workings of this are rather complex and involved and are
|
|
|
8283 well-documented in comments in @file{buffer.c}, @file{symbols.c}, and
|
|
|
8284 @file{lisp.h}.
|
|
|
8285
|
|
|
8286 @node Buffers and Textual Representation, MULE Character Sets and Encodings, Symbols and Variables, Top
|
|
|
8287 @chapter Buffers and Textual Representation
|
|
462
|
8288 @cindex buffers and textual representation
|
|
|
8289 @cindex textual representation, buffers and
|
|
428
|
8290
|
|
|
8291 @menu
|
|
|
8292 * Introduction to Buffers:: A buffer holds a block of text such as a file.
|
|
|
8293 * The Text in a Buffer:: Representation of the text in a buffer.
|
|
|
8294 * Buffer Lists:: Keeping track of all buffers.
|
|
|
8295 * Markers and Extents:: Tagging locations within a buffer.
|
|
1263
|
8296 * Ibytes and Ichars:: Representation of individual characters.
|
|
428
|
8297 * The Buffer Object:: The Lisp object corresponding to a buffer.
|
|
1496
|
8298 * Searching and Matching:: Higher-level algorithms.
|
|
428
|
8299 @end menu
|
|
|
8300
|
|
462
|
8301 @node Introduction to Buffers
|
|
428
|
8302 @section Introduction to Buffers
|
|
462
|
8303 @cindex buffers, introduction to
|
|
428
|
8304
|
|
|
8305 A buffer is logically just a Lisp object that holds some text.
|
|
|
8306 In this, it is like a string, but a buffer is optimized for
|
|
|
8307 frequent insertion and deletion, while a string is not. Furthermore:
|
|
|
8308
|
|
|
8309 @enumerate
|
|
|
8310 @item
|
|
|
8311 Buffers are @dfn{permanent} objects, i.e. once you create them, they
|
|
|
8312 remain around, and need to be explicitly deleted before they go away.
|
|
|
8313 @item
|
|
|
8314 Each buffer has a unique name, which is a string. Buffers are
|
|
|
8315 normally referred to by name. In this respect, they are like
|
|
|
8316 symbols.
|
|
|
8317 @item
|
|
|
8318 Buffers have a default insertion position, called @dfn{point}.
|
|
|
8319 Inserting text (unless you explicitly give a position) goes at point,
|
|
|
8320 and moves point forward past the text. This is what is going on when
|
|
|
8321 you type text into Emacs.
|
|
|
8322 @item
|
|
|
8323 Buffers have lots of extra properties associated with them.
|
|
|
8324 @item
|
|
|
8325 Buffers can be @dfn{displayed}. What this means is that there
|
|
|
8326 exist a number of @dfn{windows}, which are objects that correspond
|
|
|
8327 to some visible section of your display, and each window has
|
|
|
8328 an associated buffer, and the current contents of the buffer
|
|
|
8329 are shown in that section of the display. The redisplay mechanism
|
|
|
8330 (which takes care of doing this) knows how to look at the
|
|
|
8331 text of a buffer and come up with some reasonable way of displaying
|
|
|
8332 this. Many of the properties of a buffer control how the
|
|
|
8333 buffer's text is displayed.
|
|
|
8334 @item
|
|
|
8335 One buffer is distinguished and called the @dfn{current buffer}. It is
|
|
|
8336 stored in the variable @code{current_buffer}. Buffer operations operate
|
|
|
8337 on this buffer by default. When you are typing text into a buffer, the
|
|
|
8338 buffer you are typing into is always @code{current_buffer}. Switching
|
|
|
8339 to a different window changes the current buffer. Note that Lisp code
|
|
|
8340 can temporarily change the current buffer using @code{set-buffer} (often
|
|
|
8341 enclosed in a @code{save-excursion} so that the former current buffer
|
|
|
8342 gets restored when the code is finished). However, calling
|
|
|
8343 @code{set-buffer} will NOT cause a permanent change in the current
|
|
|
8344 buffer. The reason for this is that the top-level event loop sets
|
|
|
8345 @code{current_buffer} to the buffer of the selected window, each time
|
|
|
8346 it finishes executing a user command.
|
|
|
8347 @end enumerate
|
|
|
8348
|
|
|
8349 Make sure you understand the distinction between @dfn{current buffer}
|
|
|
8350 and @dfn{buffer of the selected window}, and the distinction between
|
|
|
8351 @dfn{point} of the current buffer and @dfn{window-point} of the selected
|
|
|
8352 window. (This latter distinction is explained in detail in the section
|
|
|
8353 on windows.)
|
|
|
8354
|
|
462
|
8355 @node The Text in a Buffer
|
|
428
|
8356 @section The Text in a Buffer
|
|
462
|
8357 @cindex text in a buffer, the
|
|
|
8358 @cindex buffer, the text in a
|
|
428
|
8359
|
|
|
8360 The text in a buffer consists of a sequence of zero or more
|
|
|
8361 characters. A @dfn{character} is an integer that logically represents
|
|
|
8362 a letter, number, space, or other unit of text. Most of the characters
|
|
|
8363 that you will typically encounter belong to the ASCII set of characters,
|
|
|
8364 but there are also characters for various sorts of accented letters,
|
|
|
8365 special symbols, Chinese and Japanese ideograms (i.e. Kanji, Katakana,
|
|
|
8366 etc.), Cyrillic and Greek letters, etc. The actual number of possible
|
|
|
8367 characters is quite large.
|
|
|
8368
|
|
|
8369 For now, we can view a character as some non-negative integer that
|
|
|
8370 has some shape that defines how it typically appears (e.g. as an
|
|
|
8371 uppercase A). (The exact way in which a character appears depends on the
|
|
|
8372 font used to display the character.) The internal type of characters in
|
|
1261
|
8373 the C code is an @code{Ichar}; this is just an @code{int}, but using a
|
|
428
|
8374 symbolic type makes the code clearer.
|
|
|
8375
|
|
|
8376 Between every character in a buffer is a @dfn{buffer position} or
|
|
|
8377 @dfn{character position}. We can speak of the character before or after
|
|
|
8378 a particular buffer position, and when you insert a character at a
|
|
|
8379 particular position, all characters after that position end up at new
|
|
|
8380 positions. When we speak of the character @dfn{at} a position, we
|
|
|
8381 really mean the character after the position. (This schizophrenia
|
|
1263
|
8382 between a buffer position being ``between'' two characters and ``on'' a
|
|
428
|
8383 character is rampant in Emacs.)
|
|
|
8384
|
|
|
8385 Buffer positions are numbered starting at 1. This means that
|
|
|
8386 position 1 is before the first character, and position 0 is not
|
|
|
8387 valid. If there are N characters in a buffer, then buffer
|
|
|
8388 position N+1 is after the last one, and position N+2 is not valid.
|
|
|
8389
|
|
1261
|
8390 The internal makeup of the Ichar integer varies depending on whether
|
|
|
8391 we have compiled with MULE support. If not, the Ichar integer is an
|
|
428
|
8392 8-bit integer with possible values from 0 - 255. 0 - 127 are the
|
|
|
8393 standard ASCII characters, while 128 - 255 are the characters from the
|
|
|
8394 ISO-8859-1 character set. If we have compiled with MULE support, an
|
|
1261
|
8395 Ichar is a 19-bit integer, with the various bits having meanings
|
|
428
|
8396 according to a complex scheme that will be detailed later. The
|
|
|
8397 characters numbered 0 - 255 still have the same meanings as for the
|
|
|
8398 non-MULE case, though.
|
|
|
8399
|
|
|
8400 Internally, the text in a buffer is represented in a fairly simple
|
|
|
8401 fashion: as a contiguous array of bytes, with a @dfn{gap} of some size
|
|
|
8402 in the middle. Although the gap is of some substantial size in bytes,
|
|
|
8403 there is no text contained within it: From the perspective of the text
|
|
|
8404 in the buffer, it does not exist. The gap logically sits at some buffer
|
|
|
8405 position, between two characters (or possibly at the beginning or end of
|
|
|
8406 the buffer). Insertion of text in a buffer at a particular position is
|
|
|
8407 always accomplished by first moving the gap to that position
|
|
|
8408 (i.e. through some block moving of text), then writing the text into the
|
|
|
8409 beginning of the gap, thereby shrinking the gap. If the gap shrinks
|
|
|
8410 down to nothing, a new gap is created. (What actually happens is that a
|
|
|
8411 new gap is ``created'' at the end of the buffer's text, which requires
|
|
|
8412 nothing more than changing a couple of indices; then the gap is
|
|
|
8413 ``moved'' to the position where the insertion needs to take place by
|
|
|
8414 moving up in memory all the text after that position.) Similarly,
|
|
|
8415 deletion occurs by moving the gap to the place where the text is to be
|
|
|
8416 deleted, and then simply expanding the gap to include the deleted text.
|
|
|
8417 (@dfn{Expanding} and @dfn{shrinking} the gap as just described means
|
|
|
8418 just that the internal indices that keep track of where the gap is
|
|
|
8419 located are changed.)
|
|
|
8420
|
|
|
8421 Note that the total amount of memory allocated for a buffer text never
|
|
|
8422 decreases while the buffer is live. Therefore, if you load up a
|
|
|
8423 20-megabyte file and then delete all but one character, there will be a
|
|
|
8424 20-megabyte gap, which won't get any smaller (except by inserting
|
|
|
8425 characters back again). Once the buffer is killed, the memory allocated
|
|
|
8426 for the buffer text will be freed, but it will still be sitting on the
|
|
|
8427 heap, taking up virtual memory, and will not be released back to the
|
|
|
8428 operating system. (However, if you have compiled XEmacs with rel-alloc,
|
|
|
8429 the situation is different. In this case, the space @emph{will} be
|
|
|
8430 released back to the operating system. However, this tends to result in a
|
|
|
8431 noticeable speed penalty.)
|
|
|
8432
|
|
|
8433 Astute readers may notice that the text in a buffer is represented as
|
|
1261
|
8434 an array of @emph{bytes}, while (at least in the MULE case) an Ichar is
|
|
428
|
8435 a 19-bit integer, which clearly cannot fit in a byte. This means (of
|
|
|
8436 course) that the text in a buffer uses a different representation from
|
|
1261
|
8437 an Ichar: specifically, the 19-bit Ichar becomes a series of one to
|
|
428
|
8438 four bytes. The conversion between these two representations is complex
|
|
|
8439 and will be described later.
|
|
|
8440
|
|
1261
|
8441 In the non-MULE case, everything is very simple: An Ichar
|
|
428
|
8442 is an 8-bit value, which fits neatly into one byte.
|
|
|
8443
|
|
|
8444 If we are given a buffer position and want to retrieve the
|
|
|
8445 character at that position, we need to follow these steps:
|
|
|
8446
|
|
|
8447 @enumerate
|
|
|
8448 @item
|
|
|
8449 Pretend there's no gap, and convert the buffer position into a @dfn{byte
|
|
|
8450 index} that indexes to the appropriate byte in the buffer's stream of
|
|
|
8451 textual bytes. By convention, byte indices begin at 1, just like buffer
|
|
|
8452 positions. In the non-MULE case, byte indices and buffer positions are
|
|
|
8453 identical, since one character equals one byte.
|
|
|
8454 @item
|
|
|
8455 Convert the byte index into a @dfn{memory index}, which takes the gap
|
|
|
8456 into account. The memory index is a direct index into the block of
|
|
|
8457 memory that stores the text of a buffer. This basically just involves
|
|
|
8458 checking to see if the byte index is past the gap, and if so, adding the
|
|
|
8459 size of the gap to it. By convention, memory indices begin at 1, just
|
|
|
8460 like buffer positions and byte indices, and when referring to the
|
|
|
8461 position that is @dfn{at} the gap, we always use the memory position at
|
|
|
8462 the @emph{beginning}, not at the end, of the gap.
|
|
|
8463 @item
|
|
|
8464 Fetch the appropriate bytes at the determined memory position.
|
|
|
8465 @item
|
|
1261
|
8466 Convert these bytes into an Ichar.
|
|
428
|
8467 @end enumerate
|
|
|
8468
|
|
|
8469 In the non-Mule case, (3) and (4) boil down to a simple one-byte
|
|
|
8470 memory access.
|
|
|
8471
|
|
|
8472 Note that we have defined three types of positions in a buffer:
|
|
|
8473
|
|
|
8474 @enumerate
|
|
|
8475 @item
|
|
1261
|
8476 @dfn{buffer positions} or @dfn{character positions}, typedef @code{Charbpos}
|
|
|
8477 @item
|
|
|
8478 @dfn{byte indices}, typedef @code{Bytebpos}
|
|
|
8479 @item
|
|
|
8480 @dfn{memory indices}, typedef @code{Membpos}
|
|
428
|
8481 @end enumerate
|
|
|
8482
|
|
|
8483 All three typedefs are just @code{int}s, but defining them this way makes
|
|
|
8484 things a lot clearer.
|
|
|
8485
|
|
|
8486 Most code works with buffer positions. In particular, all Lisp code
|
|
|
8487 that refers to text in a buffer uses buffer positions. Lisp code does
|
|
|
8488 not know that byte indices or memory indices exist.
|
|
|
8489
|
|
|
8490 Finally, we have a typedef for the bytes in a buffer. This is a
|
|
1261
|
8491 @code{Ibyte}, which is an unsigned char. Referring to them as
|
|
|
8492 Ibytes underscores the fact that we are working with a string of bytes
|
|
428
|
8493 in the internal Emacs buffer representation rather than in one of a
|
|
|
8494 number of possible alternative representations (e.g. EUC-encoded text,
|
|
|
8495 etc.).
|
|
|
8496
|
|
462
|
8497 @node Buffer Lists
|
|
428
|
8498 @section Buffer Lists
|
|
462
|
8499 @cindex buffer lists
|
|
428
|
8500
|
|
|
8501 Recall earlier that buffers are @dfn{permanent} objects, i.e. that
|
|
|
8502 they remain around until explicitly deleted. This entails that there is
|
|
|
8503 a list of all the buffers in existence. This list is actually an
|
|
|
8504 assoc-list (mapping from the buffer's name to the buffer) and is stored
|
|
|
8505 in the global variable @code{Vbuffer_alist}.
|
|
|
8506
|
|
|
8507 The order of the buffers in the list is important: the buffers are
|
|
|
8508 ordered approximately from most-recently-used to least-recently-used.
|
|
|
8509 Switching to a buffer using @code{switch-to-buffer},
|
|
|
8510 @code{pop-to-buffer}, etc. and switching windows using
|
|
|
8511 @code{other-window}, etc. usually brings the new current buffer to the
|
|
|
8512 front of the list. @code{switch-to-buffer}, @code{other-buffer},
|
|
|
8513 etc. look at the beginning of the list to find an alternative buffer to
|
|
|
8514 suggest. You can also explicitly move a buffer to the end of the list
|
|
|
8515 using @code{bury-buffer}.
|
|
|
8516
|
|
|
8517 In addition to the global ordering in @code{Vbuffer_alist}, each frame
|
|
|
8518 has its own ordering of the list. These lists always contain the same
|
|
|
8519 elements as in @code{Vbuffer_alist} although possibly in a different
|
|
|
8520 order. @code{buffer-list} normally returns the list for the selected
|
|
|
8521 frame. This allows you to work in separate frames without things
|
|
|
8522 interfering with each other.
|
|
|
8523
|
|
|
8524 The standard way to look up a buffer given a name is
|
|
|
8525 @code{get-buffer}, and the standard way to create a new buffer is
|
|
|
8526 @code{get-buffer-create}, which looks up a buffer with a given name,
|
|
|
8527 creating a new one if necessary. These operations correspond exactly
|
|
|
8528 with the symbol operations @code{intern-soft} and @code{intern},
|
|
|
8529 respectively. You can also force a new buffer to be created using
|
|
|
8530 @code{generate-new-buffer}, which takes a name and (if necessary) makes
|
|
|
8531 a unique name from this by appending a number, and then creates the
|
|
|
8532 buffer. This is basically like the symbol operation @code{gensym}.
|
|
|
8533
|
|
462
|
8534 @node Markers and Extents
|
|
428
|
8535 @section Markers and Extents
|
|
462
|
8536 @cindex markers and extents
|
|
|
8537 @cindex extents, markers and
|
|
428
|
8538
|
|
|
8539 Among the things associated with a buffer are things that are
|
|
|
8540 logically attached to certain buffer positions. This can be used to
|
|
|
8541 keep track of a buffer position when text is inserted and deleted, so
|
|
|
8542 that it remains at the same spot relative to the text around it; to
|
|
|
8543 assign properties to particular sections of text; etc. There are two
|
|
|
8544 such objects that are useful in this regard: they are @dfn{markers} and
|
|
|
8545 @dfn{extents}.
|
|
|
8546
|
|
|
8547 A @dfn{marker} is simply a flag placed at a particular buffer
|
|
|
8548 position, which is moved around as text is inserted and deleted.
|
|
|
8549 Markers are used for all sorts of purposes, such as the @code{mark} that
|
|
|
8550 is the other end of textual regions to be cut, copied, etc.
|
|
|
8551
|
|
|
8552 An @dfn{extent} is similar to two markers plus some associated
|
|
|
8553 properties, and is used to keep track of regions in a buffer as text is
|
|
|
8554 inserted and deleted, and to add properties (e.g. fonts) to particular
|
|
|
8555 regions of text. The external interface of extents is explained
|
|
|
8556 elsewhere.
|
|
|
8557
|
|
|
8558 The important thing here is that markers and extents simply contain
|
|
|
8559 buffer positions in them as integers, and every time text is inserted or
|
|
|
8560 deleted, these positions must be updated. In order to minimize the
|
|
|
8561 amount of shuffling that needs to be done, the positions in markers and
|
|
1261
|
8562 extents (there's one per marker, two per extent) are stored in Membpos's.
|
|
428
|
8563 This means that they only need to be moved when the text is physically
|
|
|
8564 moved in memory; since the gap structure tries to minimize this, it also
|
|
|
8565 minimizes the number of marker and extent indices that need to be
|
|
|
8566 adjusted. Look in @file{insdel.c} for the details of how this works.
|
|
|
8567
|
|
|
8568 One other important distinction is that markers are @dfn{temporary}
|
|
|
8569 while extents are @dfn{permanent}. This means that markers disappear as
|
|
|
8570 soon as there are no more pointers to them, and correspondingly, there
|
|
|
8571 is no way to determine what markers are in a buffer if you are just
|
|
|
8572 given the buffer. Extents remain in a buffer until they are detached
|
|
|
8573 (which could happen as a result of text being deleted) or the buffer is
|
|
|
8574 deleted, and primitives do exist to enumerate the extents in a buffer.
|
|
|
8575
|
|
1261
|
8576 @node Ibytes and Ichars
|
|
|
8577 @section Ibytes and Ichars
|
|
|
8578 @cindex Ibytes and Ichars
|
|
|
8579 @cindex Ichars, Ibytes and
|
|
428
|
8580
|
|
|
8581 Not yet documented.
|
|
|
8582
|
|
462
|
8583 @node The Buffer Object
|
|
428
|
8584 @section The Buffer Object
|
|
462
|
8585 @cindex buffer object, the
|
|
|
8586 @cindex object, the buffer
|
|
428
|
8587
|
|
|
8588 Buffers contain fields not directly accessible by the Lisp programmer.
|
|
|
8589 We describe them here, naming them by the names used in the C code.
|
|
|
8590 Many are accessible indirectly in Lisp programs via Lisp primitives.
|
|
|
8591
|
|
|
8592 @table @code
|
|
|
8593 @item name
|
|
|
8594 The buffer name is a string that names the buffer. It is guaranteed to
|
|
446
|
8595 be unique. @xref{Buffer Names,,, lispref, XEmacs Lisp Reference
|
|
428
|
8596 Manual}.
|
|
|
8597
|
|
|
8598 @item save_modified
|
|
|
8599 This field contains the time when the buffer was last saved, as an
|
|
446
|
8600 integer. @xref{Buffer Modification,,, lispref, XEmacs Lisp Reference
|
|
428
|
8601 Manual}.
|
|
|
8602
|
|
|
8603 @item modtime
|
|
|
8604 This field contains the modification time of the visited file. It is
|
|
|
8605 set when the file is written or read. Every time the buffer is written
|
|
|
8606 to the file, this field is compared to the modification time of the
|
|
446
|
8607 file. @xref{Buffer Modification,,, lispref, XEmacs Lisp Reference
|
|
428
|
8608 Manual}.
|
|
|
8609
|
|
|
8610 @item auto_save_modified
|
|
|
8611 This field contains the time when the buffer was last auto-saved.
|
|
|
8612
|
|
|
8613 @item last_window_start
|
|
|
8614 This field contains the @code{window-start} position in the buffer as of
|
|
|
8615 the last time the buffer was displayed in a window.
|
|
|
8616
|
|
|
8617 @item undo_list
|
|
|
8618 This field points to the buffer's undo list. @xref{Undo,,, lispref,
|
|
446
|
8619 XEmacs Lisp Reference Manual}.
|
|
428
|
8620
|
|
|
8621 @item syntax_table_v
|
|
|
8622 This field contains the syntax table for the buffer. @xref{Syntax
|
|
446
|
8623 Tables,,, lispref, XEmacs Lisp Reference Manual}.
|
|
428
|
8624
|
|
|
8625 @item downcase_table
|
|
|
8626 This field contains the conversion table for converting text to lower
|
|
446
|
8627 case. @xref{Case Tables,,, lispref, XEmacs Lisp Reference Manual}.
|
|
428
|
8628
|
|
|
8629 @item upcase_table
|
|
|
8630 This field contains the conversion table for converting text to upper
|
|
446
|
8631 case. @xref{Case Tables,,, lispref, XEmacs Lisp Reference Manual}.
|
|
428
|
8632
|
|
|
8633 @item case_canon_table
|
|
|
8634 This field contains the conversion table for canonicalizing text for
|
|
|
8635 case-folding search. @xref{Case Tables,,, lispref, XEmacs Lisp
|
|
446
|
8636 Reference Manual}.
|
|
428
|
8637
|
|
|
8638 @item case_eqv_table
|
|
|
8639 This field contains the equivalence table for case-folding search.
|
|
446
|
8640 @xref{Case Tables,,, lispref, XEmacs Lisp Reference Manual}.
|
|
428
|
8641
|
|
|
8642 @item display_table
|
|
|
8643 This field contains the buffer's display table, or @code{nil} if it
|
|
|
8644 doesn't have one. @xref{Display Tables,,, lispref, XEmacs Lisp
|
|
446
|
8645 Reference Manual}.
|
|
428
|
8646
|
|
|
8647 @item markers
|
|
|
8648 This field contains the chain of all markers that currently point into
|
|
|
8649 the buffer. Deletion of text in the buffer, and motion of the buffer's
|
|
|
8650 gap, must check each of these markers and perhaps update it.
|
|
446
|
8651 @xref{Markers,,, lispref, XEmacs Lisp Reference Manual}.
|
|
428
|
8652
|
|
|
8653 @item backed_up
|
|
|
8654 This field is a flag that tells whether a backup file has been made for
|
|
|
8655 the visited file of this buffer.
|
|
|
8656
|
|
|
8657 @item mark
|
|
|
8658 This field contains the mark for the buffer. The mark is a marker,
|
|
|
8659 hence it is also included on the list @code{markers}. @xref{The Mark,,,
|
|
446
|
8660 lispref, XEmacs Lisp Reference Manual}.
|
|
428
|
8661
|
|
|
8662 @item mark_active
|
|
|
8663 This field is non-@code{nil} if the buffer's mark is active.
|
|
|
8664
|
|
|
8665 @item local_var_alist
|
|
|
8666 This field contains the association list describing the variables local
|
|
|
8667 in this buffer, and their values, with the exception of local variables
|
|
|
8668 that have special slots in the buffer object. (Those slots are omitted
|
|
|
8669 from this table.) @xref{Buffer-Local Variables,,, lispref, XEmacs Lisp
|
|
446
|
8670 Reference Manual}.
|
|
428
|
8671
|
|
|
8672 @item modeline_format
|
|
|
8673 This field contains a Lisp object which controls how to display the mode
|
|
|
8674 line for this buffer. @xref{Modeline Format,,, lispref, XEmacs Lisp
|
|
446
|
8675 Reference Manual}.
|
|
428
|
8676
|
|
|
8677 @item base_buffer
|
|
|
8678 This field holds the buffer's base buffer (if it is an indirect buffer),
|
|
|
8679 or @code{nil}.
|
|
|
8680 @end table
|
|
|
8681
|
|
1496
|
8682 @node Searching and Matching
|
|
|
8683 @section Searching and Matching
|
|
|
8684 @cindex searching
|
|
|
8685 @cindex matching
|
|
|
8686
|
|
|
8687 Very incomplete, limited to a brief introduction.
|
|
|
8688
|
|
|
8689 People find the searching and matching code difficult to understand.
|
|
|
8690 And indeed, the details are hard. However, the basic structures are not
|
|
|
8691 so complex. First, there's a hard question with a simple answer. What
|
|
|
8692 about Mule? The answer here is that it turns out that Mule characters
|
|
|
8693 can be matched byte by byte, so neither the search code nor the regular
|
|
|
8694 expression code need take much notice of it at all! Of course, we add
|
|
|
8695 some special features (such as regular expressions that match only
|
|
|
8696 certain charsets), but these do not require new concepts. The main
|
|
|
8697 exception is that wild-card matches in Mule have to be careful to
|
|
|
8698 swallow whole characters. This is handled using the same basic macros
|
|
|
8699 that are used for buffer and string movements.
|
|
|
8700
|
|
|
8701 The complex algorithms for searching are for simple string searches. In
|
|
|
8702 particular, the algorithm used for fast string searching is Boyer-Moore.
|
|
|
8703 This algorithm is based on the idea that if you have a mismatch at a
|
|
|
8704 given position, you can precompute where to restart the search. This
|
|
|
8705 typically means that you can often make many fewer than N character
|
|
|
8706 comparisons, where N is the position at which the match is found, or the
|
|
|
8707 size of the text if it contains no match. That's fast! But it's not
|
|
|
8708 easy. You must ``compile'' the search string into a jump table. See
|
|
|
8709 the source, @file{search.c}, for more information.
|
|
|
8710
|
|
|
8711 Emacs changes the basic algorithms somewhat in order to handle
|
|
|
8712 case-insensitive searches without a full-blown regular expression.
|
|
|
8713
|
|
|
8714 Regular expressions, on the other hand, have a trivial search
|
|
|
8715 implementation: try a match at each position. (Under POSIX rules, it's
|
|
|
8716 a bit more complex, because POSIX requires that you find the
|
|
|
8717 @emph{longest} match in the text. This means you keep a record of the
|
|
|
8718 best match so far, and find all the matches.)
|
|
|
8719
|
|
|
8720 The matching code for regular expressions is quite complex. First, the
|
|
|
8721 regular expression itself is compiled. There are two basic approaches
|
|
|
8722 that could be taken. The first is to compile the expression into tables
|
|
|
8723 to drive a generic finite automaton emulator. This is the approach
|
|
|
8724 given in many textbooks (Sedgewick's @emph{Algorithms} and Aho, Sethi,
|
|
|
8725 and Ullmann's @emph{Compilers: Principles, Techniques, and Tools}, aka
|
|
|
8726 ``The Dragon Book'') as well as being used by the @file{lex} family of
|
|
|
8727 lexical analysis engines.
|
|
|
8728
|
|
|
8729 Emacs uses a somewhat different technique. The expression is compiled
|
|
|
8730 into a form of bytecode, which is interpreted by a special interpreter.
|
|
|
8731 The interpreter itself basically amounts to an inline implementation of
|
|
|
8732 the finite automaton emulator. The advantage of this technique is that
|
|
|
8733 it's easier to add special features, such as control of case-sensitivity
|
|
|
8734 via a global variable.
|
|
|
8735
|
|
|
8736 The compiler is not treated here. See the source, @file{regex.c}. The
|
|
|
8737 interpreter, although it is divided into several functions, and looks
|
|
|
8738 fearsomely complex, is actually quite simple in concept. However,
|
|
|
8739 basically what you're doing there is a strcmp on steroids, right?
|
|
|
8740
|
|
|
8741 @example
|
|
|
8742 int
|
|
|
8743 strcmp (char *p, /* pattern pointer */
|
|
|
8744 char *b) /* buffer pointer */
|
|
|
8745 @{
|
|
|
8746 while (*p++ == *b++)
|
|
|
8747 ;
|
|
|
8748 return *(--p) - *(--b); /* oops, we overshot */
|
|
|
8749 @}
|
|
|
8750 @end example
|
|
|
8751
|
|
|
8752 Really, it's no harder than that. (A bit of a white lie, OK?)
|
|
|
8753
|
|
|
8754 How does the regexp code generalize this?
|
|
|
8755
|
|
|
8756 @enumerate
|
|
|
8757 @item
|
|
|
8758 Depending on the pattern, @code{*b} may have a general relationship to
|
|
|
8759 @code{*p}. @emph{I.e.}, direct comparison against @code{*p} is
|
|
|
8760 generalized to include checks for set membership, and context dependent
|
|
|
8761 properties. This depends on @code{&*b}. Of course that's meaningless
|
|
|
8762 in C, so we use @code{b} directly, instead.
|
|
|
8763
|
|
|
8764 @item
|
|
|
8765 Although to ensure the algorithm terminates, @code{b} must advance step
|
|
|
8766 by step, @code{p} can branch and jump.
|
|
|
8767
|
|
|
8768 @item
|
|
|
8769 The information returned is much greater, including information about
|
|
|
8770 subexpressions.
|
|
|
8771 @end enumerate
|
|
|
8772
|
|
|
8773 We'll ignore (3). (2) is mostly interesting when compiling the regular
|
|
|
8774 expression. Now we have
|
|
|
8775
|
|
|
8776 @example
|
|
|
8777 @group
|
|
|
8778 enum operator_t @{
|
|
|
8779 accept = 0,
|
|
|
8780 exact,
|
|
|
8781 any,
|
|
|
8782 range,
|
|
|
8783 group, /* actually, these are probably */
|
|
|
8784 repeat, /* turned into conditional code */
|
|
|
8785 /* etc */
|
|
|
8786 @};
|
|
|
8787 @end group
|
|
|
8788
|
|
|
8789 @group
|
|
|
8790 enum status_t @{
|
|
|
8791 working = 0,
|
|
|
8792 matched,
|
|
|
8793 mismatch,
|
|
|
8794 end_of_buffer,
|
|
|
8795 error
|
|
|
8796 @};
|
|
|
8797 @end group
|
|
|
8798
|
|
|
8799 @group
|
|
|
8800 struct pattern @{
|
|
|
8801 enum operator_t operator;
|
|
|
8802 char char_value;
|
|
|
8803 boolean range_table[256];
|
|
|
8804 /* etc, etc */
|
|
|
8805 @};
|
|
|
8806 @end group
|
|
|
8807
|
|
|
8808 @group
|
|
|
8809 char *p, /* pattern pointer */
|
|
|
8810 *b; /* buffer pointer */
|
|
|
8811
|
|
|
8812 enum status_t
|
|
|
8813 match (struct pattern *p, char *b)
|
|
|
8814 @{
|
|
|
8815 enum status_t done = working;
|
|
|
8816
|
|
|
8817 while (!(done = match_1_operator (p, b)))
|
|
|
8818 @{
|
|
|
8819 struct pattern *p1 = p;
|
|
|
8820 p = next_p (p, b);
|
|
|
8821 b = next_b (p1, b);
|
|
|
8822 @}
|
|
|
8823 return done;
|
|
|
8824 @}
|
|
|
8825 @end group
|
|
|
8826 @end example
|
|
|
8827
|
|
|
8828 This format exposes the underlying finite automaton.
|
|
|
8829
|
|
|
8830 All of them have the following structure, except that the @samp{next_*}
|
|
|
8831 functions decide where to jump (for @samp{p}) and whether or not to
|
|
|
8832 increment (for @samp{b}), rather than checking for satisfaction of a
|
|
|
8833 matching condition.
|
|
|
8834
|
|
|
8835 @example
|
|
|
8836 enum status_t
|
|
|
8837 match_1_operator (pattern *p, char *b)
|
|
|
8838 @{
|
|
|
8839 if (! *b) return end_of_buffer;
|
|
|
8840 switch (p->operator)
|
|
|
8841 @{
|
|
|
8842 case accept:
|
|
|
8843 return matched;
|
|
|
8844 case exact:
|
|
|
8845 if (*b != p->char_value) return mismatch; else break;
|
|
|
8846 case any:
|
|
|
8847 break;
|
|
|
8848 case range:
|
|
|
8849 /* range_table is computed in the regexp_compile function */
|
|
|
8850 if (! p->range_table[*b]) return mismatch;
|
|
|
8851 /* etc, etc */
|
|
|
8852 @}
|
|
|
8853 return working;
|
|
|
8854 @}
|
|
|
8855 @end example
|
|
|
8856
|
|
|
8857 Grouping, repetition, and alternation are handled by compiling the
|
|
|
8858 subexpression and calling @code{match (p->subpattern, b)} recursively.
|
|
|
8859
|
|
|
8860 In terms of reading the actual code, there are five optimizations
|
|
|
8861 (obfuscations, if you like) that have been done.
|
|
|
8862
|
|
|
8863 @enumerate
|
|
|
8864 @item
|
|
|
8865 An explicit "failure stack" has been substituted for recursion.
|
|
|
8866
|
|
|
8867 @item
|
|
|
8868 The @code{match_1_operator}, @code{next_p}, and @code{next_b} functions
|
|
|
8869 are actually inlined into the @code{match} function for efficiency.
|
|
|
8870 Then the pointer movement is interspersed with the matching operations.
|
|
|
8871
|
|
|
8872 @item
|
|
|
8873 If the operator uses buffer context, the buffer pointer movement is
|
|
|
8874 sometimes implicit in the operations retrieving the context.
|
|
|
8875
|
|
|
8876 @item
|
|
|
8877 Some cases are combined into short preparation for individual cases, and
|
|
|
8878 a "fall-through" into combined code for several cases.
|
|
|
8879
|
|
|
8880 @item
|
|
|
8881 The @code{pattern} type is not an explicit @samp{struct}. Instead, the
|
|
|
8882 data (including, @emph{e.g.}, @samp{range_table}) is inlined into the
|
|
|
8883 compiled bytecode. This leads to bizarre code in the interpreter like
|
|
|
8884
|
|
|
8885 @example
|
|
|
8886 case range:
|
|
|
8887 p += *(p + 1); break;
|
|
|
8888 @end example
|
|
|
8889
|
|
|
8890 in @code{next_p}, because the compiled pattern is laid out
|
|
|
8891
|
|
|
8892 @example
|
|
|
8893 ..., 'range', count, first_8_flags, second_8_flags, ..., next_op, ...
|
|
|
8894 @end example
|
|
|
8895 @end enumerate
|
|
|
8896
|
|
|
8897 But if you keep your eye on the "switch in a loop" structure, you
|
|
|
8898 should be able to understand the parts you need.
|
|
|
8899
|
|
|
8900
|
|
428
|
8901 @node MULE Character Sets and Encodings, The Lisp Reader and Compiler, Buffers and Textual Representation, Top
|
|
|
8902 @chapter MULE Character Sets and Encodings
|
|
462
|
8903 @cindex Mule character sets and encodings
|
|
|
8904 @cindex character sets and encodings, Mule
|
|
|
8905 @cindex encodings, Mule character sets and
|
|
428
|
8906
|
|
|
8907 Recall that there are two primary ways that text is represented in
|
|
|
8908 XEmacs. The @dfn{buffer} representation sees the text as a series of
|
|
1261
|
8909 bytes (Ibytes), with a variable number of bytes used per character.
|
|
428
|
8910 The @dfn{character} representation sees the text as a series of integers
|
|
1261
|
8911 (Ichars), one per character. The character representation is a cleaner
|
|
428
|
8912 representation from a theoretical standpoint, and is thus used in many
|
|
|
8913 cases when lots of manipulations on a string need to be done. However,
|
|
|
8914 the buffer representation is the standard representation used in both
|
|
|
8915 Lisp strings and buffers, and because of this, it is the ``default''
|
|
|
8916 representation that text comes in. The reason for using this
|
|
|
8917 representation is that it's compact and is compatible with ASCII.
|
|
|
8918
|
|
|
8919 @menu
|
|
|
8920 * Character Sets::
|
|
|
8921 * Encodings::
|
|
|
8922 * Internal Mule Encodings::
|
|
|
8923 * CCL::
|
|
|
8924 @end menu
|
|
|
8925
|
|
462
|
8926 @node Character Sets
|
|
428
|
8927 @section Character Sets
|
|
462
|
8928 @cindex character sets
|
|
428
|
8929
|
|
|
8930 A character set (or @dfn{charset}) is an ordered set of characters. A
|
|
|
8931 particular character in a charset is indexed using one or more
|
|
|
8932 @dfn{position codes}, which are non-negative integers. The number of
|
|
|
8933 position codes needed to identify a particular character in a charset is
|
|
|
8934 called the @dfn{dimension} of the charset. In XEmacs/Mule, all charsets
|
|
|
8935 have dimension 1 or 2, and the size of all charsets (except for a few
|
|
|
8936 special cases) is either 94, 96, 94 by 94, or 96 by 96. The range of
|
|
|
8937 position codes used to index characters from any of these types of
|
|
|
8938 character sets is as follows:
|
|
|
8939
|
|
|
8940 @example
|
|
|
8941 Charset type Position code 1 Position code 2
|
|
|
8942 ------------------------------------------------------------
|
|
|
8943 94 33 - 126 N/A
|
|
|
8944 96 32 - 127 N/A
|
|
|
8945 94x94 33 - 126 33 - 126
|
|
|
8946 96x96 32 - 127 32 - 127
|
|
|
8947 @end example
|
|
|
8948
|
|
|
8949 Note that in the above cases position codes do not start at an
|
|
|
8950 expected value such as 0 or 1. The reason for this will become clear
|
|
|
8951 later.
|
|
|
8952
|
|
|
8953 For example, Latin-1 is a 96-character charset, and JISX0208 (the
|
|
|
8954 Japanese national character set) is a 94x94-character charset.
|
|
|
8955
|
|
|
8956 [Note that, although the ranges above define the @emph{valid} position
|
|
|
8957 codes for a charset, some of the slots in a particular charset may in
|
|
|
8958 fact be empty. This is the case for JISX0208, for example, where (e.g.)
|
|
|
8959 all the slots whose first position code is in the range 118 - 127 are
|
|
|
8960 empty.]
|
|
|
8961
|
|
|
8962 There are three charsets that do not follow the above rules. All of
|
|
|
8963 them have one dimension, and have ranges of position codes as follows:
|
|
|
8964
|
|
|
8965 @example
|
|
|
8966 Charset name Position code 1
|
|
|
8967 ------------------------------------
|
|
|
8968 ASCII 0 - 127
|
|
|
8969 Control-1 0 - 31
|
|
|
8970 Composite 0 - some large number
|
|
|
8971 @end example
|
|
|
8972
|
|
|
8973 (The upper bound of the position code for composite characters has not
|
|
|
8974 yet been determined, but it will probably be at least 16,383).
|
|
|
8975
|
|
|
8976 ASCII is the union of two subsidiary character sets: Printing-ASCII
|
|
|
8977 (the printing ASCII character set, consisting of position codes 33 -
|
|
|
8978 126, like for a standard 94-character charset) and Control-ASCII (the
|
|
|
8979 non-printing characters that would appear in a binary file with codes 0
|
|
|
8980 - 32 and 127).
|
|
|
8981
|
|
|
8982 Control-1 contains the non-printing characters that would appear in a
|
|
|
8983 binary file with codes 128 - 159.
|
|
|
8984
|
|
|
8985 Composite contains characters that are generated by overstriking one
|
|
|
8986 or more characters from other charsets.
|
|
|
8987
|
|
|
8988 Note that some characters in ASCII, and all characters in Control-1,
|
|
|
8989 are @dfn{control} (non-printing) characters. These have no printed
|
|
|
8990 representation but instead control some other function of the printing
|
|
|
8991 (e.g. TAB or 8 moves the current character position to the next tab
|
|
|
8992 stop). All other characters in all charsets are @dfn{graphic}
|
|
|
8993 (printing) characters.
|
|
|
8994
|
|
|
8995 When a binary file is read in, the bytes in the file are assigned to
|
|
|
8996 character sets as follows:
|
|
|
8997
|
|
|
8998 @example
|
|
|
8999 Bytes Character set Range
|
|
|
9000 --------------------------------------------------
|
|
|
9001 0 - 127 ASCII 0 - 127
|
|
|
9002 128 - 159 Control-1 0 - 31
|
|
|
9003 160 - 255 Latin-1 32 - 127
|
|
|
9004 @end example
|
|
|
9005
|
|
|
9006 This is a bit ad-hoc but gets the job done.
|
|
|
9007
|
|
462
|
9008 @node Encodings
|
|
428
|
9009 @section Encodings
|
|
462
|
9010 @cindex encodings, Mule
|
|
|
9011 @cindex Mule encodings
|
|
428
|
9012
|
|
|
9013 An @dfn{encoding} is a way of numerically representing characters from
|
|
|
9014 one or more character sets. If an encoding only encompasses one
|
|
|
9015 character set, then the position codes for the characters in that
|
|
|
9016 character set could be used directly. This is not possible, however, if
|
|
|
9017 more than one character set is to be used in the encoding.
|
|
|
9018
|
|
|
9019 For example, the conversion detailed above between bytes in a binary
|
|
|
9020 file and characters is effectively an encoding that encompasses the
|
|
|
9021 three character sets ASCII, Control-1, and Latin-1 in a stream of 8-bit
|
|
|
9022 bytes.
|
|
|
9023
|
|
|
9024 Thus, an encoding can be viewed as a way of encoding characters from a
|
|
|
9025 specified group of character sets using a stream of bytes, each of which
|
|
|
9026 contains a fixed number of bits (but not necessarily 8, as in the common
|
|
|
9027 usage of ``byte'').
|
|
|
9028
|
|
|
9029 Here are descriptions of a couple of common
|
|
|
9030 encodings:
|
|
|
9031
|
|
|
9032 @menu
|
|
|
9033 * Japanese EUC (Extended Unix Code)::
|
|
|
9034 * JIS7::
|
|
|
9035 @end menu
|
|
|
9036
|
|
462
|
9037 @node Japanese EUC (Extended Unix Code)
|
|
428
|
9038 @subsection Japanese EUC (Extended Unix Code)
|
|
462
|
9039 @cindex Japanese EUC (Extended Unix Code)
|
|
|
9040 @cindex EUC (Extended Unix Code), Japanese
|
|
|
9041 @cindex Extended Unix Code, Japanese EUC
|
|
428
|
9042
|
|
|
9043 This encompasses the character sets Printing-ASCII, Japanese-JISX0201,
|
|
|
9044 and Japanese-JISX0208-Kana (half-width katakana, the right half of
|
|
|
9045 JISX0201). It uses 8-bit bytes.
|
|
|
9046
|
|
|
9047 Note that Printing-ASCII and Japanese-JISX0201-Kana are 94-character
|
|
|
9048 charsets, while Japanese-JISX0208 is a 94x94-character charset.
|
|
|
9049
|
|
|
9050 The encoding is as follows:
|
|
|
9051
|
|
|
9052 @example
|
|
|
9053 Character set Representation (PC=position-code)
|
|
|
9054 ------------- --------------
|
|
|
9055 Printing-ASCII PC1
|
|
|
9056 Japanese-JISX0201-Kana 0x8E | PC1 + 0x80
|
|
|
9057 Japanese-JISX0208 PC1 + 0x80 | PC2 + 0x80
|
|
|
9058 Japanese-JISX0212 PC1 + 0x80 | PC2 + 0x80
|
|
|
9059 @end example
|
|
|
9060
|
|
|
9061
|
|
462
|
9062 @node JIS7
|
|
428
|
9063 @subsection JIS7
|
|
462
|
9064 @cindex JIS7
|
|
428
|
9065
|
|
|
9066 This encompasses the character sets Printing-ASCII,
|
|
|
9067 Japanese-JISX0201-Roman (the left half of JISX0201; this character set
|
|
|
9068 is very similar to Printing-ASCII and is a 94-character charset),
|
|
|
9069 Japanese-JISX0208, and Japanese-JISX0201-Kana. It uses 7-bit bytes.
|
|
|
9070
|
|
|
9071 Unlike Japanese EUC, this is a @dfn{modal} encoding, which
|
|
|
9072 means that there are multiple states that the encoding can
|
|
|
9073 be in, which affect how the bytes are to be interpreted.
|
|
|
9074 Special sequences of bytes (called @dfn{escape sequences})
|
|
|
9075 are used to change states.
|
|
|
9076
|
|
|
9077 The encoding is as follows:
|
|
|
9078
|
|
|
9079 @example
|
|
|
9080 Character set Representation (PC=position-code)
|
|
|
9081 ------------- --------------
|
|
|
9082 Printing-ASCII PC1
|
|
|
9083 Japanese-JISX0201-Roman PC1
|
|
|
9084 Japanese-JISX0201-Kana PC1
|
|
|
9085 Japanese-JISX0208 PC1 PC2
|
|
|
9086
|
|
|
9087
|
|
|
9088 Escape sequence ASCII equivalent Meaning
|
|
|
9089 --------------- ---------------- -------
|
|
|
9090 0x1B 0x28 0x4A ESC ( J invoke Japanese-JISX0201-Roman
|
|
|
9091 0x1B 0x28 0x49 ESC ( I invoke Japanese-JISX0201-Kana
|
|
|
9092 0x1B 0x24 0x42 ESC $ B invoke Japanese-JISX0208
|
|
|
9093 0x1B 0x28 0x42 ESC ( B invoke Printing-ASCII
|
|
|
9094 @end example
|
|
|
9095
|
|
|
9096 Initially, Printing-ASCII is invoked.
|
|
|
9097
|
|
462
|
9098 @node Internal Mule Encodings
|
|
428
|
9099 @section Internal Mule Encodings
|
|
462
|
9100 @cindex internal Mule encodings
|
|
|
9101 @cindex Mule encodings, internal
|
|
|
9102 @cindex encodings, internal Mule
|
|
428
|
9103
|
|
|
9104 In XEmacs/Mule, each character set is assigned a unique number, called a
|
|
|
9105 @dfn{leading byte}. This is used in the encodings of a character.
|
|
|
9106 Leading bytes are in the range 0x80 - 0xFF (except for ASCII, which has
|
|
|
9107 a leading byte of 0), although some leading bytes are reserved.
|
|
|
9108
|
|
|
9109 Charsets whose leading byte is in the range 0x80 - 0x9F are called
|
|
|
9110 @dfn{official} and are used for built-in charsets. Other charsets are
|
|
|
9111 called @dfn{private} and have leading bytes in the range 0xA0 - 0xFF;
|
|
|
9112 these are user-defined charsets.
|
|
|
9113
|
|
|
9114 More specifically:
|
|
|
9115
|
|
|
9116 @example
|
|
|
9117 Character set Leading byte
|
|
|
9118 ------------- ------------
|
|
|
9119 ASCII 0
|
|
|
9120 Composite 0x80
|
|
|
9121 Dimension-1 Official 0x81 - 0x8D
|
|
|
9122 (0x8E is free)
|
|
|
9123 Control-1 0x8F
|
|
|
9124 Dimension-2 Official 0x90 - 0x99
|
|
|
9125 (0x9A - 0x9D are free;
|
|
|
9126 0x9E and 0x9F are reserved)
|
|
|
9127 Dimension-1 Private 0xA0 - 0xEF
|
|
|
9128 Dimension-2 Private 0xF0 - 0xFF
|
|
|
9129 @end example
|
|
|
9130
|
|
|
9131 There are two internal encodings for characters in XEmacs/Mule. One is
|
|
|
9132 called @dfn{string encoding} and is an 8-bit encoding that is used for
|
|
|
9133 representing characters in a buffer or string. It uses 1 to 4 bytes per
|
|
|
9134 character. The other is called @dfn{character encoding} and is a 19-bit
|
|
|
9135 encoding that is used for representing characters individually in a
|
|
|
9136 variable.
|
|
|
9137
|
|
|
9138 (In the following descriptions, we'll ignore composite characters for
|
|
|
9139 the moment. We also give a general (structural) overview first,
|
|
|
9140 followed later by the exact details.)
|
|
|
9141
|
|
|
9142 @menu
|
|
|
9143 * Internal String Encoding::
|
|
|
9144 * Internal Character Encoding::
|
|
|
9145 @end menu
|
|
|
9146
|
|
462
|
9147 @node Internal String Encoding
|
|
428
|
9148 @subsection Internal String Encoding
|
|
462
|
9149 @cindex internal string encoding
|
|
|
9150 @cindex string encoding, internal
|
|
|
9151 @cindex encoding, internal string
|
|
428
|
9152
|
|
|
9153 ASCII characters are encoded using their position code directly. Other
|
|
|
9154 characters are encoded using their leading byte followed by their
|
|
|
9155 position code(s) with the high bit set. Characters in private character
|
|
|
9156 sets have their leading byte prefixed with a @dfn{leading byte prefix},
|
|
|
9157 which is either 0x9E or 0x9F. (No character sets are ever assigned these
|
|
|
9158 leading bytes.) Specifically:
|
|
|
9159
|
|
|
9160 @example
|
|
|
9161 Character set Encoding (PC=position-code, LB=leading-byte)
|
|
|
9162 ------------- --------
|
|
|
9163 ASCII PC-1 |
|
|
|
9164 Control-1 LB | PC1 + 0xA0 |
|
|
|
9165 Dimension-1 official LB | PC1 + 0x80 |
|
|
|
9166 Dimension-1 private 0x9E | LB | PC1 + 0x80 |
|
|
|
9167 Dimension-2 official LB | PC1 + 0x80 | PC2 + 0x80 |
|
|
|
9168 Dimension-2 private 0x9F | LB | PC1 + 0x80 | PC2 + 0x80
|
|
|
9169 @end example
|
|
|
9170
|
|
|
9171 The basic characteristic of this encoding is that the first byte
|
|
|
9172 of all characters is in the range 0x00 - 0x9F, and the second and
|
|
|
9173 following bytes of all characters is in the range 0xA0 - 0xFF.
|
|
|
9174 This means that it is impossible to get out of sync, or more
|
|
|
9175 specifically:
|
|
|
9176
|
|
|
9177 @enumerate
|
|
|
9178 @item
|
|
|
9179 Given any byte position, the beginning of the character it is
|
|
|
9180 within can be determined in constant time.
|
|
|
9181 @item
|
|
|
9182 Given any byte position at the beginning of a character, the
|
|
|
9183 beginning of the next character can be determined in constant
|
|
|
9184 time.
|
|
|
9185 @item
|
|
|
9186 Given any byte position at the beginning of a character, the
|
|
|
9187 beginning of the previous character can be determined in constant
|
|
|
9188 time.
|
|
|
9189 @item
|
|
|
9190 Textual searches can simply treat encoded strings as if they
|
|
|
9191 were encoded in a one-byte-per-character fashion rather than
|
|
|
9192 the actual multi-byte encoding.
|
|
|
9193 @end enumerate
|
|
|
9194
|
|
|
9195 None of the standard non-modal encodings meet all of these
|
|
|
9196 conditions. For example, EUC satisfies only (2) and (3), while
|
|
|
9197 Shift-JIS and Big5 (not yet described) satisfy only (2). (All
|
|
|
9198 non-modal encodings must satisfy (2), in order to be unambiguous.)
|
|
|
9199
|
|
462
|
9200 @node Internal Character Encoding
|
|
428
|
9201 @subsection Internal Character Encoding
|
|
462
|
9202 @cindex internal character encoding
|
|
|
9203 @cindex character encoding, internal
|
|
|
9204 @cindex encoding, internal character
|
|
428
|
9205
|
|
|
9206 One 19-bit word represents a single character. The word is
|
|
|
9207 separated into three fields:
|
|
|
9208
|
|
|
9209 @example
|
|
|
9210 Bit number: 18 17 16 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
|
|
|
9211 <------------> <------------------> <------------------>
|
|
|
9212 Field: 1 2 3
|
|
|
9213 @end example
|
|
|
9214
|
|
|
9215 Note that fields 2 and 3 hold 7 bits each, while field 1 holds 5 bits.
|
|
|
9216
|
|
|
9217 @example
|
|
|
9218 Character set Field 1 Field 2 Field 3
|
|
|
9219 ------------- ------- ------- -------
|
|
|
9220 ASCII 0 0 PC1
|
|
|
9221 range: (00 - 7F)
|
|
|
9222 Control-1 0 1 PC1
|
|
|
9223 range: (00 - 1F)
|
|
|
9224 Dimension-1 official 0 LB - 0x80 PC1
|
|
|
9225 range: (01 - 0D) (20 - 7F)
|
|
|
9226 Dimension-1 private 0 LB - 0x80 PC1
|
|
|
9227 range: (20 - 6F) (20 - 7F)
|
|
|
9228 Dimension-2 official LB - 0x8F PC1 PC2
|
|
|
9229 range: (01 - 0A) (20 - 7F) (20 - 7F)
|
|
|
9230 Dimension-2 private LB - 0xE1 PC1 PC2
|
|
|
9231 range: (0F - 1E) (20 - 7F) (20 - 7F)
|
|
|
9232 Composite 0x1F ? ?
|
|
|
9233 @end example
|
|
|
9234
|
|
|
9235 Note that character codes 0 - 255 are the same as the ``binary encoding''
|
|
|
9236 described above.
|
|
|
9237
|
|
462
|
9238 @node CCL
|
|
428
|
9239 @section CCL
|
|
462
|
9240 @cindex CCL
|
|
428
|
9241
|
|
|
9242 @example
|
|
|
9243 CCL PROGRAM SYNTAX:
|
|
|
9244 CCL_PROGRAM := (CCL_MAIN_BLOCK
|
|
|
9245 [ CCL_EOF_BLOCK ])
|
|
|
9246
|
|
|
9247 CCL_MAIN_BLOCK := CCL_BLOCK
|
|
|
9248 CCL_EOF_BLOCK := CCL_BLOCK
|
|
|
9249
|
|
|
9250 CCL_BLOCK := STATEMENT | (STATEMENT [STATEMENT ...])
|
|
|
9251 STATEMENT :=
|
|
|
9252 SET | IF | BRANCH | LOOP | REPEAT | BREAK
|
|
|
9253 | READ | WRITE
|
|
|
9254
|
|
|
9255 SET := (REG = EXPRESSION) | (REG SELF_OP EXPRESSION)
|
|
|
9256 | INT-OR-CHAR
|
|
|
9257
|
|
|
9258 EXPRESSION := ARG | (EXPRESSION OP ARG)
|
|
|
9259
|
|
|
9260 IF := (if EXPRESSION CCL_BLOCK CCL_BLOCK)
|
|
|
9261 BRANCH := (branch EXPRESSION CCL_BLOCK [CCL_BLOCK ...])
|
|
|
9262 LOOP := (loop STATEMENT [STATEMENT ...])
|
|
|
9263 BREAK := (break)
|
|
|
9264 REPEAT := (repeat)
|
|
|
9265 | (write-repeat [REG | INT-OR-CHAR | string])
|
|
|
9266 | (write-read-repeat REG [INT-OR-CHAR | string | ARRAY]?)
|
|
|
9267 READ := (read REG) | (read REG REG)
|
|
|
9268 | (read-if REG ARITH_OP ARG CCL_BLOCK CCL_BLOCK)
|
|
|
9269 | (read-branch REG CCL_BLOCK [CCL_BLOCK ...])
|
|
|
9270 WRITE := (write REG) | (write REG REG)
|
|
|
9271 | (write INT-OR-CHAR) | (write STRING) | STRING
|
|
|
9272 | (write REG ARRAY)
|
|
|
9273 END := (end)
|
|
|
9274
|
|
|
9275 REG := r0 | r1 | r2 | r3 | r4 | r5 | r6 | r7
|
|
|
9276 ARG := REG | INT-OR-CHAR
|
|
|
9277 OP := + | - | * | / | % | & | '|' | ^ | << | >> | <8 | >8 | //
|
|
|
9278 | < | > | == | <= | >= | !=
|
|
|
9279 SELF_OP :=
|
|
|
9280 += | -= | *= | /= | %= | &= | '|=' | ^= | <<= | >>=
|
|
|
9281 ARRAY := '[' INT-OR-CHAR ... ']'
|
|
|
9282 INT-OR-CHAR := INT | CHAR
|
|
|
9283
|
|
|
9284 MACHINE CODE:
|
|
|
9285
|
|
|
9286 The machine code consists of a vector of 32-bit words.
|
|
|
9287 The first such word specifies the start of the EOF section of the code;
|
|
|
9288 this is the code executed to handle any stuff that needs to be done
|
|
|
9289 (e.g. designating back to ASCII and left-to-right mode) after all
|
|
|
9290 other encoded/decoded data has been written out. This is not used for
|
|
|
9291 charset CCL programs.
|
|
|
9292
|
|
442
|
9293 REGISTER: 0..7 -- referred by RRR or rrr
|
|
428
|
9294
|
|
|
9295 OPERATOR BIT FIELD (27-bit): XXXXXXXXXXXXXXX RRR TTTTT
|
|
|
9296 TTTTT (5-bit): operator type
|
|
|
9297 RRR (3-bit): register number
|
|
|
9298 XXXXXXXXXXXXXXXX (15-bit):
|
|
|
9299 CCCCCCCCCCCCCCC: constant or address
|
|
|
9300 000000000000rrr: register number
|
|
|
9301
|
|
|
9302 AAAA: 00000 +
|
|
|
9303 00001 -
|
|
|
9304 00010 *
|
|
|
9305 00011 /
|
|
|
9306 00100 %
|
|
|
9307 00101 &
|
|
|
9308 00110 |
|
|
|
9309 00111 ~
|
|
|
9310
|
|
|
9311 01000 <<
|
|
|
9312 01001 >>
|
|
|
9313 01010 <8
|
|
|
9314 01011 >8
|
|
|
9315 01100 //
|
|
|
9316 01101 not used
|
|
|
9317 01110 not used
|
|
|
9318 01111 not used
|
|
|
9319
|
|
|
9320 10000 <
|
|
|
9321 10001 >
|
|
|
9322 10010 ==
|
|
|
9323 10011 <=
|
|
|
9324 10100 >=
|
|
|
9325 10101 !=
|
|
|
9326
|
|
|
9327 OPERATORS: TTTTT RRR XX..
|
|
|
9328
|
|
|
9329 SetCS: 00000 RRR C...C RRR = C...C
|
|
|
9330 SetCL: 00001 RRR ..... RRR = c...c
|
|
|
9331 c.............c
|
|
|
9332 SetR: 00010 RRR ..rrr RRR = rrr
|
|
|
9333 SetA: 00011 RRR ..rrr RRR = array[rrr]
|
|
|
9334 C.............C size of array = C...C
|
|
|
9335 c.............c contents = c...c
|
|
|
9336
|
|
|
9337 Jump: 00100 000 c...c jump to c...c
|
|
|
9338 JumpCond: 00101 RRR c...c if (!RRR) jump to c...c
|
|
|
9339 WriteJump: 00110 RRR c...c Write1 RRR, jump to c...c
|
|
|
9340 WriteReadJump: 00111 RRR c...c Write1, Read1 RRR, jump to c...c
|
|
|
9341 WriteCJump: 01000 000 c...c Write1 C...C, jump to c...c
|
|
|
9342 C...C
|
|
|
9343 WriteCReadJump: 01001 RRR c...c Write1 C...C, Read1 RRR,
|
|
|
9344 C.............C and jump to c...c
|
|
|
9345 WriteSJump: 01010 000 c...c WriteS, jump to c...c
|
|
|
9346 C.............C
|
|
|
9347 S.............S
|
|
|
9348 ...
|
|
|
9349 WriteSReadJump: 01011 RRR c...c WriteS, Read1 RRR, jump to c...c
|
|
|
9350 C.............C
|
|
|
9351 S.............S
|
|
|
9352 ...
|
|
|
9353 WriteAReadJump: 01100 RRR c...c WriteA, Read1 RRR, jump to c...c
|
|
|
9354 C.............C size of array = C...C
|
|
|
9355 c.............c contents = c...c
|
|
|
9356 ...
|
|
|
9357 Branch: 01101 RRR C...C if (RRR >= 0 && RRR < C..)
|
|
|
9358 c.............c branch to (RRR+1)th address
|
|
|
9359 Read1: 01110 RRR ... read 1-byte to RRR
|
|
|
9360 Read2: 01111 RRR ..rrr read 2-byte to RRR and rrr
|
|
|
9361 ReadBranch: 10000 RRR C...C Read1 and Branch
|
|
|
9362 c.............c
|
|
|
9363 ...
|
|
|
9364 Write1: 10001 RRR ..... write 1-byte RRR
|
|
|
9365 Write2: 10010 RRR ..rrr write 2-byte RRR and rrr
|
|
|
9366 WriteC: 10011 000 ..... write 1-char C...CC
|
|
|
9367 C.............C
|
|
|
9368 WriteS: 10100 000 ..... write C..-byte of string
|
|
|
9369 C.............C
|
|
|
9370 S.............S
|
|
|
9371 ...
|
|
|
9372 WriteA: 10101 RRR ..... write array[RRR]
|
|
|
9373 C.............C size of array = C...C
|
|
|
9374 c.............c contents = c...c
|
|
|
9375 ...
|
|
|
9376 End: 10110 000 ..... terminate the execution
|
|
|
9377
|
|
|
9378 SetSelfCS: 10111 RRR C...C RRR AAAAA= C...C
|
|
|
9379 ..........AAAAA
|
|
|
9380 SetSelfCL: 11000 RRR ..... RRR AAAAA= c...c
|
|
|
9381 c.............c
|
|
|
9382 ..........AAAAA
|
|
|
9383 SetSelfR: 11001 RRR ..Rrr RRR AAAAA= rrr
|
|
|
9384 ..........AAAAA
|
|
|
9385 SetExprCL: 11010 RRR ..Rrr RRR = rrr AAAAA c...c
|
|
|
9386 c.............c
|
|
|
9387 ..........AAAAA
|
|
|
9388 SetExprR: 11011 RRR ..rrr RRR = rrr AAAAA Rrr
|
|
|
9389 ............Rrr
|
|
|
9390 ..........AAAAA
|
|
|
9391 JumpCondC: 11100 RRR c...c if !(RRR AAAAA C..) jump to c...c
|
|
|
9392 C.............C
|
|
|
9393 ..........AAAAA
|
|
|
9394 JumpCondR: 11101 RRR c...c if !(RRR AAAAA rrr) jump to c...c
|
|
|
9395 ............rrr
|
|
|
9396 ..........AAAAA
|
|
|
9397 ReadJumpCondC: 11110 RRR c...c Read1 and JumpCondC
|
|
|
9398 C.............C
|
|
|
9399 ..........AAAAA
|
|
|
9400 ReadJumpCondR: 11111 RRR c...c Read1 and JumpCondR
|
|
|
9401 ............rrr
|
|
|
9402 ..........AAAAA
|
|
|
9403 @end example
|
|
|
9404
|
|
|
9405 @node The Lisp Reader and Compiler, Lstreams, MULE Character Sets and Encodings, Top
|
|
|
9406 @chapter The Lisp Reader and Compiler
|
|
462
|
9407 @cindex Lisp reader and compiler, the
|
|
|
9408 @cindex reader and compiler, the Lisp
|
|
|
9409 @cindex compiler, the Lisp reader and
|
|
428
|
9410
|
|
|
9411 Not yet documented.
|
|
|
9412
|
|
|
9413 @node Lstreams, Consoles; Devices; Frames; Windows, The Lisp Reader and Compiler, Top
|
|
|
9414 @chapter Lstreams
|
|
462
|
9415 @cindex lstreams
|
|
428
|
9416
|
|
|
9417 An @dfn{lstream} is an internal Lisp object that provides a generic
|
|
|
9418 buffering stream implementation. Conceptually, you send data to the
|
|
|
9419 stream or read data from the stream, not caring what's on the other end
|
|
|
9420 of the stream. The other end could be another stream, a file
|
|
|
9421 descriptor, a stdio stream, a fixed block of memory, a reallocating
|
|
|
9422 block of memory, etc. The main purpose of the stream is to provide a
|
|
|
9423 standard interface and to do buffering. Macros are defined to read or
|
|
|
9424 write characters, so the calling functions do not have to worry about
|
|
|
9425 blocking data together in order to achieve efficiency.
|
|
|
9426
|
|
|
9427 @menu
|
|
|
9428 * Creating an Lstream:: Creating an lstream object.
|
|
|
9429 * Lstream Types:: Different sorts of things that are streamed.
|
|
|
9430 * Lstream Functions:: Functions for working with lstreams.
|
|
|
9431 * Lstream Methods:: Creating new lstream types.
|
|
|
9432 @end menu
|
|
|
9433
|
|
462
|
9434 @node Creating an Lstream
|
|
428
|
9435 @section Creating an Lstream
|
|
462
|
9436 @cindex lstream, creating an
|
|
428
|
9437
|
|
|
9438 Lstreams come in different types, depending on what is being interfaced
|
|
|
9439 to. Although the primitive for creating new lstreams is
|
|
|
9440 @code{Lstream_new()}, generally you do not call this directly. Instead,
|
|
|
9441 you call some type-specific creation function, which creates the lstream
|
|
|
9442 and initializes it as appropriate for the particular type.
|
|
|
9443
|
|
|
9444 All lstream creation functions take a @var{mode} argument, specifying
|
|
|
9445 what mode the lstream should be opened as. This controls whether the
|
|
|
9446 lstream is for input and output, and optionally whether data should be
|
|
|
9447 blocked up in units of MULE characters. Note that some types of
|
|
|
9448 lstreams can only be opened for input; others only for output; and
|
|
|
9449 others can be opened either way. #### Richard Mlynarik thinks that
|
|
|
9450 there should be a strict separation between input and output streams,
|
|
|
9451 and he's probably right.
|
|
|
9452
|
|
|
9453 @var{mode} is a string, one of
|
|
|
9454
|
|
|
9455 @table @code
|
|
|
9456 @item "r"
|
|
|
9457 Open for reading.
|
|
|
9458 @item "w"
|
|
|
9459 Open for writing.
|
|
|
9460 @item "rc"
|
|
|
9461 Open for reading, but ``read'' never returns partial MULE characters.
|
|
|
9462 @item "wc"
|
|
|
9463 Open for writing, but never writes partial MULE characters.
|
|
|
9464 @end table
|
|
|
9465
|
|
462
|
9466 @node Lstream Types
|
|
428
|
9467 @section Lstream Types
|
|
462
|
9468 @cindex lstream types
|
|
|
9469 @cindex types, lstream
|
|
428
|
9470
|
|
|
9471 @table @asis
|
|
|
9472 @item stdio
|
|
|
9473
|
|
|
9474 @item filedesc
|
|
|
9475
|
|
|
9476 @item lisp-string
|
|
|
9477
|
|
|
9478 @item fixed-buffer
|
|
|
9479
|
|
|
9480 @item resizing-buffer
|
|
|
9481
|
|
|
9482 @item dynarr
|
|
|
9483
|
|
|
9484 @item lisp-buffer
|
|
|
9485
|
|
|
9486 @item print
|
|
|
9487
|
|
|
9488 @item decoding
|
|
|
9489
|
|
|
9490 @item encoding
|
|
|
9491 @end table
|
|
|
9492
|
|
462
|
9493 @node Lstream Functions
|
|
428
|
9494 @section Lstream Functions
|
|
462
|
9495 @cindex lstream functions
|
|
428
|
9496
|
|
442
|
9497 @deftypefun {Lstream *} Lstream_new (Lstream_implementation *@var{imp}, const char *@var{mode})
|
|
428
|
9498 Allocate and return a new Lstream. This function is not really meant to
|
|
|
9499 be called directly; rather, each stream type should provide its own
|
|
|
9500 stream creation function, which creates the stream and does any other
|
|
|
9501 necessary creation stuff (e.g. opening a file).
|
|
|
9502 @end deftypefun
|
|
|
9503
|
|
|
9504 @deftypefun void Lstream_set_buffering (Lstream *@var{lstr}, Lstream_buffering @var{buffering}, int @var{buffering_size})
|
|
|
9505 Change the buffering of a stream. See @file{lstream.h}. By default the
|
|
|
9506 buffering is @code{STREAM_BLOCK_BUFFERED}.
|
|
|
9507 @end deftypefun
|
|
|
9508
|
|
|
9509 @deftypefun int Lstream_flush (Lstream *@var{lstr})
|
|
|
9510 Flush out any pending unwritten data in the stream. Clear any buffered
|
|
|
9511 input data. Returns 0 on success, -1 on error.
|
|
|
9512 @end deftypefun
|
|
|
9513
|
|
|
9514 @deftypefn Macro int Lstream_putc (Lstream *@var{stream}, int @var{c})
|
|
|
9515 Write out one byte to the stream. This is a macro and so it is very
|
|
|
9516 efficient. The @var{c} argument is only evaluated once but the @var{stream}
|
|
|
9517 argument is evaluated more than once. Returns 0 on success, -1 on
|
|
|
9518 error.
|
|
|
9519 @end deftypefn
|
|
|
9520
|
|
|
9521 @deftypefn Macro int Lstream_getc (Lstream *@var{stream})
|
|
|
9522 Read one byte from the stream. This is a macro and so it is very
|
|
|
9523 efficient. The @var{stream} argument is evaluated more than once. Return
|
|
|
9524 value is -1 for EOF or error.
|
|
|
9525 @end deftypefn
|
|
|
9526
|
|
|
9527 @deftypefn Macro void Lstream_ungetc (Lstream *@var{stream}, int @var{c})
|
|
|
9528 Push one byte back onto the input queue. This will be the next byte
|
|
|
9529 read from the stream. Any number of bytes can be pushed back and will
|
|
440
|
9530 be read in the reverse order they were pushed back---most recent
|
|
|
9531 first. (This is necessary for consistency---if there are a number of
|
|
428
|
9532 bytes that have been unread and I read and unread a byte, it needs to be
|
|
|
9533 the first to be read again.) This is a macro and so it is very
|
|
|
9534 efficient. The @var{c} argument is only evaluated once but the @var{stream}
|
|
|
9535 argument is evaluated more than once.
|
|
|
9536 @end deftypefn
|
|
|
9537
|
|
|
9538 @deftypefun int Lstream_fputc (Lstream *@var{stream}, int @var{c})
|
|
|
9539 @deftypefunx int Lstream_fgetc (Lstream *@var{stream})
|
|
|
9540 @deftypefunx void Lstream_fungetc (Lstream *@var{stream}, int @var{c})
|
|
|
9541 Function equivalents of the above macros.
|
|
|
9542 @end deftypefun
|
|
|
9543
|
|
1261
|
9544 @deftypefun Bytecount Lstream_read (Lstream *@var{stream}, void *@var{data}, Bytecount @var{size})
|
|
428
|
9545 Read @var{size} bytes of @var{data} from the stream. Return the number
|
|
|
9546 of bytes read. 0 means EOF. -1 means an error occurred and no bytes
|
|
|
9547 were read.
|
|
|
9548 @end deftypefun
|
|
|
9549
|
|
1261
|
9550 @deftypefun Bytecount Lstream_write (Lstream *@var{stream}, void *@var{data}, Bytecount @var{size})
|
|
428
|
9551 Write @var{size} bytes of @var{data} to the stream. Return the number
|
|
|
9552 of bytes written. -1 means an error occurred and no bytes were written.
|
|
|
9553 @end deftypefun
|
|
|
9554
|
|
1261
|
9555 @deftypefun void Lstream_unread (Lstream *@var{stream}, void *@var{data}, Bytecount @var{size})
|
|
428
|
9556 Push back @var{size} bytes of @var{data} onto the input queue. The next
|
|
|
9557 call to @code{Lstream_read()} with the same size will read the same
|
|
|
9558 bytes back. Note that this will be the case even if there is other
|
|
|
9559 pending unread data.
|
|
|
9560 @end deftypefun
|
|
|
9561
|
|
|
9562 @deftypefun int Lstream_close (Lstream *@var{stream})
|
|
|
9563 Close the stream. All data will be flushed out.
|
|
|
9564 @end deftypefun
|
|
|
9565
|
|
|
9566 @deftypefun void Lstream_reopen (Lstream *@var{stream})
|
|
|
9567 Reopen a closed stream. This enables I/O on it again. This is not
|
|
|
9568 meant to be called except from a wrapper routine that reinitializes
|
|
440
|
9569 variables and such---the close routine may well have freed some
|
|
428
|
9570 necessary storage structures, for example.
|
|
|
9571 @end deftypefun
|
|
|
9572
|
|
|
9573 @deftypefun void Lstream_rewind (Lstream *@var{stream})
|
|
|
9574 Rewind the stream to the beginning.
|
|
|
9575 @end deftypefun
|
|
|
9576
|
|
462
|
9577 @node Lstream Methods
|
|
428
|
9578 @section Lstream Methods
|
|
462
|
9579 @cindex lstream methods
|
|
428
|
9580
|
|
1261
|
9581 @deftypefn {Lstream Method} Bytecount reader (Lstream *@var{stream}, unsigned char *@var{data}, Bytecount @var{size})
|
|
428
|
9582 Read some data from the stream's end and store it into @var{data}, which
|
|
|
9583 can hold @var{size} bytes. Return the number of bytes read. A return
|
|
|
9584 value of 0 means no bytes can be read at this time. This may be because
|
|
|
9585 of an EOF, or because there is a granularity greater than one byte that
|
|
|
9586 the stream imposes on the returned data, and @var{size} is less than
|
|
|
9587 this granularity. (This will happen frequently for streams that need to
|
|
|
9588 return whole characters, because @code{Lstream_read()} calls the reader
|
|
|
9589 function repeatedly until it has the number of bytes it wants or until 0
|
|
|
9590 is returned.) The lstream functions do not treat a 0 return as EOF or
|
|
|
9591 do anything special; however, the calling function will interpret any 0
|
|
|
9592 it gets back as EOF. This will normally not happen unless the caller
|
|
|
9593 calls @code{Lstream_read()} with a very small size.
|
|
|
9594
|
|
|
9595 This function can be @code{NULL} if the stream is output-only.
|
|
|
9596 @end deftypefn
|
|
|
9597
|
|
1261
|
9598 @deftypefn {Lstream Method} Bytecount writer (Lstream *@var{stream}, const unsigned char *@var{data}, Bytecount @var{size})
|
|
428
|
9599 Send some data to the stream's end. Data to be sent is in @var{data}
|
|
|
9600 and is @var{size} bytes. Return the number of bytes sent. This
|
|
|
9601 function can send and return fewer bytes than is passed in; in that
|
|
|
9602 case, the function will just be called again until there is no data left
|
|
|
9603 or 0 is returned. A return value of 0 means that no more data can be
|
|
|
9604 currently stored, but there is no error; the data will be squirreled
|
|
|
9605 away until the writer can accept data. (This is useful, e.g., if you're
|
|
|
9606 dealing with a non-blocking file descriptor and are getting
|
|
|
9607 @code{EWOULDBLOCK} errors.) This function can be @code{NULL} if the
|
|
|
9608 stream is input-only.
|
|
|
9609 @end deftypefn
|
|
|
9610
|
|
|
9611 @deftypefn {Lstream Method} int rewinder (Lstream *@var{stream})
|
|
|
9612 Rewind the stream. If this is @code{NULL}, the stream is not seekable.
|
|
|
9613 @end deftypefn
|
|
|
9614
|
|
|
9615 @deftypefn {Lstream Method} int seekable_p (Lstream *@var{stream})
|
|
440
|
9616 Indicate whether this stream is seekable---i.e. it can be rewound.
|
|
428
|
9617 This method is ignored if the stream does not have a rewind method. If
|
|
|
9618 this method is not present, the result is determined by whether a rewind
|
|
|
9619 method is present.
|
|
|
9620 @end deftypefn
|
|
|
9621
|
|
|
9622 @deftypefn {Lstream Method} int flusher (Lstream *@var{stream})
|
|
|
9623 Perform any additional operations necessary to flush the data in this
|
|
|
9624 stream.
|
|
|
9625 @end deftypefn
|
|
|
9626
|
|
|
9627 @deftypefn {Lstream Method} int pseudo_closer (Lstream *@var{stream})
|
|
|
9628 @end deftypefn
|
|
|
9629
|
|
|
9630 @deftypefn {Lstream Method} int closer (Lstream *@var{stream})
|
|
|
9631 Perform any additional operations necessary to close this stream down.
|
|
|
9632 May be @code{NULL}. This function is called when @code{Lstream_close()}
|
|
|
9633 is called or when the stream is garbage-collected. When this function
|
|
|
9634 is called, all pending data in the stream will already have been written
|
|
|
9635 out.
|
|
|
9636 @end deftypefn
|
|
|
9637
|
|
|
9638 @deftypefn {Lstream Method} Lisp_Object marker (Lisp_Object @var{lstream}, void (*@var{markfun}) (Lisp_Object))
|
|
|
9639 Mark this object for garbage collection. Same semantics as a standard
|
|
|
9640 @code{Lisp_Object} marker. This function can be @code{NULL}.
|
|
|
9641 @end deftypefn
|
|
|
9642
|
|
|
9643 @node Consoles; Devices; Frames; Windows, The Redisplay Mechanism, Lstreams, Top
|
|
|
9644 @chapter Consoles; Devices; Frames; Windows
|
|
462
|
9645 @cindex consoles; devices; frames; windows
|
|
|
9646 @cindex devices; frames; windows, consoles;
|
|
|
9647 @cindex frames; windows, consoles; devices;
|
|
|
9648 @cindex windows, consoles; devices; frames;
|
|
428
|
9649
|
|
|
9650 @menu
|
|
|
9651 * Introduction to Consoles; Devices; Frames; Windows::
|
|
|
9652 * Point::
|
|
|
9653 * Window Hierarchy::
|
|
|
9654 * The Window Object::
|
|
|
9655 @end menu
|
|
|
9656
|
|
462
|
9657 @node Introduction to Consoles; Devices; Frames; Windows
|
|
428
|
9658 @section Introduction to Consoles; Devices; Frames; Windows
|
|
462
|
9659 @cindex consoles; devices; frames; windows, introduction to
|
|
|
9660 @cindex devices; frames; windows, introduction to consoles;
|
|
|
9661 @cindex frames; windows, introduction to consoles; devices;
|
|
|
9662 @cindex windows, introduction to consoles; devices; frames;
|
|
428
|
9663
|
|
|
9664 A window-system window that you see on the screen is called a
|
|
|
9665 @dfn{frame} in Emacs terminology. Each frame is subdivided into one or
|
|
|
9666 more non-overlapping panes, called (confusingly) @dfn{windows}. Each
|
|
|
9667 window displays the text of a buffer in it. (See above on Buffers.) Note
|
|
|
9668 that buffers and windows are independent entities: Two or more windows
|
|
|
9669 can be displaying the same buffer (potentially in different locations),
|
|
|
9670 and a buffer can be displayed in no windows.
|
|
|
9671
|
|
|
9672 A single display screen that contains one or more frames is called
|
|
|
9673 a @dfn{display}. Under most circumstances, there is only one display.
|
|
|
9674 However, more than one display can exist, for example if you have
|
|
|
9675 a @dfn{multi-headed} console, i.e. one with a single keyboard but
|
|
|
9676 multiple displays. (Typically in such a situation, the various
|
|
|
9677 displays act like one large display, in that the mouse is only
|
|
|
9678 in one of them at a time, and moving the mouse off of one moves
|
|
|
9679 it into another.) In some cases, the different displays will
|
|
|
9680 have different characteristics, e.g. one color and one mono.
|
|
|
9681
|
|
|
9682 XEmacs can display frames on multiple displays. It can even deal
|
|
|
9683 simultaneously with frames on multiple keyboards (called @dfn{consoles} in
|
|
|
9684 XEmacs terminology). Here is one case where this might be useful: You
|
|
|
9685 are using XEmacs on your workstation at work, and leave it running.
|
|
|
9686 Then you go home and dial in on a TTY line, and you can use the
|
|
|
9687 already-running XEmacs process to display another frame on your local
|
|
|
9688 TTY.
|
|
|
9689
|
|
|
9690 Thus, there is a hierarchy console -> display -> frame -> window.
|
|
|
9691 There is a separate Lisp object type for each of these four concepts.
|
|
|
9692 Furthermore, there is logically a @dfn{selected console},
|
|
|
9693 @dfn{selected display}, @dfn{selected frame}, and @dfn{selected window}.
|
|
|
9694 Each of these objects is distinguished in various ways, such as being the
|
|
|
9695 default object for various functions that act on objects of that type.
|
|
442
|
9696 Note that every containing object remembers the ``selected'' object
|
|
428
|
9697 among the objects that it contains: e.g. not only is there a selected
|
|
|
9698 window, but every frame remembers the last window in it that was
|
|
|
9699 selected, and changing the selected frame causes the remembered window
|
|
|
9700 within it to become the selected window. Similar relationships apply
|
|
|
9701 for consoles to devices and devices to frames.
|
|
|
9702
|
|
462
|
9703 @node Point
|
|
428
|
9704 @section Point
|
|
462
|
9705 @cindex point
|
|
428
|
9706
|
|
|
9707 Recall that every buffer has a current insertion position, called
|
|
|
9708 @dfn{point}. Now, two or more windows may be displaying the same buffer,
|
|
|
9709 and the text cursor in the two windows (i.e. @code{point}) can be in
|
|
|
9710 two different places. You may ask, how can that be, since each
|
|
|
9711 buffer has only one value of @code{point}? The answer is that each window
|
|
|
9712 also has a value of @code{point} that is squirreled away in it. There
|
|
|
9713 is only one selected window, and the value of ``point'' in that buffer
|
|
|
9714 corresponds to that window. When the selected window is changed
|
|
|
9715 from one window to another displaying the same buffer, the old
|
|
|
9716 value of @code{point} is stored into the old window's ``point'' and the
|
|
|
9717 value of @code{point} from the new window is retrieved and made the
|
|
|
9718 value of @code{point} in the buffer. This means that @code{window-point}
|
|
|
9719 for the selected window is potentially inaccurate, and if you
|
|
|
9720 want to retrieve the correct value of @code{point} for a window,
|
|
|
9721 you must special-case on the selected window and retrieve the
|
|
|
9722 buffer's point instead. This is related to why @code{save-window-excursion}
|
|
|
9723 does not save the selected window's value of @code{point}.
|
|
|
9724
|
|
462
|
9725 @node Window Hierarchy
|
|
428
|
9726 @section Window Hierarchy
|
|
|
9727 @cindex window hierarchy
|
|
|
9728 @cindex hierarchy of windows
|
|
|
9729
|
|
|
9730 If a frame contains multiple windows (panes), they are always created
|
|
|
9731 by splitting an existing window along the horizontal or vertical axis.
|
|
|
9732 Terminology is a bit confusing here: to @dfn{split a window
|
|
|
9733 horizontally} means to create two side-by-side windows, i.e. to make a
|
|
|
9734 @emph{vertical} cut in a window. Likewise, to @dfn{split a window
|
|
|
9735 vertically} means to create two windows, one above the other, by making
|
|
|
9736 a @emph{horizontal} cut.
|
|
|
9737
|
|
|
9738 If you split a window and then split again along the same axis, you
|
|
|
9739 will end up with a number of panes all arranged along the same axis.
|
|
|
9740 The precise way in which the splits were made should not be important,
|
|
|
9741 and this is reflected internally. Internally, all windows are arranged
|
|
|
9742 in a tree, consisting of two types of windows, @dfn{combination} windows
|
|
|
9743 (which have children, and are covered completely by those children) and
|
|
|
9744 @dfn{leaf} windows, which have no children and are visible. Every
|
|
|
9745 combination window has two or more children, all arranged along the same
|
|
|
9746 axis. There are (logically) two subtypes of windows, depending on
|
|
|
9747 whether their children are horizontally or vertically arrayed. There is
|
|
|
9748 always one root window, which is either a leaf window (if the frame
|
|
|
9749 contains only one window) or a combination window (if the frame contains
|
|
|
9750 more than one window). In the latter case, the root window will have
|
|
|
9751 two or more children, either horizontally or vertically arrayed, and
|
|
|
9752 each of those children will be either a leaf window or another
|
|
|
9753 combination window.
|
|
|
9754
|
|
|
9755 Here are some rules:
|
|
|
9756
|
|
|
9757 @enumerate
|
|
|
9758 @item
|
|
|
9759 Horizontal combination windows can never have children that are
|
|
|
9760 horizontal combination windows; same for vertical.
|
|
|
9761
|
|
|
9762 @item
|
|
|
9763 Only leaf windows can be split (obviously) and this splitting does one
|
|
|
9764 of two things: (a) turns the leaf window into a combination window and
|
|
|
9765 creates two new leaf children, or (b) turns the leaf window into one of
|
|
|
9766 the two new leaves and creates the other leaf. Rule (1) dictates which
|
|
|
9767 of these two outcomes happens.
|
|
|
9768
|
|
|
9769 @item
|
|
|
9770 Every combination window must have at least two children.
|
|
|
9771
|
|
|
9772 @item
|
|
|
9773 Leaf windows can never become combination windows. They can be deleted,
|
|
|
9774 however. If this results in a violation of (3), the parent combination
|
|
|
9775 window also gets deleted.
|
|
|
9776
|
|
|
9777 @item
|
|
|
9778 All functions that accept windows must be prepared to accept combination
|
|
|
9779 windows, and do something sane (e.g. signal an error if so).
|
|
|
9780 Combination windows @emph{do} escape to the Lisp level.
|
|
|
9781
|
|
|
9782 @item
|
|
|
9783 All windows have three fields governing their contents:
|
|
|
9784 these are @dfn{hchild} (a list of horizontally-arrayed children),
|
|
|
9785 @dfn{vchild} (a list of vertically-arrayed children), and @dfn{buffer}
|
|
|
9786 (the buffer contained in a leaf window). Exactly one of
|
|
444
|
9787 these will be non-@code{nil}. Remember that @dfn{horizontally-arrayed}
|
|
428
|
9788 means ``side-by-side'' and @dfn{vertically-arrayed} means
|
|
|
9789 @dfn{one above the other}.
|
|
|
9790
|
|
|
9791 @item
|
|
|
9792 Leaf windows also have markers in their @code{start} (the
|
|
|
9793 first buffer position displayed in the window) and @code{pointm}
|
|
440
|
9794 (the window's stashed value of @code{point}---see above) fields,
|
|
444
|
9795 while combination windows have @code{nil} in these fields.
|
|
428
|
9796
|
|
|
9797 @item
|
|
|
9798 The list of children for a window is threaded through the
|
|
|
9799 @code{next} and @code{prev} fields of each child window.
|
|
|
9800
|
|
|
9801 @item
|
|
|
9802 @strong{Deleted windows can be undeleted}. This happens as a result of
|
|
|
9803 restoring a window configuration, and is unlike frames, displays, and
|
|
|
9804 consoles, which, once deleted, can never be restored. Deleting a window
|
|
|
9805 does nothing except set a special @code{dead} bit to 1 and clear out the
|
|
|
9806 @code{next}, @code{prev}, @code{hchild}, and @code{vchild} fields, for
|
|
|
9807 GC purposes.
|
|
|
9808
|
|
|
9809 @item
|
|
440
|
9810 Most frames actually have two top-level windows---one for the
|
|
428
|
9811 minibuffer and one (the @dfn{root}) for everything else. The modeline
|
|
|
9812 (if present) separates these two. The @code{next} field of the root
|
|
|
9813 points to the minibuffer, and the @code{prev} field of the minibuffer
|
|
|
9814 points to the root. The other @code{next} and @code{prev} fields are
|
|
|
9815 @code{nil}, and the frame points to both of these windows.
|
|
|
9816 Minibuffer-less frames have no minibuffer window, and the @code{next}
|
|
|
9817 and @code{prev} of the root window are @code{nil}. Minibuffer-only
|
|
|
9818 frames have no root window, and the @code{next} of the minibuffer window
|
|
|
9819 is @code{nil} but the @code{prev} points to itself. (#### This is an
|
|
|
9820 artifact that should be fixed.)
|
|
|
9821 @end enumerate
|
|
|
9822
|
|
462
|
9823 @node The Window Object
|
|
428
|
9824 @section The Window Object
|
|
462
|
9825 @cindex window object, the
|
|
|
9826 @cindex object, the window
|
|
428
|
9827
|
|
|
9828 Windows have the following accessible fields:
|
|
|
9829
|
|
|
9830 @table @code
|
|
|
9831 @item frame
|
|
|
9832 The frame that this window is on.
|
|
|
9833
|
|
|
9834 @item mini_p
|
|
|
9835 Non-@code{nil} if this window is a minibuffer window.
|
|
|
9836
|
|
|
9837 @item buffer
|
|
|
9838 The buffer that the window is displaying. This may change often during
|
|
|
9839 the life of the window.
|
|
|
9840
|
|
|
9841 @item dedicated
|
|
|
9842 Non-@code{nil} if this window is dedicated to its buffer.
|
|
|
9843
|
|
|
9844 @item pointm
|
|
|
9845 @cindex window point internals
|
|
|
9846 This is the value of point in the current buffer when this window is
|
|
|
9847 selected; when it is not selected, it retains its previous value.
|
|
|
9848
|
|
|
9849 @item start
|
|
|
9850 The position in the buffer that is the first character to be displayed
|
|
|
9851 in the window.
|
|
|
9852
|
|
|
9853 @item force_start
|
|
|
9854 If this flag is non-@code{nil}, it says that the window has been
|
|
|
9855 scrolled explicitly by the Lisp program. This affects what the next
|
|
|
9856 redisplay does if point is off the screen: instead of scrolling the
|
|
|
9857 window to show the text around point, it moves point to a location that
|
|
|
9858 is on the screen.
|
|
|
9859
|
|
|
9860 @item last_modified
|
|
|
9861 The @code{modified} field of the window's buffer, as of the last time
|
|
|
9862 a redisplay completed in this window.
|
|
|
9863
|
|
|
9864 @item last_point
|
|
|
9865 The buffer's value of point, as of the last time
|
|
|
9866 a redisplay completed in this window.
|
|
|
9867
|
|
|
9868 @item left
|
|
|
9869 This is the left-hand edge of the window, measured in columns. (The
|
|
|
9870 leftmost column on the screen is @w{column 0}.)
|
|
|
9871
|
|
|
9872 @item top
|
|
|
9873 This is the top edge of the window, measured in lines. (The top line on
|
|
|
9874 the screen is @w{line 0}.)
|
|
|
9875
|
|
|
9876 @item height
|
|
|
9877 The height of the window, measured in lines.
|
|
|
9878
|
|
|
9879 @item width
|
|
|
9880 The width of the window, measured in columns.
|
|
|
9881
|
|
|
9882 @item next
|
|
|
9883 This is the window that is the next in the chain of siblings. It is
|
|
|
9884 @code{nil} in a window that is the rightmost or bottommost of a group of
|
|
|
9885 siblings.
|
|
|
9886
|
|
|
9887 @item prev
|
|
|
9888 This is the window that is the previous in the chain of siblings. It is
|
|
|
9889 @code{nil} in a window that is the leftmost or topmost of a group of
|
|
|
9890 siblings.
|
|
|
9891
|
|
|
9892 @item parent
|
|
|
9893 Internally, XEmacs arranges windows in a tree; each group of siblings has
|
|
|
9894 a parent window whose area includes all the siblings. This field points
|
|
|
9895 to a window's parent.
|
|
|
9896
|
|
|
9897 Parent windows do not display buffers, and play little role in display
|
|
|
9898 except to shape their child windows. Emacs Lisp programs usually have
|
|
|
9899 no access to the parent windows; they operate on the windows at the
|
|
|
9900 leaves of the tree, which actually display buffers.
|
|
|
9901
|
|
|
9902 @item hscroll
|
|
|
9903 This is the number of columns that the display in the window is scrolled
|
|
|
9904 horizontally to the left. Normally, this is 0.
|
|
|
9905
|
|
|
9906 @item use_time
|
|
|
9907 This is the last time that the window was selected. The function
|
|
|
9908 @code{get-lru-window} uses this field.
|
|
|
9909
|
|
|
9910 @item display_table
|
|
|
9911 The window's display table, or @code{nil} if none is specified for it.
|
|
|
9912
|
|
|
9913 @item update_mode_line
|
|
|
9914 Non-@code{nil} means this window's mode line needs to be updated.
|
|
|
9915
|
|
|
9916 @item base_line_number
|
|
|
9917 The line number of a certain position in the buffer, or @code{nil}.
|
|
|
9918 This is used for displaying the line number of point in the mode line.
|
|
|
9919
|
|
|
9920 @item base_line_pos
|
|
|
9921 The position in the buffer for which the line number is known, or
|
|
|
9922 @code{nil} meaning none is known.
|
|
|
9923
|
|
|
9924 @item region_showing
|
|
|
9925 If the region (or part of it) is highlighted in this window, this field
|
|
|
9926 holds the mark position that made one end of that region. Otherwise,
|
|
|
9927 this field is @code{nil}.
|
|
|
9928 @end table
|
|
|
9929
|
|
|
9930 @node The Redisplay Mechanism, Extents, Consoles; Devices; Frames; Windows, Top
|
|
|
9931 @chapter The Redisplay Mechanism
|
|
462
|
9932 @cindex redisplay mechanism, the
|
|
428
|
9933
|
|
|
9934 The redisplay mechanism is one of the most complicated sections of
|
|
|
9935 XEmacs, especially from a conceptual standpoint. This is doubly so
|
|
|
9936 because, unlike for the basic aspects of the Lisp interpreter, the
|
|
|
9937 computer science theories of how to efficiently handle redisplay are not
|
|
|
9938 well-developed.
|
|
|
9939
|
|
|
9940 When working with the redisplay mechanism, remember the Golden Rules
|
|
|
9941 of Redisplay:
|
|
|
9942
|
|
|
9943 @enumerate
|
|
|
9944 @item
|
|
|
9945 It Is Better To Be Correct Than Fast.
|
|
|
9946 @item
|
|
|
9947 Thou Shalt Not Run Elisp From Within Redisplay.
|
|
|
9948 @item
|
|
|
9949 It Is Better To Be Fast Than Not To Be.
|
|
|
9950 @end enumerate
|
|
|
9951
|
|
|
9952 @menu
|
|
|
9953 * Critical Redisplay Sections::
|
|
|
9954 * Line Start Cache::
|
|
|
9955 * Redisplay Piece by Piece::
|
|
|
9956 @end menu
|
|
|
9957
|
|
462
|
9958 @node Critical Redisplay Sections
|
|
428
|
9959 @section Critical Redisplay Sections
|
|
462
|
9960 @cindex redisplay sections, critical
|
|
428
|
9961 @cindex critical redisplay sections
|
|
|
9962
|
|
|
9963 Within this section, we are defenseless and assume that the
|
|
|
9964 following cannot happen:
|
|
|
9965
|
|
|
9966 @enumerate
|
|
|
9967 @item
|
|
|
9968 garbage collection
|
|
|
9969 @item
|
|
|
9970 Lisp code evaluation
|
|
|
9971 @item
|
|
|
9972 frame size changes
|
|
|
9973 @end enumerate
|
|
|
9974
|
|
|
9975 We ensure (3) by calling @code{hold_frame_size_changes()}, which
|
|
|
9976 will cause any pending frame size changes to get put on hold
|
|
|
9977 till after the end of the critical section. (1) follows
|
|
|
9978 automatically if (2) is met. #### Unfortunately, there are
|
|
|
9979 some places where Lisp code can be called within this section.
|
|
|
9980 We need to remove them.
|
|
|
9981
|
|
|
9982 If @code{Fsignal()} is called during this critical section, we
|
|
|
9983 will @code{abort()}.
|
|
|
9984
|
|
|
9985 If garbage collection is called during this critical section,
|
|
|
9986 we simply return. #### We should abort instead.
|
|
|
9987
|
|
|
9988 #### If a frame-size change does occur we should probably
|
|
|
9989 actually be preempting redisplay.
|
|
|
9990
|
|
462
|
9991 @node Line Start Cache
|
|
428
|
9992 @section Line Start Cache
|
|
|
9993 @cindex line start cache
|
|
|
9994
|
|
|
9995 The traditional scrolling code in Emacs breaks in a variable height
|
|
|
9996 world. It depends on the key assumption that the number of lines that
|
|
|
9997 can be displayed at any given time is fixed. This led to a complete
|
|
|
9998 separation of the scrolling code from the redisplay code. In order to
|
|
|
9999 fully support variable height lines, the scrolling code must actually be
|
|
|
10000 tightly integrated with redisplay. Only redisplay can determine how
|
|
|
10001 many lines will be displayed on a screen for any given starting point.
|
|
|
10002
|
|
|
10003 What is ideally wanted is a complete list of the starting buffer
|
|
|
10004 position for every possible display line of a buffer along with the
|
|
|
10005 height of that display line. Maintaining such a full list would be very
|
|
|
10006 expensive. We settle for having it include information for all areas
|
|
|
10007 which we happen to generate anyhow (i.e. the region currently being
|
|
|
10008 displayed) and for those areas we need to work with.
|
|
|
10009
|
|
|
10010 In order to ensure that the cache accurately represents what redisplay
|
|
|
10011 would actually show, it is necessary to invalidate it in many
|
|
|
10012 situations. If the buffer changes, the starting positions may no longer
|
|
|
10013 be correct. If a face or an extent has changed then the line heights
|
|
|
10014 may have altered. These events happen frequently enough that the cache
|
|
|
10015 can end up being constantly disabled. With this potentially constant
|
|
|
10016 invalidation when is the cache ever useful?
|
|
|
10017
|
|
|
10018 Even if the cache is invalidated before every single usage, it is
|
|
|
10019 necessary. Scrolling often requires knowledge about display lines which
|
|
|
10020 are actually above or below the visible region. The cache provides a
|
|
|
10021 convenient light-weight method of storing this information for multiple
|
|
|
10022 display regions. This knowledge is necessary for the scrolling code to
|
|
|
10023 always obey the First Golden Rule of Redisplay.
|
|
|
10024
|
|
|
10025 If the cache already contains all of the information that the scrolling
|
|
|
10026 routines happen to need so that it doesn't have to go generate it, then
|
|
|
10027 we are able to obey the Third Golden Rule of Redisplay. The first thing
|
|
|
10028 we do to help out the cache is to always add the displayed region. This
|
|
|
10029 region had to be generated anyway, so the cache ends up getting the
|
|
|
10030 information basically for free. In those cases where a user is simply
|
|
|
10031 scrolling around viewing a buffer there is a high probability that this
|
|
|
10032 is sufficient to always provide the needed information. The second
|
|
|
10033 thing we can do is be smart about invalidating the cache.
|
|
|
10034
|
|
440
|
10035 TODO---Be smart about invalidating the cache. Potential places:
|
|
428
|
10036
|
|
|
10037 @itemize @bullet
|
|
|
10038 @item
|
|
|
10039 Insertions at end-of-line which don't cause line-wraps do not alter the
|
|
|
10040 starting positions of any display lines. These types of buffer
|
|
|
10041 modifications should not invalidate the cache. This is actually a large
|
|
|
10042 optimization for redisplay speed as well.
|
|
|
10043 @item
|
|
|
10044 Buffer modifications frequently only affect the display of lines at and
|
|
|
10045 below where they occur. In these situations we should only invalidate
|
|
|
10046 the part of the cache starting at where the modification occurs.
|
|
|
10047 @end itemize
|
|
|
10048
|
|
|
10049 In case you're wondering, the Second Golden Rule of Redisplay is not
|
|
|
10050 applicable.
|
|
|
10051
|
|
462
|
10052 @node Redisplay Piece by Piece
|
|
428
|
10053 @section Redisplay Piece by Piece
|
|
462
|
10054 @cindex redisplay piece by piece
|
|
428
|
10055
|
|
|
10056 As you can begin to see redisplay is complex and also not well
|
|
|
10057 documented. Chuck no longer works on XEmacs so this section is my take
|
|
|
10058 on the workings of redisplay.
|
|
|
10059
|
|
|
10060 Redisplay happens in three phases:
|
|
|
10061
|
|
|
10062 @enumerate
|
|
|
10063 @item
|
|
|
10064 Determine desired display in area that needs redisplay.
|
|
|
10065 Implemented by @code{redisplay.c}
|
|
|
10066 @item
|
|
|
10067 Compare desired display with current display
|
|
|
10068 Implemented by @code{redisplay-output.c}
|
|
|
10069 @item
|
|
|
10070 Output changes Implemented by @code{redisplay-output.c},
|
|
|
10071 @code{redisplay-x.c}, @code{redisplay-msw.c} and @code{redisplay-tty.c}
|
|
|
10072 @end enumerate
|
|
|
10073
|
|
442
|
10074 Steps 1 and 2 are device-independent and relatively complex. Step 3 is
|
|
428
|
10075 mostly device-dependent.
|
|
|
10076
|
|
|
10077 Determining the desired display
|
|
|
10078
|
|
|
10079 Display attributes are stored in @code{display_line} structures. Each
|
|
|
10080 @code{display_line} consists of a set of @code{display_block}'s and each
|
|
|
10081 @code{display_block} contains a number of @code{rune}'s. Generally
|
|
|
10082 dynarr's of @code{display_line}'s are held by each window representing
|
|
|
10083 the current display and the desired display.
|
|
|
10084
|
|
442
|
10085 The @code{display_line} structures are tightly tied to buffers which
|
|
428
|
10086 presents a problem for redisplay as this connection is bogus for the
|
|
|
10087 modeline. Hence the @code{display_line} generation routines are
|
|
|
10088 duplicated for generating the modeline. This means that the modeline
|
|
|
10089 display code has many bugs that the standard redisplay code does not.
|
|
|
10090
|
|
|
10091 The guts of @code{display_line} generation are in
|
|
|
10092 @code{create_text_block}, which creates a single display line for the
|
|
|
10093 desired locale. This incrementally parses the characters on the current
|
|
442
|
10094 line and generates redisplay structures for each.
|
|
428
|
10095
|
|
|
10096 Gutter redisplay is different. Because the data to display is stored in
|
|
|
10097 a string we cannot use @code{create_text_block}. Instead we use
|
|
|
10098 @code{create_text_string_block} which performs the same function as
|
|
|
10099 @code{create_text_block} but for strings. Many of the complexities of
|
|
|
10100 @code{create_text_block} to do with cursor handling and selective
|
|
|
10101 display have been removed.
|
|
|
10102
|
|
|
10103 @node Extents, Faces, The Redisplay Mechanism, Top
|
|
|
10104 @chapter Extents
|
|
462
|
10105 @cindex extents
|
|
428
|
10106
|
|
|
10107 @menu
|
|
|
10108 * Introduction to Extents:: Extents are ranges over text, with properties.
|
|
|
10109 * Extent Ordering:: How extents are ordered internally.
|
|
|
10110 * Format of the Extent Info:: The extent information in a buffer or string.
|
|
|
10111 * Zero-Length Extents:: A weird special case.
|
|
442
|
10112 * Mathematics of Extent Ordering:: A rigorous foundation.
|
|
428
|
10113 * Extent Fragments:: Cached information useful for redisplay.
|
|
|
10114 @end menu
|
|
|
10115
|
|
462
|
10116 @node Introduction to Extents
|
|
428
|
10117 @section Introduction to Extents
|
|
462
|
10118 @cindex extents, introduction to
|
|
428
|
10119
|
|
|
10120 Extents are regions over a buffer, with a start and an end position
|
|
|
10121 denoting the region of the buffer included in the extent. In
|
|
|
10122 addition, either end can be closed or open, meaning that the endpoint
|
|
|
10123 is or is not logically included in the extent. Insertion of a character
|
|
|
10124 at a closed endpoint causes the character to go inside the extent;
|
|
|
10125 insertion at an open endpoint causes the character to go outside.
|
|
|
10126
|
|
|
10127 Extent endpoints are stored using memory indices (see @file{insdel.c}),
|
|
|
10128 to minimize the amount of adjusting that needs to be done when
|
|
|
10129 characters are inserted or deleted.
|
|
|
10130
|
|
|
10131 (Formerly, extent endpoints at the gap could be either before or
|
|
|
10132 after the gap, depending on the open/closedness of the endpoint.
|
|
|
10133 The intent of this was to make it so that insertions would
|
|
|
10134 automatically go inside or out of extents as necessary with no
|
|
|
10135 further work needing to be done. It didn't work out that way,
|
|
|
10136 however, and just ended up complexifying and buggifying all the
|
|
|
10137 rest of the code.)
|
|
|
10138
|
|
462
|
10139 @node Extent Ordering
|
|
428
|
10140 @section Extent Ordering
|
|
462
|
10141 @cindex extent ordering
|
|
428
|
10142
|
|
|
10143 Extents are compared using memory indices. There are two orderings
|
|
|
10144 for extents and both orders are kept current at all times. The normal
|
|
|
10145 or @dfn{display} order is as follows:
|
|
|
10146
|
|
|
10147 @example
|
|
|
10148 Extent A is ``less than'' extent B,
|
|
|
10149 that is, earlier in the display order,
|
|
|
10150 if: A-start < B-start,
|
|
|
10151 or if: A-start = B-start, and A-end > B-end
|
|
|
10152 @end example
|
|
|
10153
|
|
|
10154 So if two extents begin at the same position, the larger of them is the
|
|
|
10155 earlier one in the display order (@code{EXTENT_LESS} is true).
|
|
|
10156
|
|
|
10157 For the e-order, the same thing holds:
|
|
|
10158
|
|
|
10159 @example
|
|
|
10160 Extent A is ``less than'' extent B in e-order,
|
|
|
10161 that is, later in the buffer,
|
|
|
10162 if: A-end < B-end,
|
|
|
10163 or if: A-end = B-end, and A-start > B-start
|
|
|
10164 @end example
|
|
|
10165
|
|
|
10166 So if two extents end at the same position, the smaller of them is the
|
|
|
10167 earlier one in the e-order (@code{EXTENT_E_LESS} is true).
|
|
|
10168
|
|
|
10169 The display order and the e-order are complementary orders: any
|
|
|
10170 theorem about the display order also applies to the e-order if you swap
|
|
|
10171 all occurrences of ``display order'' and ``e-order'', ``less than'' and
|
|
|
10172 ``greater than'', and ``extent start'' and ``extent end''.
|
|
|
10173
|
|
462
|
10174 @node Format of the Extent Info
|
|
428
|
10175 @section Format of the Extent Info
|
|
462
|
10176 @cindex extent info, format of the
|
|
428
|
10177
|
|
|
10178 An extent-info structure consists of a list of the buffer or string's
|
|
|
10179 extents and a @dfn{stack of extents} that lists all of the extents over
|
|
|
10180 a particular position. The stack-of-extents info is used for
|
|
440
|
10181 optimization purposes---it basically caches some info that might
|
|
428
|
10182 be expensive to compute. Certain otherwise hard computations are easy
|
|
|
10183 given the stack of extents over a particular position, and if the
|
|
|
10184 stack of extents over a nearby position is known (because it was
|
|
|
10185 calculated at some prior point in time), it's easy to move the stack
|
|
|
10186 of extents to the proper position.
|
|
|
10187
|
|
|
10188 Given that the stack of extents is an optimization, and given that
|
|
|
10189 it requires memory, a string's stack of extents is wiped out each
|
|
|
10190 time a garbage collection occurs. Therefore, any time you retrieve
|
|
|
10191 the stack of extents, it might not be there. If you need it to
|
|
|
10192 be there, use the @code{_force} version.
|
|
|
10193
|
|
|
10194 Similarly, a string may or may not have an extent_info structure.
|
|
|
10195 (Generally it won't if there haven't been any extents added to the
|
|
|
10196 string.) So use the @code{_force} version if you need the extent_info
|
|
|
10197 structure to be there.
|
|
|
10198
|
|
1263
|
10199 A list of extents is maintained as a double gap array. One gap array
|
|
428
|
10200 is ordered by start index (the @dfn{display order}) and the other is
|
|
|
10201 ordered by end index (the @dfn{e-order}). Note that positions in an
|
|
|
10202 extent list should logically be conceived of as referring @emph{to} a
|
|
|
10203 particular extent (as is the norm in programs) rather than sitting
|
|
|
10204 between two extents. Note also that callers of these functions should
|
|
|
10205 not be aware of the fact that the extent list is implemented as an
|
|
|
10206 array, except for the fact that positions are integers (this should be
|
|
|
10207 generalized to handle integers and linked list equally well).
|
|
|
10208
|
|
1261
|
10209 A gap array is the same structure used by buffer text: an array of
|
|
|
10210 elements with a "gap" somewhere in the middle. Insertion and deletion
|
|
|
10211 happens by moving the gap to the insertion/deletion point, and then
|
|
|
10212 expanding/contracting as necessary. Gap arrays have a number of
|
|
|
10213 useful properties:
|
|
|
10214
|
|
|
10215 @enumerate
|
|
|
10216 @item
|
|
|
10217 They are space efficient, as there is no need for next/previous pointers.
|
|
|
10218
|
|
|
10219 @item
|
|
|
10220 If the items in them are sorted, locating an item is fast -- @math{O(log N)}.
|
|
|
10221
|
|
|
10222 @item
|
|
|
10223 Insertion and deletion is very fast (constant time, essentially) if the
|
|
|
10224 gap is near (which favors localized operations, as will usually be the
|
|
|
10225 case). Even if not, it requires only a block move of memory, which is
|
|
|
10226 generally a highly optimized operation on modern processors.
|
|
|
10227
|
|
|
10228 @item
|
|
|
10229 Code to manipulate them is relatively simple to write.
|
|
|
10230 @end enumerate
|
|
|
10231
|
|
1263
|
10232 An alternative would be balanced binary trees, which have guaranteed
|
|
1261
|
10233 @math{O(log N)} time for all operations (although the constant factors
|
|
|
10234 are not as good, and repeated localized operations will be slower than
|
|
|
10235 for a gap array). Such code is quite tricky to write, however.
|
|
|
10236
|
|
462
|
10237 @node Zero-Length Extents
|
|
428
|
10238 @section Zero-Length Extents
|
|
462
|
10239 @cindex zero-length extents
|
|
|
10240 @cindex extents, zero-length
|
|
428
|
10241
|
|
|
10242 Extents can be zero-length, and will end up that way if their endpoints
|
|
444
|
10243 are explicitly set that way or if their detachable property is @code{nil}
|
|
428
|
10244 and all the text in the extent is deleted. (The exception is open-open
|
|
|
10245 zero-length extents, which are barred from existing because there is
|
|
|
10246 no sensible way to define their properties. Deletion of the text in
|
|
|
10247 an open-open extent causes it to be converted into a closed-open
|
|
|
10248 extent.) Zero-length extents are primarily used to represent
|
|
|
10249 annotations, and behave as follows:
|
|
|
10250
|
|
|
10251 @enumerate
|
|
|
10252 @item
|
|
|
10253 Insertion at the position of a zero-length extent expands the extent
|
|
|
10254 if both endpoints are closed; goes after the extent if it is closed-open;
|
|
|
10255 and goes before the extent if it is open-closed.
|
|
|
10256
|
|
|
10257 @item
|
|
|
10258 Deletion of a character on a side of a zero-length extent whose
|
|
|
10259 corresponding endpoint is closed causes the extent to be detached if
|
|
|
10260 it is detachable; if the extent is not detachable or the corresponding
|
|
|
10261 endpoint is open, the extent remains in the buffer, moving as necessary.
|
|
|
10262 @end enumerate
|
|
|
10263
|
|
|
10264 Note that closed-open, non-detachable zero-length extents behave
|
|
|
10265 exactly like markers and that open-closed, non-detachable zero-length
|
|
|
10266 extents behave like the ``point-type'' marker in Mule.
|
|
|
10267
|
|
462
|
10268 @node Mathematics of Extent Ordering
|
|
428
|
10269 @section Mathematics of Extent Ordering
|
|
462
|
10270 @cindex mathematics of extent ordering
|
|
428
|
10271 @cindex extent mathematics
|
|
|
10272 @cindex extent ordering
|
|
|
10273
|
|
|
10274 @cindex display order of extents
|
|
|
10275 @cindex extents, display order
|
|
|
10276 The extents in a buffer are ordered by ``display order'' because that
|
|
|
10277 is that order that the redisplay mechanism needs to process them in.
|
|
|
10278 The e-order is an auxiliary ordering used to facilitate operations
|
|
|
10279 over extents. The operations that can be performed on the ordered
|
|
|
10280 list of extents in a buffer are
|
|
|
10281
|
|
|
10282 @enumerate
|
|
|
10283 @item
|
|
|
10284 Locate where an extent would go if inserted into the list.
|
|
|
10285 @item
|
|
|
10286 Insert an extent into the list.
|
|
|
10287 @item
|
|
|
10288 Remove an extent from the list.
|
|
|
10289 @item
|
|
|
10290 Map over all the extents that overlap a range.
|
|
|
10291 @end enumerate
|
|
|
10292
|
|
|
10293 (4) requires being able to determine the first and last extents
|
|
|
10294 that overlap a range.
|
|
|
10295
|
|
|
10296 NOTE: @dfn{overlap} is used as follows:
|
|
|
10297
|
|
|
10298 @itemize @bullet
|
|
|
10299 @item
|
|
|
10300 two ranges overlap if they have at least one point in common.
|
|
|
10301 Whether the endpoints are open or closed makes a difference here.
|
|
|
10302 @item
|
|
|
10303 a point overlaps a range if the point is contained within the
|
|
|
10304 range; this is equivalent to treating a point @math{P} as the range
|
|
|
10305 @math{[P, P]}.
|
|
|
10306 @item
|
|
|
10307 In the case of an @emph{extent} overlapping a point or range, the extent
|
|
|
10308 is normally treated as having closed endpoints. This applies
|
|
|
10309 consistently in the discussion of stacks of extents and such below.
|
|
|
10310 Note that this definition of overlap is not necessarily consistent with
|
|
|
10311 the extents that @code{map-extents} maps over, since @code{map-extents}
|
|
|
10312 sometimes pays attention to whether the endpoints of an extents are open
|
|
|
10313 or closed. But for our purposes, it greatly simplifies things to treat
|
|
|
10314 all extents as having closed endpoints.
|
|
|
10315 @end itemize
|
|
|
10316
|
|
|
10317 First, define @math{>}, @math{<}, @math{<=}, etc. as applied to extents
|
|
|
10318 to mean comparison according to the display order. Comparison between
|
|
|
10319 an extent @math{E} and an index @math{I} means comparison between
|
|
|
10320 @math{E} and the range @math{[I, I]}.
|
|
|
10321
|
|
|
10322 Also define @math{e>}, @math{e<}, @math{e<=}, etc. to mean comparison
|
|
|
10323 according to the e-order.
|
|
|
10324
|
|
|
10325 For any range @math{R}, define @math{R(0)} to be the starting index of
|
|
|
10326 the range and @math{R(1)} to be the ending index of the range.
|
|
|
10327
|
|
|
10328 For any extent @math{E}, define @math{E(next)} to be the extent directly
|
|
|
10329 following @math{E}, and @math{E(prev)} to be the extent directly
|
|
|
10330 preceding @math{E}. Assume @math{E(next)} and @math{E(prev)} can be
|
|
|
10331 determined from @math{E} in constant time. (This is because we store
|
|
|
10332 the extent list as a doubly linked list.)
|
|
|
10333
|
|
|
10334 Similarly, define @math{E(e-next)} and @math{E(e-prev)} to be the
|
|
|
10335 extents directly following and preceding @math{E} in the e-order.
|
|
|
10336
|
|
|
10337 Now:
|
|
|
10338
|
|
|
10339 Let @math{R} be a range.
|
|
|
10340 Let @math{F} be the first extent overlapping @math{R}.
|
|
|
10341 Let @math{L} be the last extent overlapping @math{R}.
|
|
|
10342
|
|
|
10343 Theorem 1: @math{R(1)} lies between @math{L} and @math{L(next)},
|
|
|
10344 i.e. @math{L <= R(1) < L(next)}.
|
|
|
10345
|
|
|
10346 This follows easily from the definition of display order. The
|
|
|
10347 basic reason that this theorem applies is that the display order
|
|
|
10348 sorts by increasing starting index.
|
|
|
10349
|
|
|
10350 Therefore, we can determine @math{L} just by looking at where we would
|
|
|
10351 insert @math{R(1)} into the list, and if we know @math{F} and are moving
|
|
|
10352 forward over extents, we can easily determine when we've hit @math{L} by
|
|
|
10353 comparing the extent we're at to @math{R(1)}.
|
|
|
10354
|
|
|
10355 @example
|
|
|
10356 Theorem 2: @math{F(e-prev) e< [1, R(0)] e<= F}.
|
|
|
10357 @end example
|
|
|
10358
|
|
|
10359 This is the analog of Theorem 1, and applies because the e-order
|
|
|
10360 sorts by increasing ending index.
|
|
|
10361
|
|
|
10362 Therefore, @math{F} can be found in the same amount of time as
|
|
|
10363 operation (1), i.e. the time that it takes to locate where an extent
|
|
1261
|
10364 would go if inserted into the e-order list. This is @math{O(log N)},
|
|
|
10365 since we are using gap arrays to manage extents.
|
|
428
|
10366
|
|
|
10367 Define a @dfn{stack of extents} (or @dfn{SOE}) as the set of extents
|
|
1261
|
10368 (ordered in display order and e-order, just like for normal extent
|
|
|
10369 lists) that overlap an index @math{I}.
|
|
428
|
10370
|
|
|
10371 Now:
|
|
|
10372
|
|
|
10373 Let @math{I} be an index, let @math{S} be the stack of extents on
|
|
1261
|
10374 @math{I} and let @math{F} be the first extent in @math{S}.
|
|
428
|
10375
|
|
|
10376 Theorem 3: The first extent in @math{S} is the first extent that overlaps
|
|
|
10377 any range @math{[I, J]}.
|
|
|
10378
|
|
|
10379 Proof: Any extent that overlaps @math{[I, J]} but does not include
|
|
|
10380 @math{I} must have a start index @math{> I}, and thus be greater than
|
|
|
10381 any extent in @math{S}.
|
|
|
10382
|
|
|
10383 Therefore, finding the first extent that overlaps a range @math{R} is
|
|
|
10384 the same as finding the first extent that overlaps @math{R(0)}.
|
|
|
10385
|
|
|
10386 Theorem 4: Let @math{I2} be an index such that @math{I2 > I}, and let
|
|
|
10387 @math{F2} be the first extent that overlaps @math{I2}. Then, either
|
|
|
10388 @math{F2} is in @math{S} or @math{F2} is greater than any extent in
|
|
|
10389 @math{S}.
|
|
|
10390
|
|
|
10391 Proof: If @math{F2} does not include @math{I} then its start index is
|
|
|
10392 greater than @math{I} and thus it is greater than any extent in
|
|
|
10393 @math{S}, including @math{F}. Otherwise, @math{F2} includes @math{I}
|
|
|
10394 and thus is in @math{S}, and thus @math{F2 >= F}.
|
|
|
10395
|
|
462
|
10396 @node Extent Fragments
|
|
428
|
10397 @section Extent Fragments
|
|
462
|
10398 @cindex extent fragments
|
|
|
10399 @cindex fragments, extent
|
|
428
|
10400
|
|
|
10401 Imagine that the buffer is divided up into contiguous, non-overlapping
|
|
|
10402 @dfn{runs} of text such that no extent starts or ends within a run
|
|
|
10403 (extents that abut the run don't count).
|
|
|
10404
|
|
|
10405 An extent fragment is a structure that holds data about the run that
|
|
|
10406 contains a particular buffer position (if the buffer position is at the
|
|
440
|
10407 junction of two runs, the run after the position is used)---the
|
|
428
|
10408 beginning and end of the run, a list of all of the extents in that run,
|
|
|
10409 the @dfn{merged face} that results from merging all of the faces
|
|
|
10410 corresponding to those extents, the begin and end glyphs at the
|
|
|
10411 beginning of the run, etc. This is the information that redisplay needs
|
|
|
10412 in order to display this run.
|
|
|
10413
|
|
|
10414 Extent fragments have to be very quick to update to a new buffer
|
|
|
10415 position when moving linearly through the buffer. They rely on the
|
|
|
10416 stack-of-extents code, which does the heavy-duty algorithmic work of
|
|
|
10417 determining which extents overly a particular position.
|
|
|
10418
|
|
|
10419 @node Faces, Glyphs, Extents, Top
|
|
|
10420 @chapter Faces
|
|
462
|
10421 @cindex faces
|
|
428
|
10422
|
|
|
10423 Not yet documented.
|
|
|
10424
|
|
|
10425 @node Glyphs, Specifiers, Faces, Top
|
|
|
10426 @chapter Glyphs
|
|
462
|
10427 @cindex glyphs
|
|
428
|
10428
|
|
|
10429 Glyphs are graphical elements that can be displayed in XEmacs buffers or
|
|
|
10430 gutters. We use the term graphical element here in the broadest possible
|
|
446
|
10431 sense since glyphs can be as mundane as text or as arcane as a native
|
|
428
|
10432 tab widget.
|
|
|
10433
|
|
|
10434 In XEmacs, glyphs represent the uninstantiated state of graphical
|
|
|
10435 elements, i.e. they hold all the information necessary to produce an
|
|
446
|
10436 image on-screen but the image need not exist at this stage, and multiple
|
|
|
10437 screen images can be instantiated from a single glyph.
|
|
428
|
10438
|
|
|
10439 Glyphs are lazily instantiated by calling one of the glyph
|
|
|
10440 functions. This usually occurs within redisplay when
|
|
|
10441 @code{Fglyph_height} is called. Instantiation causes an image-instance
|
|
454
|
10442 to be created and cached. This cache is on a per-device basis for all glyphs
|
|
|
10443 except widget-glyphs, and on a per-window basis for widgets-glyphs. The
|
|
428
|
10444 caching is done by @code{image_instantiate} and is necessary because it
|
|
|
10445 is generally possible to display an image-instance in multiple
|
|
|
10446 domains. For instance if we create a Pixmap, we can actually display
|
|
|
10447 this on multiple windows - even though we only need a single Pixmap
|
|
|
10448 instance to do this. If caching wasn't done then it would be necessary
|
|
442
|
10449 to create image-instances for every displayable occurrence of a glyph -
|
|
428
|
10450 and every usage - and this would be extremely memory and cpu intensive.
|
|
|
10451
|
|
|
10452 Widget-glyphs (a.k.a native widgets) are not cached in this way. This is
|
|
|
10453 because widget-glyph image-instances on screen are toolkit windows, and
|
|
|
10454 thus cannot be reused in multiple XEmacs domains. Thus widget-glyphs are
|
|
446
|
10455 cached on an XEmacs window basis.
|
|
428
|
10456
|
|
|
10457 Any action on a glyph first consults the cache before actually
|
|
|
10458 instantiating a widget.
|
|
|
10459
|
|
454
|
10460 @section Glyph Instantiation
|
|
462
|
10461 @cindex glyph instantiation
|
|
|
10462 @cindex instantiation, glyph
|
|
454
|
10463
|
|
|
10464 Glyph instantiation is a hairy topic and requires some explanation. The
|
|
|
10465 guts of glyph instantiation is contained within
|
|
|
10466 @code{image_instantiate}. A glyph contains an image which is a
|
|
|
10467 specifier. When a glyph function - for instance @code{Fglyph_height} -
|
|
|
10468 asks for a property of the glyph that can only be determined from its
|
|
|
10469 instantiated state, then the glyph image is instantiated and an image
|
|
|
10470 instance created. The instantiation process is governed by the specifier
|
|
|
10471 code and goes through a series of steps:
|
|
|
10472
|
|
|
10473 @itemize @bullet
|
|
|
10474 @item
|
|
|
10475 Validation. Instantiation of image instances happens dynamically - often
|
|
|
10476 within the guts of redisplay. Thus it is often not feasible to catch
|
|
|
10477 instantiator errors at instantiation time. Instead the instantiator is
|
|
|
10478 validated at the time it is added to the image specifier. This function
|
|
|
10479 is defined by @code{image_validate} and at a simple level validates
|
|
|
10480 keyword value pairs.
|
|
|
10481 @item
|
|
|
10482 Duplication. The specifier code by default takes a copy of the
|
|
|
10483 instantiator. This is reasonable for most specifiers but in the case of
|
|
|
10484 widget-glyphs can be problematic, since some of the properties in the
|
|
|
10485 instantiator - for instance callbacks - could cause infinite recursion
|
|
|
10486 in the copying process. Thus the image code defines a function -
|
|
|
10487 @code{image_copy_instantiator} - which will selectively copy values.
|
|
|
10488 This is controlled by the way that a keyword is defined either using
|
|
|
10489 @code{IIFORMAT_VALID_KEYWORD} or
|
|
|
10490 @code{IIFORMAT_VALID_NONCOPY_KEYWORD}. Note that the image caching and
|
|
|
10491 redisplay code relies on instantiator copying to ensure that current and
|
|
|
10492 new instantiators are actually different rather than referring to the
|
|
|
10493 same thing.
|
|
|
10494 @item
|
|
|
10495 Normalization. Once the instantiator has been copied it must be
|
|
|
10496 converted into a form that is viable at instantiation time. This can
|
|
|
10497 involve no changes at all, but typically involves things like converting
|
|
|
10498 file names to the actual data. This function is defined by
|
|
|
10499 @code{image_going_to_add} and @code{normalize_image_instantiator}.
|
|
|
10500 @item
|
|
|
10501 Instantiation. When an image instance is actually required for display
|
|
|
10502 it is instantiated using @code{image_instantiate}. This involves calling
|
|
|
10503 instantiate methods that are specific to the type of image being
|
|
|
10504 instantiated.
|
|
|
10505 @end itemize
|
|
|
10506
|
|
|
10507 The final instantiation phase also involves a number of steps. In order
|
|
|
10508 to understand these we need to describe a number of concepts.
|
|
|
10509
|
|
|
10510 An image is instantiated in a @dfn{domain}, where a domain can be any
|
|
|
10511 one of a device, frame, window or image-instance. The domain gives the
|
|
|
10512 image-instance context and identity and properties that affect the
|
|
|
10513 appearance of the image-instance may be different for the same glyph
|
|
|
10514 instantiated in different domains. An example is the face used to
|
|
|
10515 display the image-instance.
|
|
|
10516
|
|
|
10517 Although an image is instantiated in a particular domain the
|
|
|
10518 instantiation domain is not necessarily the domain in which the
|
|
|
10519 image-instance is cached. For example a pixmap can be instantiated in a
|
|
|
10520 window be actually be cached on a per-device basis. The domain in which
|
|
|
10521 the image-instance is actually cached is called the
|
|
|
10522 @dfn{governing-domain}. A governing-domain is currently either a device
|
|
|
10523 or a window. Widget-glyphs and text-glyphs have a window as a
|
|
|
10524 governing-domain, all other image-instances have a device as the
|
|
|
10525 governing-domain. The governing domain for an image-instance is
|
|
|
10526 determined using the governing_domain image-instance method.
|
|
|
10527
|
|
|
10528 @section Widget-Glyphs
|
|
462
|
10529 @cindex widget-glyphs
|
|
454
|
10530
|
|
440
|
10531 @section Widget-Glyphs in the MS-Windows Environment
|
|
462
|
10532 @cindex widget-glyphs in the MS-Windows environment
|
|
|
10533 @cindex MS-Windows environment, widget-glyphs in the
|
|
428
|
10534
|
|
|
10535 To Do
|
|
|
10536
|
|
|
10537 @section Widget-Glyphs in the X Environment
|
|
462
|
10538 @cindex widget-glyphs in the X environment
|
|
|
10539 @cindex X environment, widget-glyphs in the
|
|
428
|
10540
|
|
446
|
10541 Widget-glyphs under X make heavy use of lwlib (@pxref{Lucid Widget
|
|
|
10542 Library}) for manipulating the native toolkit objects. This is primarily
|
|
|
10543 so that different toolkits can be supported for widget-glyphs, just as
|
|
|
10544 they are supported for features such as menubars etc.
|
|
428
|
10545
|
|
454
|
10546 Lwlib is extremely poorly documented and quite hairy so here is my
|
|
|
10547 understanding of what goes on.
|
|
|
10548
|
|
|
10549 Lwlib maintains a set of widget_instances which mirror the hierarchical
|
|
|
10550 state of Xt widgets. I think this is so that widgets can be updated and
|
|
|
10551 manipulated generically by the lwlib library. For instance
|
|
|
10552 update_one_widget_instance can cope with multiple types of widget and
|
|
|
10553 multiple types of toolkit. Each element in the widget hierarchy is updated
|
|
|
10554 from its corresponding widget_instance by walking the widget_instance
|
|
|
10555 tree recursively.
|
|
|
10556
|
|
|
10557 This has desirable properties such as lw_modify_all_widgets which is
|
|
|
10558 called from @file{glyphs-x.c} and updates all the properties of a widget
|
|
|
10559 without having to know what the widget is or what toolkit it is from.
|
|
|
10560 Unfortunately this also has hairy properties such as making the lwlib
|
|
|
10561 code quite complex. And of course lwlib has to know at some level what
|
|
|
10562 the widget is and how to set its properties.
|
|
|
10563
|
|
428
|
10564 @node Specifiers, Menus, Glyphs, Top
|
|
|
10565 @chapter Specifiers
|
|
462
|
10566 @cindex specifiers
|
|
428
|
10567
|
|
|
10568 Not yet documented.
|
|
|
10569
|
|
|
10570 @node Menus, Subprocesses, Specifiers, Top
|
|
|
10571 @chapter Menus
|
|
462
|
10572 @cindex menus
|
|
428
|
10573
|
|
|
10574 A menu is set by setting the value of the variable
|
|
|
10575 @code{current-menubar} (which may be buffer-local) and then calling
|
|
|
10576 @code{set-menubar-dirty-flag} to signal a change. This will cause the
|
|
|
10577 menu to be redrawn at the next redisplay. The format of the data in
|
|
|
10578 @code{current-menubar} is described in @file{menubar.c}.
|
|
|
10579
|
|
|
10580 Internally the data in current-menubar is parsed into a tree of
|
|
|
10581 @code{widget_value's} (defined in @file{lwlib.h}); this is accomplished
|
|
|
10582 by the recursive function @code{menu_item_descriptor_to_widget_value()},
|
|
|
10583 called by @code{compute_menubar_data()}. Such a tree is deallocated
|
|
|
10584 using @code{free_widget_value()}.
|
|
|
10585
|
|
|
10586 @code{update_screen_menubars()} is one of the external entry points.
|
|
|
10587 This checks to see, for each screen, if that screen's menubar needs to
|
|
|
10588 be updated. This is the case if
|
|
|
10589
|
|
|
10590 @enumerate
|
|
|
10591 @item
|
|
|
10592 @code{set-menubar-dirty-flag} was called since the last redisplay. (This
|
|
|
10593 function sets the C variable menubar_has_changed.)
|
|
|
10594 @item
|
|
|
10595 The buffer displayed in the screen has changed.
|
|
|
10596 @item
|
|
|
10597 The screen has no menubar currently displayed.
|
|
|
10598 @end enumerate
|
|
|
10599
|
|
|
10600 @code{set_screen_menubar()} is called for each such screen. This
|
|
|
10601 function calls @code{compute_menubar_data()} to create the tree of
|
|
|
10602 widget_value's, then calls @code{lw_create_widget()},
|
|
|
10603 @code{lw_modify_all_widgets()}, and/or @code{lw_destroy_all_widgets()}
|
|
|
10604 to create the X-Toolkit widget associated with the menu.
|
|
|
10605
|
|
|
10606 @code{update_psheets()}, the other external entry point, actually
|
|
|
10607 changes the menus being displayed. It uses the widgets fixed by
|
|
|
10608 @code{update_screen_menubars()} and calls various X functions to ensure
|
|
|
10609 that the menus are displayed properly.
|
|
|
10610
|
|
|
10611 The menubar widget is set up so that @code{pre_activate_callback()} is
|
|
|
10612 called when the menu is first selected (i.e. mouse button goes down),
|
|
|
10613 and @code{menubar_selection_callback()} is called when an item is
|
|
|
10614 selected. @code{pre_activate_callback()} calls the function in
|
|
|
10615 activate-menubar-hook, which can change the menubar (this is described
|
|
|
10616 in @file{menubar.c}). If the menubar is changed,
|
|
|
10617 @code{set_screen_menubars()} is called.
|
|
|
10618 @code{menubar_selection_callback()} enqueues a menu event, putting in it
|
|
|
10619 a function to call (either @code{eval} or @code{call-interactively}) and
|
|
|
10620 its argument, which is the callback function or form given in the menu's
|
|
|
10621 description.
|
|
|
10622
|
|
446
|
10623 @node Subprocesses, Interface to the X Window System, Menus, Top
|
|
428
|
10624 @chapter Subprocesses
|
|
462
|
10625 @cindex subprocesses
|
|
428
|
10626
|
|
|
10627 The fields of a process are:
|
|
|
10628
|
|
|
10629 @table @code
|
|
|
10630 @item name
|
|
|
10631 A string, the name of the process.
|
|
|
10632
|
|
|
10633 @item command
|
|
|
10634 A list containing the command arguments that were used to start this
|
|
|
10635 process.
|
|
|
10636
|
|
|
10637 @item filter
|
|
|
10638 A function used to accept output from the process instead of a buffer,
|
|
|
10639 or @code{nil}.
|
|
|
10640
|
|
|
10641 @item sentinel
|
|
|
10642 A function called whenever the process receives a signal, or @code{nil}.
|
|
|
10643
|
|
|
10644 @item buffer
|
|
|
10645 The associated buffer of the process.
|
|
|
10646
|
|
|
10647 @item pid
|
|
|
10648 An integer, the Unix process @sc{id}.
|
|
|
10649
|
|
|
10650 @item childp
|
|
|
10651 A flag, non-@code{nil} if this is really a child process.
|
|
|
10652 It is @code{nil} for a network connection.
|
|
|
10653
|
|
|
10654 @item mark
|
|
|
10655 A marker indicating the position of the end of the last output from this
|
|
|
10656 process inserted into the buffer. This is often but not always the end
|
|
|
10657 of the buffer.
|
|
|
10658
|
|
|
10659 @item kill_without_query
|
|
|
10660 If this is non-@code{nil}, killing XEmacs while this process is still
|
|
|
10661 running does not ask for confirmation about killing the process.
|
|
|
10662
|
|
|
10663 @item raw_status_low
|
|
|
10664 @itemx raw_status_high
|
|
|
10665 These two fields record 16 bits each of the process status returned by
|
|
|
10666 the @code{wait} system call.
|
|
|
10667
|
|
|
10668 @item status
|
|
|
10669 The process status, as @code{process-status} should return it.
|
|
|
10670
|
|
|
10671 @item tick
|
|
|
10672 @itemx update_tick
|
|
|
10673 If these two fields are not equal, a change in the status of the process
|
|
|
10674 needs to be reported, either by running the sentinel or by inserting a
|
|
|
10675 message in the process buffer.
|
|
|
10676
|
|
|
10677 @item pty_flag
|
|
|
10678 Non-@code{nil} if communication with the subprocess uses a @sc{pty};
|
|
|
10679 @code{nil} if it uses a pipe.
|
|
|
10680
|
|
|
10681 @item infd
|
|
|
10682 The file descriptor for input from the process.
|
|
|
10683
|
|
|
10684 @item outfd
|
|
|
10685 The file descriptor for output to the process.
|
|
|
10686
|
|
|
10687 @item subtty
|
|
|
10688 The file descriptor for the terminal that the subprocess is using. (On
|
|
|
10689 some systems, there is no need to record this, so the value is
|
|
|
10690 @code{-1}.)
|
|
|
10691
|
|
|
10692 @item tty_name
|
|
|
10693 The name of the terminal that the subprocess is using,
|
|
|
10694 or @code{nil} if it is using pipes.
|
|
|
10695 @end table
|
|
|
10696
|
|
446
|
10697 @node Interface to the X Window System, Index, Subprocesses, Top
|
|
|
10698 @chapter Interface to the X Window System
|
|
462
|
10699 @cindex X Window System, interface to the
|
|
446
|
10700
|
|
|
10701 Mostly undocumented.
|
|
|
10702
|
|
|
10703 @menu
|
|
|
10704 * Lucid Widget Library:: An interface to various widget sets.
|
|
|
10705 @end menu
|
|
|
10706
|
|
462
|
10707 @node Lucid Widget Library
|
|
446
|
10708 @section Lucid Widget Library
|
|
462
|
10709 @cindex Lucid Widget Library
|
|
|
10710 @cindex widget library, Lucid
|
|
|
10711 @cindex library, Lucid Widget
|
|
446
|
10712
|
|
|
10713 Lwlib is extremely poorly documented and quite hairy. The author(s)
|
|
|
10714 blame that on X, Xt, and Motif, with some justice, but also sufficient
|
|
|
10715 hypocrisy to avoid drawing the obvious conclusion about their own work.
|
|
|
10716
|
|
|
10717 The Lucid Widget Library is composed of two more or less independent
|
|
|
10718 pieces. The first, as the name suggests, is a set of widgets. These
|
|
|
10719 widgets are intended to resemble and improve on widgets provided in the
|
|
|
10720 Motif toolkit but not in the Athena widgets, including menubars and
|
|
|
10721 scrollbars. Recent additions by Andy Piper integrate some ``modern''
|
|
|
10722 widgets by Edward Falk, including checkboxes, radio buttons, progress
|
|
|
10723 gauges, and index tab controls (aka notebooks).
|
|
|
10724
|
|
|
10725 The second piece of the Lucid widget library is a generic interface to
|
|
|
10726 several toolkits for X (including Xt, the Athena widget set, and Motif,
|
|
|
10727 as well as the Lucid widgets themselves) so that core XEmacs code need
|
|
|
10728 not know which widget set has been used to build the graphical user
|
|
|
10729 interface.
|
|
|
10730
|
|
|
10731 @menu
|
|
|
10732 * Generic Widget Interface:: The lwlib generic widget interface.
|
|
|
10733 * Scrollbars::
|
|
|
10734 * Menubars::
|
|
|
10735 * Checkboxes and Radio Buttons::
|
|
|
10736 * Progress Bars::
|
|
|
10737 * Tab Controls::
|
|
|
10738 @end menu
|
|
|
10739
|
|
462
|
10740 @node Generic Widget Interface
|
|
446
|
10741 @subsection Generic Widget Interface
|
|
462
|
10742 @cindex widget interface, generic
|
|
446
|
10743
|
|
|
10744 In general in any toolkit a widget may be a composite object. In Xt,
|
|
|
10745 all widgets have an X window that they manage, but typically a complex
|
|
|
10746 widget will have widget children, each of which manages a subwindow of
|
|
|
10747 the parent widget's X window. These children may themselves be
|
|
|
10748 composite widgets. Thus a widget is actually a tree or hierarchy of
|
|
|
10749 widgets.
|
|
|
10750
|
|
|
10751 For each toolkit widget, lwlib maintains a tree of @code{widget_values}
|
|
|
10752 which mirror the hierarchical state of Xt widgets (including Motif,
|
|
|
10753 Athena, 3D Athena, and Falk's widget sets). Each @code{widget_value}
|
|
|
10754 has @code{contents} member, which points to the head of a linked list of
|
|
|
10755 its children. The linked list of siblings is chained through the
|
|
|
10756 @code{next} member of @code{widget_value}.
|
|
|
10757
|
|
|
10758 @example
|
|
|
10759 +-----------+
|
|
|
10760 | composite |
|
|
|
10761 +-----------+
|
|
|
10762 |
|
|
|
10763 | contents
|
|
|
10764 V
|
|
|
10765 +-------+ next +-------+ next +-------+
|
|
|
10766 | child |----->| child |----->| child |
|
|
|
10767 +-------+ +-------+ +-------+
|
|
|
10768 |
|
|
|
10769 | contents
|
|
|
10770 V
|
|
|
10771 +-------------+ next +-------------+
|
|
|
10772 | grand child |----->| grand child |
|
|
|
10773 +-------------+ +-------------+
|
|
|
10774
|
|
|
10775 The @code{widget_value} hierarchy of a composite widget with two simple
|
|
|
10776 children and one composite child.
|
|
|
10777 @end example
|
|
|
10778
|
|
|
10779 The @code{widget_instance} structure maintains the inverse view of the
|
|
|
10780 tree. As for the @code{widget_value}, siblings are chained through the
|
|
|
10781 @code{next} member. However, rather than naming children, the
|
|
|
10782 @code{widget_instance} tree links to parents.
|
|
|
10783
|
|
|
10784 @example
|
|
|
10785 +-----------+
|
|
|
10786 | composite |
|
|
|
10787 +-----------+
|
|
|
10788 A
|
|
|
10789 | parent
|
|
|
10790 |
|
|
|
10791 +-------+ next +-------+ next +-------+
|
|
|
10792 | child |----->| child |----->| child |
|
|
|
10793 +-------+ +-------+ +-------+
|
|
|
10794 A
|
|
|
10795 | parent
|
|
|
10796 |
|
|
|
10797 +-------------+ next +-------------+
|
|
|
10798 | grand child |----->| grand child |
|
|
|
10799 +-------------+ +-------------+
|
|
|
10800
|
|
|
10801 The @code{widget_value} hierarchy of a composite widget with two simple
|
|
|
10802 children and one composite child.
|
|
|
10803 @end example
|
|
|
10804
|
|
|
10805 This permits widgets derived from different toolkits to be updated and
|
|
|
10806 manipulated generically by the lwlib library. For instance
|
|
|
10807 @code{update_one_widget_instance} can cope with multiple types of widget
|
|
|
10808 and multiple types of toolkit. Each element in the widget hierarchy is
|
|
|
10809 updated from its corresponding @code{widget_value} by walking the
|
|
|
10810 @code{widget_value} tree. This has desirable properties. For example,
|
|
|
10811 @code{lw_modify_all_widgets} is called from @file{glyphs-x.c} and
|
|
|
10812 updates all the properties of a widget without having to know what the
|
|
|
10813 widget is or what toolkit it is from. Unfortunately this also has its
|
|
|
10814 hairy properties; the lwlib code quite complex. And of course lwlib has
|
|
|
10815 to know at some level what the widget is and how to set its properties.
|
|
|
10816
|
|
|
10817 The @code{widget_instance} structure also contains a pointer to the root
|
|
|
10818 of its tree. Widget instances are further confi
|
|
|
10819
|
|
|
10820
|
|
462
|
10821 @node Scrollbars
|
|
446
|
10822 @subsection Scrollbars
|
|
462
|
10823 @cindex scrollbars
|
|
|
10824
|
|
|
10825 @node Menubars
|
|
446
|
10826 @subsection Menubars
|
|
462
|
10827 @cindex menubars
|
|
|
10828
|
|
|
10829 @node Checkboxes and Radio Buttons
|
|
446
|
10830 @subsection Checkboxes and Radio Buttons
|
|
462
|
10831 @cindex checkboxes and radio buttons
|
|
|
10832 @cindex radio buttons, checkboxes and
|
|
|
10833 @cindex buttons, checkboxes and radio
|
|
|
10834
|
|
|
10835 @node Progress Bars
|
|
446
|
10836 @subsection Progress Bars
|
|
462
|
10837 @cindex progress bars
|
|
|
10838 @cindex bars, progress
|
|
|
10839
|
|
|
10840 @node Tab Controls
|
|
446
|
10841 @subsection Tab Controls
|
|
462
|
10842 @cindex tab controls
|
|
428
|
10843
|
|
|
10844 @include index.texi
|
|
|
10845
|
|
|
10846 @c Print the tables of contents
|
|
|
10847 @summarycontents
|
|
|
10848 @contents
|
|
|
10849 @c That's all
|
|
|
10850
|
|
|
10851 @bye
|
