1 This is ../info/internals.info, produced by makeinfo version 4.0b from
2 internals/internals.texi.
4 INFO-DIR-SECTION XEmacs Editor
6 * Internals: (internals). XEmacs Internals Manual.
9 Copyright (C) 1992 - 1996 Ben Wing. Copyright (C) 1996, 1997 Sun
10 Microsystems. Copyright (C) 1994 - 1998 Free Software Foundation.
11 Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
13 Permission is granted to make and distribute verbatim copies of this
14 manual provided the copyright notice and this permission notice are
15 preserved on all copies.
17 Permission is granted to copy and distribute modified versions of
18 this manual under the conditions for verbatim copying, provided that the
19 entire resulting derived work is distributed under the terms of a
20 permission notice identical to this one.
22 Permission is granted to copy and distribute translations of this
23 manual into another language, under the above conditions for modified
24 versions, except that this permission notice may be stated in a
25 translation approved by the Foundation.
27 Permission is granted to copy and distribute modified versions of
28 this manual under the conditions for verbatim copying, provided also
29 that the section entitled "GNU General Public License" is included
30 exactly as in the original, and provided that the entire resulting
31 derived work is distributed under the terms of a permission notice
32 identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that the section entitled "GNU General Public License"
37 may be included in a translation approved by the Free Software
38 Foundation instead of in the original English.
41 File: internals.info, Node: Events and the Event Loop, Next: Evaluation; Stack Frames; Bindings, Prev: Dumping, Up: Top
43 Events and the Event Loop
44 *************************
48 * Introduction to Events::
50 * Specifics of the Event Gathering Mechanism::
51 * Specifics About the Emacs Event::
52 * The Event Stream Callback Routines::
53 * Other Event Loop Functions::
55 * Dispatching Events; The Command Builder::
58 File: internals.info, Node: Introduction to Events, Next: Main Loop, Prev: Events and the Event Loop, Up: Events and the Event Loop
60 Introduction to Events
61 ======================
63 An event is an object that encapsulates information about an
64 interesting occurrence in the operating system. Events are generated
65 either by user action, direct (e.g. typing on the keyboard or moving
66 the mouse) or indirect (moving another window, thereby generating an
67 expose event on an Emacs frame), or as a result of some other typically
68 asynchronous action happening, such as output from a subprocess being
69 ready or a timer expiring. Events come into the system in an
70 asynchronous fashion (typically through a callback being called) and
71 are converted into a synchronous event queue (first-in, first-out) in a
72 process that we will call "collection".
74 Note that each application has its own event queue. (It is
75 immaterial whether the collection process directly puts the events in
76 the proper application's queue, or puts them into a single system
77 queue, which is later split up.)
79 The most basic level of event collection is done by the operating
80 system or window system. Typically, XEmacs does its own event
81 collection as well. Often there are multiple layers of collection in
82 XEmacs, with events from various sources being collected into a queue,
83 which is then combined with other sources to go into another queue
84 (i.e. a second level of collection), with perhaps another level on top
87 XEmacs has its own types of events (called "Emacs events"), which
88 provides an abstract layer on top of the system-dependent nature of the
89 most basic events that are received. Part of the complex nature of the
90 XEmacs event collection process involves converting from the
91 operating-system events into the proper Emacs events--there may not be
92 a one-to-one correspondence.
94 Emacs events are documented in `events.h'; I'll discuss them later.
97 File: internals.info, Node: Main Loop, Next: Specifics of the Event Gathering Mechanism, Prev: Introduction to Events, Up: Events and the Event Loop
102 The "command loop" is the top-level loop that the editor is always
103 running. It loops endlessly, calling `next-event' to retrieve an event
104 and `dispatch-event' to execute it. `dispatch-event' does the
105 appropriate thing with non-user events (process, timeout, magic, eval,
106 mouse motion); this involves calling a Lisp handler function, redrawing
107 a newly-exposed part of a frame, reading subprocess output, etc. For
108 user events, `dispatch-event' looks up the event in relevant keymaps or
109 menubars; when a full key sequence or menubar selection is reached, the
110 appropriate function is executed. `dispatch-event' may have to keep
111 state across calls; this is done in the "command-builder" structure
112 associated with each console (remember, there's usually only one
113 console), and the engine that looks up keystrokes and constructs full
114 key sequences is called the "command builder". This is documented
117 The guts of the command loop are in `command_loop_1()'. This
118 function doesn't catch errors, though--that's the job of
119 `command_loop_2()', which is a condition-case (i.e. error-trapping)
120 wrapper around `command_loop_1()'. `command_loop_1()' never returns,
121 but may get thrown out of.
123 When an error occurs, `cmd_error()' is called, which usually invokes
124 the Lisp error handler in `command-error'; however, a default error
125 handler is provided if `command-error' is `nil' (e.g. during startup).
126 The purpose of the error handler is simply to display the error message
127 and do associated cleanup; it does not need to throw anywhere. When
128 the error handler finishes, the condition-case in `command_loop_2()'
129 will finish and `command_loop_2()' will reinvoke `command_loop_1()'.
131 `command_loop_2()' is invoked from three places: from
132 `initial_command_loop()' (called from `main()' at the end of internal
133 initialization), from the Lisp function `recursive-edit', and from
134 `call_command_loop()'.
136 `call_command_loop()' is called when a macro is started and when the
137 minibuffer is entered; normal termination of the macro or minibuffer
138 causes a throw out of the recursive command loop. (To
139 `execute-kbd-macro' for macros and `exit' for minibuffers. Note also
140 that the low-level minibuffer-entering function,
141 `read-minibuffer-internal', provides its own error handling and does
142 not need `command_loop_2()''s error encapsulation; so it tells
143 `call_command_loop()' to invoke `command_loop_1()' directly.)
145 Note that both read-minibuffer-internal and recursive-edit set up a
146 catch for `exit'; this is why `abort-recursive-edit', which throws to
147 this catch, exits out of either one.
149 `initial_command_loop()', called from `main()', sets up a catch for
150 `top-level' when invoking `command_loop_2()', allowing functions to
151 throw all the way to the top level if they really need to. Before
152 invoking `command_loop_2()', `initial_command_loop()' calls
153 `top_level_1()', which handles all of the startup stuff (creating the
154 initial frame, handling the command-line options, loading the user's
155 `.emacs' file, etc.). The function that actually does this is in Lisp
156 and is pointed to by the variable `top-level'; normally this function is
157 `normal-top-level'. `top_level_1()' is just an error-handling wrapper
158 similar to `command_loop_2()'. Note also that `initial_command_loop()'
159 sets up a catch for `top-level' when invoking `top_level_1()', just
160 like when it invokes `command_loop_2()'.
163 File: internals.info, Node: Specifics of the Event Gathering Mechanism, Next: Specifics About the Emacs Event, Prev: Main Loop, Up: Events and the Event Loop
165 Specifics of the Event Gathering Mechanism
166 ==========================================
168 Here is an approximate diagram of the collection processes at work
169 in XEmacs, under TTY's (TTY's are simpler than X so we'll look at this
172 asynch. asynch. asynch. asynch. [Collectors in
173 kbd events kbd events process process the OS]
176 | | | | SIGINT, [signal handlers
177 | | | | SIGQUIT, in XEmacs]
179 file file file file SIGALRM
180 desc. desc. desc. desc. |
181 (TTY) (TTY) (pipe) (pipe) |
182 | | | | fake timeouts
190 ------>-----------<----------------<----------------
193 | [collected using select() in emacs_tty_next_event()
194 | and converted to the appropriate Emacs event]
197 V (above this line is TTY-specific)
198 Emacs -----------------------------------------------
199 event (below this line is the generic event mechanism)
202 was there if not, call
203 a SIGINT? emacs_tty_next_event()
210 | [collected in event_stream_next_event();
211 | SIGINT is converted using maybe_read_quit_event()]
216 \---->------>----- maybe_kbd_translate() ---->---\
220 command event queue |
222 (contains events that were event queue, call
223 read earlier but not processed, event_stream_next_event()
224 typically when waiting in a |
225 sit-for, sleep-for, etc. for |
226 a particular event to be received) |
230 ---->------------------------------------<----
233 | next_event_internal()]
235 unread- unread- event from |
236 command- command- keyboard else, call
237 events event macro next_event_internal()
242 --------->----------------------<------------
244 | [collected in `next-event', which may loop
245 | more than once if the event it gets is on
246 | a dead frame, device, etc.]
250 feed into top-level event loop,
251 which repeatedly calls `next-event'
252 and then dispatches the event
253 using `dispatch-event'
255 Notice the separation between TTY-specific and generic event
256 mechanism. When using the Xt-based event loop, the TTY-specific stuff
257 is replaced but the rest stays the same.
259 It's also important to realize that only one different kind of
260 system-specific event loop can be operating at a time, and must be able
261 to receive all kinds of events simultaneously. For the two existing
262 event loops (implemented in `event-tty.c' and `event-Xt.c',
263 respectively), the TTY event loop _only_ handles TTY consoles, while
264 the Xt event loop handles _both_ TTY and X consoles. This situation is
265 different from all of the output handlers, where you simply have one
268 Here's the Xt Event Loop Diagram (notice that below a certain point,
269 it's the same as the above diagram):
271 asynch. asynch. asynch. asynch. [Collectors in
272 kbd kbd process process the OS]
273 events events output output
275 | | | | asynch. asynch. [Collectors in the
276 | | | | X X OS and X Window System]
277 | | | | events events
280 | | | | | | SIGINT, [signal handlers
281 | | | | | | SIGQUIT, in XEmacs]
282 | | | | | | SIGWINCH,
286 | | | | | | | timeouts
291 file file file file file file file |
292 desc. desc. desc. desc. desc. desc. desc. |
293 (TTY) (TTY) (pipe) (pipe) (socket) (socket) (pipe) |
298 --->----------------------------------------<---------<------
300 | | |[collected using select() in
301 | | | _XtWaitForSomething(), called
302 | | | from XtAppProcessEvent(), called
303 | | | in emacs_Xt_next_event();
304 | | | dispatched to various callbacks]
307 emacs_Xt_ p_s_callback(), | [popup_selection_callback]
308 event_handler() x_u_v_s_callback(),| [x_update_vertical_scrollbar_
309 | x_u_h_s_callback(),| callback]
310 | search_callback() | [x_update_horizontal_scrollbar_
314 enqueue_Xt_ signal_special_ |
315 dispatch_event() Xt_user_event() |
327 dispatch Xt_what_callback()
334 ---->-----------<--------
337 | [collected and converted as appropriate in
338 | emacs_Xt_next_event()]
341 V (above this line is Xt-specific)
342 Emacs ------------------------------------------------
343 event (below this line is the generic event mechanism)
346 was there if not, call
347 a SIGINT? emacs_Xt_next_event()
354 | [collected in event_stream_next_event();
355 | SIGINT is converted using maybe_read_quit_event()]
360 \---->------>----- maybe_kbd_translate() -->-----\
364 command event queue |
366 (contains events that were event queue, call
367 read earlier but not processed, event_stream_next_event()
368 typically when waiting in a |
369 sit-for, sleep-for, etc. for |
370 a particular event to be received) |
374 ---->----------------------------------<------
377 | next_event_internal()]
379 unread- unread- event from |
380 command- command- keyboard else, call
381 events event macro next_event_internal()
386 --------->----------------------<------------
388 | [collected in `next-event', which may loop
389 | more than once if the event it gets is on
390 | a dead frame, device, etc.]
394 feed into top-level event loop,
395 which repeatedly calls `next-event'
396 and then dispatches the event
397 using `dispatch-event'
400 File: internals.info, Node: Specifics About the Emacs Event, Next: The Event Stream Callback Routines, Prev: Specifics of the Event Gathering Mechanism, Up: Events and the Event Loop
402 Specifics About the Emacs Event
403 ===============================
406 File: internals.info, Node: The Event Stream Callback Routines, Next: Other Event Loop Functions, Prev: Specifics About the Emacs Event, Up: Events and the Event Loop
408 The Event Stream Callback Routines
409 ==================================
412 File: internals.info, Node: Other Event Loop Functions, Next: Converting Events, Prev: The Event Stream Callback Routines, Up: Events and the Event Loop
414 Other Event Loop Functions
415 ==========================
417 `detect_input_pending()' and `input-pending-p' look for input by
418 calling `event_stream->event_pending_p' and looking in
419 `[V]unread-command-event' and the `command_event_queue' (they do not
420 check for an executing keyboard macro, though).
422 `discard-input' cancels any command events pending (and any keyboard
423 macros currently executing), and puts the others onto the
424 `command_event_queue'. There is a comment about a "race condition",
425 which is not a good sign.
427 `next-command-event' and `read-char' are higher-level interfaces to
428 `next-event'. `next-command-event' gets the next "command" event (i.e.
429 keypress, mouse event, menu selection, or scrollbar action), calling
430 `dispatch-event' on any others. `read-char' calls `next-command-event'
431 and uses `event_to_character()' to return the character equivalent.
432 With the right kind of input method support, it is possible for
433 (read-char) to return a Kanji character.
436 File: internals.info, Node: Converting Events, Next: Dispatching Events; The Command Builder, Prev: Other Event Loop Functions, Up: Events and the Event Loop
441 `character_to_event()', `event_to_character()',
442 `event-to-character', and `character-to-event' convert between
443 characters and keypress events corresponding to the characters. If the
444 event was not a keypress, `event_to_character()' returns -1 and
445 `event-to-character' returns `nil'. These functions convert between
446 character representation and the split-up event representation (keysym
450 File: internals.info, Node: Dispatching Events; The Command Builder, Prev: Converting Events, Up: Events and the Event Loop
452 Dispatching Events; The Command Builder
453 =======================================
458 File: internals.info, Node: Evaluation; Stack Frames; Bindings, Next: Symbols and Variables, Prev: Events and the Event Loop, Up: Top
460 Evaluation; Stack Frames; Bindings
461 **********************************
466 * Dynamic Binding; The specbinding Stack; Unwind-Protects::
467 * Simple Special Forms::
471 File: internals.info, Node: Evaluation, Next: Dynamic Binding; The specbinding Stack; Unwind-Protects, Prev: Evaluation; Stack Frames; Bindings, Up: Evaluation; Stack Frames; Bindings
476 `Feval()' evaluates the form (a Lisp object) that is passed to it.
477 Note that evaluation is only non-trivial for two types of objects:
478 symbols and conses. A symbol is evaluated simply by calling
479 `symbol-value' on it and returning the value.
481 Evaluating a cons means calling a function. First, `eval' checks to
482 see if garbage-collection is necessary, and calls `garbage_collect_1()'
483 if so. It then increases the evaluation depth by 1 (`lisp_eval_depth',
484 which is always less than `max_lisp_eval_depth') and adds an element to
485 the linked list of `struct backtrace''s (`backtrace_list'). Each such
486 structure contains a pointer to the function being called plus a list
487 of the function's arguments. Originally these values are stored
488 unevalled, and as they are evaluated, the backtrace structure is
489 updated. Garbage collection pays attention to the objects pointed to
490 in the backtrace structures (garbage collection might happen while a
491 function is being called or while an argument is being evaluated, and
492 there could easily be no other references to the arguments in the
493 argument list; once an argument is evaluated, however, the unevalled
494 version is not needed by eval, and so the backtrace structure is
497 At this point, the function to be called is determined by looking at
498 the car of the cons (if this is a symbol, its function definition is
499 retrieved and the process repeated). The function should then consist
500 of either a `Lisp_Subr' (built-in function written in C), a
501 `Lisp_Compiled_Function' object, or a cons whose car is one of the
502 symbols `autoload', `macro' or `lambda'.
504 If the function is a `Lisp_Subr', the lisp object points to a
505 `struct Lisp_Subr' (created by `DEFUN()'), which contains a pointer to
506 the C function, a minimum and maximum number of arguments (or possibly
507 the special constants `MANY' or `UNEVALLED'), a pointer to the symbol
508 referring to that subr, and a couple of other things. If the subr
509 wants its arguments `UNEVALLED', they are passed raw as a list.
510 Otherwise, an array of evaluated arguments is created and put into the
511 backtrace structure, and either passed whole (`MANY') or each argument
512 is passed as a C argument.
514 If the function is a `Lisp_Compiled_Function',
515 `funcall_compiled_function()' is called. If the function is a lambda
516 list, `funcall_lambda()' is called. If the function is a macro, [.....
517 fill in] is done. If the function is an autoload, `do_autoload()' is
518 called to load the definition and then eval starts over [explain this
521 When `Feval()' exits, the evaluation depth is reduced by one, the
522 debugger is called if appropriate, and the current backtrace structure
523 is removed from the list.
525 Both `funcall_compiled_function()' and `funcall_lambda()' need to go
526 through the list of formal parameters to the function and bind them to
527 the actual arguments, checking for `&rest' and `&optional' symbols in
528 the formal parameters and making sure the number of actual arguments is
529 correct. `funcall_compiled_function()' can do this a little more
530 efficiently, since the formal parameter list can be checked for sanity
531 when the compiled function object is created.
533 `funcall_lambda()' simply calls `Fprogn' to execute the code in the
536 `funcall_compiled_function()' calls the real byte-code interpreter
537 `execute_optimized_program()' on the byte-code instructions, which are
538 converted into an internal form for faster execution.
540 When a compiled function is executed for the first time by
541 `funcall_compiled_function()', or during the dump phase of building
542 XEmacs, the byte-code instructions are converted from a `Lisp_String'
543 (which is inefficient to access, especially in the presence of MULE)
544 into a `Lisp_Opaque' object containing an array of unsigned char, which
545 can be directly executed by the byte-code interpreter. At this time
546 the byte code is also analyzed for validity and transformed into a more
547 optimized form, so that `execute_optimized_program()' can really fly.
549 Here are some of the optimizations performed by the internal
550 byte-code transformer:
551 1. References to the `constants' array are checked for out-of-range
552 indices, so that the byte interpreter doesn't have to.
554 2. References to the `constants' array that will be used as a Lisp
555 variable are checked for being correct non-constant (i.e. not `t',
556 `nil', or `keywordp') symbols, so that the byte interpreter
559 3. The maximum number of variable bindings in the byte-code is
560 pre-computed, so that space on the `specpdl' stack can be
561 pre-reserved once for the whole function execution.
563 4. All byte-code jumps are relative to the current program counter
564 instead of the start of the program, thereby saving a register.
566 5. One-byte relative jumps are converted from the byte-code form of
567 unsigned chars offset by 127 to machine-friendly signed chars.
569 Of course, this transformation of the `instructions' should not be
570 visible to the user, so `Fcompiled_function_instructions()' needs to
571 know how to convert the optimized opaque object back into a Lisp string
572 that is identical to the original string from the `.elc' file.
573 (Actually, the resulting string may (rarely) contain slightly
574 different, yet equivalent, byte code.)
576 `Ffuncall()' implements Lisp `funcall'. `(funcall fun x1 x2 x3
577 ...)' is equivalent to `(eval (list fun (quote x1) (quote x2) (quote
578 x3) ...))'. `Ffuncall()' contains its own code to do the evaluation,
579 however, and is very similar to `Feval()'.
581 From the performance point of view, it is worth knowing that most of
582 the time in Lisp evaluation is spent executing `Lisp_Subr' and
583 `Lisp_Compiled_Function' objects via `Ffuncall()' (not `Feval()').
585 `Fapply()' implements Lisp `apply', which is very similar to
586 `funcall' except that if the last argument is a list, the result is the
587 same as if each of the arguments in the list had been passed separately.
588 `Fapply()' does some business to expand the last argument if it's a
589 list, then calls `Ffuncall()' to do the work.
591 `apply1()', `call0()', `call1()', `call2()', and `call3()' call a
592 function, passing it the argument(s) given (the arguments are given as
593 separate C arguments rather than being passed as an array). `apply1()'
594 uses `Fapply()' while the others use `Ffuncall()' to do the real work.
597 File: internals.info, Node: Dynamic Binding; The specbinding Stack; Unwind-Protects, Next: Simple Special Forms, Prev: Evaluation, Up: Evaluation; Stack Frames; Bindings
599 Dynamic Binding; The specbinding Stack; Unwind-Protects
600 =======================================================
605 Lisp_Object old_value;
606 Lisp_Object (*func) (Lisp_Object); /* for unwind-protect */
609 `struct specbinding' is used for local-variable bindings and
610 unwind-protects. `specpdl' holds an array of `struct specbinding''s,
611 `specpdl_ptr' points to the beginning of the free bindings in the
612 array, `specpdl_size' specifies the total number of binding slots in
613 the array, and `max_specpdl_size' specifies the maximum number of
614 bindings the array can be expanded to hold. `grow_specpdl()' increases
615 the size of the `specpdl' array, multiplying its size by 2 but never
616 exceeding `max_specpdl_size' (except that if this number is less than
617 400, it is first set to 400).
619 `specbind()' binds a symbol to a value and is used for local
620 variables and `let' forms. The symbol and its old value (which might
621 be `Qunbound', indicating no prior value) are recorded in the specpdl
622 array, and `specpdl_size' is increased by 1.
624 `record_unwind_protect()' implements an "unwind-protect", which,
625 when placed around a section of code, ensures that some specified
626 cleanup routine will be executed even if the code exits abnormally
627 (e.g. through a `throw' or quit). `record_unwind_protect()' simply
628 adds a new specbinding to the `specpdl' array and stores the
629 appropriate information in it. The cleanup routine can either be a C
630 function, which is stored in the `func' field, or a `progn' form, which
631 is stored in the `old_value' field.
633 `unbind_to()' removes specbindings from the `specpdl' array until
634 the specified position is reached. Each specbinding can be one of
637 1. an unwind-protect with a C cleanup function (`func' is not 0, and
638 `old_value' holds an argument to be passed to the function);
640 2. an unwind-protect with a Lisp form (`func' is 0, `symbol' is
641 `nil', and `old_value' holds the form to be executed with
644 3. a local-variable binding (`func' is 0, `symbol' is not `nil', and
645 `old_value' holds the old value, which is stored as the symbol's
649 File: internals.info, Node: Simple Special Forms, Next: Catch and Throw, Prev: Dynamic Binding; The specbinding Stack; Unwind-Protects, Up: Evaluation; Stack Frames; Bindings
654 `or', `and', `if', `cond', `progn', `prog1', `prog2', `setq',
655 `quote', `function', `let*', `let', `while'
657 All of these are very simple and work as expected, calling `Feval()'
658 or `Fprogn()' as necessary and (in the case of `let' and `let*') using
659 `specbind()' to create bindings and `unbind_to()' to undo the bindings
662 Note that, with the exception of `Fprogn', these functions are
663 typically called in real life only in interpreted code, since the byte
664 compiler knows how to convert calls to these functions directly into
668 File: internals.info, Node: Catch and Throw, Prev: Simple Special Forms, Up: Evaluation; Stack Frames; Bindings
677 struct catchtag *next;
680 struct backtrace *backlist;
685 `catch' is a Lisp function that places a catch around a body of
686 code. A catch is a means of non-local exit from the code. When a catch
687 is created, a tag is specified, and executing a `throw' to this tag
688 will exit from the body of code caught with this tag, and its value will
689 be the value given in the call to `throw'. If there is no such call,
690 the code will be executed normally.
692 Information pertaining to a catch is held in a `struct catchtag',
693 which is placed at the head of a linked list pointed to by `catchlist'.
694 `internal_catch()' is passed a C function to call (`Fprogn()' when
695 Lisp `catch' is called) and arguments to give it, and places a catch
696 around the function. Each `struct catchtag' is held in the stack frame
697 of the `internal_catch()' instance that created the catch.
699 `internal_catch()' is fairly straightforward. It stores into the
700 `struct catchtag' the tag name and the current values of
701 `backtrace_list', `lisp_eval_depth', `gcprolist', and the offset into
702 the `specpdl' array, sets a jump point with `_setjmp()' (storing the
703 jump point into the `struct catchtag'), and calls the function.
704 Control will return to `internal_catch()' either when the function
705 exits normally or through a `_longjmp()' to this jump point. In the
706 latter case, `throw' will store the value to be returned into the
707 `struct catchtag' before jumping. When it's done, `internal_catch()'
708 removes the `struct catchtag' from the catchlist and returns the proper
711 `Fthrow()' goes up through the catchlist until it finds one with a
712 matching tag. It then calls `unbind_catch()' to restore everything to
713 what it was when the appropriate catch was set, stores the return value
714 in the `struct catchtag', and jumps (with `_longjmp()') to its jump
717 `unbind_catch()' removes all catches from the catchlist until it
718 finds the correct one. Some of the catches might have been placed for
719 error-trapping, and if so, the appropriate entries on the handlerlist
720 must be removed (see "errors"). `unbind_catch()' also restores the
721 values of `gcprolist', `backtrace_list', and `lisp_eval', and calls
722 `unbind_to()' to undo any specbindings created since the catch.
725 File: internals.info, Node: Symbols and Variables, Next: Buffers and Textual Representation, Prev: Evaluation; Stack Frames; Bindings, Up: Top
727 Symbols and Variables
728 *********************
732 * Introduction to Symbols::
737 File: internals.info, Node: Introduction to Symbols, Next: Obarrays, Prev: Symbols and Variables, Up: Symbols and Variables
739 Introduction to Symbols
740 =======================
742 A symbol is basically just an object with four fields: a name (a
743 string), a value (some Lisp object), a function (some Lisp object), and
744 a property list (usually a list of alternating keyword/value pairs).
745 What makes symbols special is that there is usually only one symbol with
746 a given name, and the symbol is referred to by name. This makes a
747 symbol a convenient way of calling up data by name, i.e. of implementing
748 variables. (The variable's value is stored in the "value slot".)
749 Similarly, functions are referenced by name, and the definition of the
750 function is stored in a symbol's "function slot". This means that
751 there can be a distinct function and variable with the same name. The
752 property list is used as a more general mechanism of associating
753 additional values with particular names, and once again the namespace is
754 independent of the function and variable namespaces.
757 File: internals.info, Node: Obarrays, Next: Symbol Values, Prev: Introduction to Symbols, Up: Symbols and Variables
762 The identity of symbols with their names is accomplished through a
763 structure called an obarray, which is just a poorly-implemented hash
764 table mapping from strings to symbols whose name is that string. (I say
765 "poorly implemented" because an obarray appears in Lisp as a vector
766 with some hidden fields rather than as its own opaque type. This is an
767 Emacs Lisp artifact that should be fixed.)
769 Obarrays are implemented as a vector of some fixed size (which should
770 be a prime for best results), where each "bucket" of the vector
771 contains one or more symbols, threaded through a hidden `next' field in
772 the symbol. Lookup of a symbol in an obarray, and adding a symbol to
773 an obarray, is accomplished through standard hash-table techniques.
775 The standard Lisp function for working with symbols and obarrays is
776 `intern'. This looks up a symbol in an obarray given its name; if it's
777 not found, a new symbol is automatically created with the specified
778 name, added to the obarray, and returned. This is what happens when the
779 Lisp reader encounters a symbol (or more precisely, encounters the name
780 of a symbol) in some text that it is reading. There is a standard
781 obarray called `obarray' that is used for this purpose, although the
782 Lisp programmer is free to create his own obarrays and `intern' symbols
785 Note that, once a symbol is in an obarray, it stays there until
786 something is done about it, and the standard obarray `obarray' always
787 stays around, so once you use any particular variable name, a
788 corresponding symbol will stay around in `obarray' until you exit
791 Note that `obarray' itself is a variable, and as such there is a
792 symbol in `obarray' whose name is `"obarray"' and which contains
793 `obarray' as its value.
795 Note also that this call to `intern' occurs only when in the Lisp
796 reader, not when the code is executed (at which point the symbol is
797 already around, stored as such in the definition of the function).
799 You can create your own obarray using `make-vector' (this is
800 horrible but is an artifact) and intern symbols into that obarray.
801 Doing that will result in two or more symbols with the same name.
802 However, at most one of these symbols is in the standard `obarray': You
803 cannot have two symbols of the same name in any particular obarray.
804 Note that you cannot add a symbol to an obarray in any fashion other
805 than using `intern': i.e. you can't take an existing symbol and put it
806 in an existing obarray. Nor can you change the name of an existing
807 symbol. (Since obarrays are vectors, you can violate the consistency of
808 things by storing directly into the vector, but let's ignore that
811 Usually symbols are created by `intern', but if you really want, you
812 can explicitly create a symbol using `make-symbol', giving it some
813 name. The resulting symbol is not in any obarray (i.e. it is
814 "uninterned"), and you can't add it to any obarray. Therefore its
815 primary purpose is as a symbol to use in macros to avoid namespace
816 pollution. It can also be used as a carrier of information, but cons
817 cells could probably be used just as well.
819 You can also use `intern-soft' to look up a symbol but not create a
820 new one, and `unintern' to remove a symbol from an obarray. This
821 returns the removed symbol. (Remember: You can't put the symbol back
822 into any obarray.) Finally, `mapatoms' maps over all of the symbols in
826 File: internals.info, Node: Symbol Values, Prev: Obarrays, Up: Symbols and Variables
831 The value field of a symbol normally contains a Lisp object.
832 However, a symbol can be "unbound", meaning that it logically has no
833 value. This is internally indicated by storing a special Lisp object,
834 called "the unbound marker" and stored in the global variable
835 `Qunbound'. The unbound marker is of a special Lisp object type called
836 "symbol-value-magic". It is impossible for the Lisp programmer to
837 directly create or access any object of this type.
839 *You must not let any "symbol-value-magic" object escape to the Lisp
840 level.* Printing any of these objects will cause the message `INTERNAL
841 EMACS BUG' to appear as part of the print representation. (You may see
842 this normally when you call `debug_print()' from the debugger on a Lisp
843 object.) If you let one of these objects escape to the Lisp level, you
844 will violate a number of assumptions contained in the C code and make
845 the unbound marker not function right.
847 When a symbol is created, its value field (and function field) are
848 set to `Qunbound'. The Lisp programmer can restore these conditions
849 later using `makunbound' or `fmakunbound', and can query to see whether
850 the value of function fields are "bound" (i.e. have a value other than
851 `Qunbound') using `boundp' and `fboundp'. The fields are set to a
852 normal Lisp object using `set' (or `setq') and `fset'.
854 Other symbol-value-magic objects are used as special markers to
855 indicate variables that have non-normal properties. This includes any
856 variables that are tied into C variables (setting the variable magically
857 sets some global variable in the C code, and likewise for retrieving the
858 variable's value), variables that magically tie into slots in the
859 current buffer, variables that are buffer-local, etc. The
860 symbol-value-magic object is stored in the value cell in place of a
861 normal object, and the code to retrieve a symbol's value (i.e.
862 `symbol-value') knows how to do special things with them. This means
863 that you should not just fetch the value cell directly if you want a
866 The exact workings of this are rather complex and involved and are
867 well-documented in comments in `buffer.c', `symbols.c', and `lisp.h'.
870 File: internals.info, Node: Buffers and Textual Representation, Next: MULE Character Sets and Encodings, Prev: Symbols and Variables, Up: Top
872 Buffers and Textual Representation
873 **********************************
877 * Introduction to Buffers:: A buffer holds a block of text such as a file.
878 * The Text in a Buffer:: Representation of the text in a buffer.
879 * Buffer Lists:: Keeping track of all buffers.
880 * Markers and Extents:: Tagging locations within a buffer.
881 * Bufbytes and Emchars:: Representation of individual characters.
882 * The Buffer Object:: The Lisp object corresponding to a buffer.
885 File: internals.info, Node: Introduction to Buffers, Next: The Text in a Buffer, Prev: Buffers and Textual Representation, Up: Buffers and Textual Representation
887 Introduction to Buffers
888 =======================
890 A buffer is logically just a Lisp object that holds some text. In
891 this, it is like a string, but a buffer is optimized for frequent
892 insertion and deletion, while a string is not. Furthermore:
894 1. Buffers are "permanent" objects, i.e. once you create them, they
895 remain around, and need to be explicitly deleted before they go
898 2. Each buffer has a unique name, which is a string. Buffers are
899 normally referred to by name. In this respect, they are like
902 3. Buffers have a default insertion position, called "point".
903 Inserting text (unless you explicitly give a position) goes at
904 point, and moves point forward past the text. This is what is
905 going on when you type text into Emacs.
907 4. Buffers have lots of extra properties associated with them.
909 5. Buffers can be "displayed". What this means is that there exist a
910 number of "windows", which are objects that correspond to some
911 visible section of your display, and each window has an associated
912 buffer, and the current contents of the buffer are shown in that
913 section of the display. The redisplay mechanism (which takes care
914 of doing this) knows how to look at the text of a buffer and come
915 up with some reasonable way of displaying this. Many of the
916 properties of a buffer control how the buffer's text is displayed.
918 6. One buffer is distinguished and called the "current buffer". It is
919 stored in the variable `current_buffer'. Buffer operations operate
920 on this buffer by default. When you are typing text into a
921 buffer, the buffer you are typing into is always `current_buffer'.
922 Switching to a different window changes the current buffer. Note
923 that Lisp code can temporarily change the current buffer using
924 `set-buffer' (often enclosed in a `save-excursion' so that the
925 former current buffer gets restored when the code is finished).
926 However, calling `set-buffer' will NOT cause a permanent change in
927 the current buffer. The reason for this is that the top-level
928 event loop sets `current_buffer' to the buffer of the selected
929 window, each time it finishes executing a user command.
931 Make sure you understand the distinction between "current buffer"
932 and "buffer of the selected window", and the distinction between
933 "point" of the current buffer and "window-point" of the selected
934 window. (This latter distinction is explained in detail in the section
projects / chise / xemacs-chise.git- / blob