From c773345a18b3b4c06ef91104b538992102c146e8 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Mon, 4 May 2009 04:07:28 +0000 Subject: [PATCH] * internals.texi (Object Internals): Don't assume 32-bit machines are the norm. (Buffer Internals): Consolidate table entries for readability. --- doc/lispref/ChangeLog | 6 + doc/lispref/internals.texi | 432 ++++++++++++++++++--------------------------- 2 files changed, 176 insertions(+), 262 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 5dda8f51cf8..f1bfb8b5a57 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,9 @@ +2009-05-04 Chong Yidong + + * internals.texi (Object Internals): Don't assume 32-bit machines + are the norm. + (Buffer Internals): Consolidate table entries for readability. + 2009-04-29 Chong Yidong * variables.texi (File Local Variables): Note that read-circle is diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 58c086a6f1d..349be6efc51 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -815,11 +815,10 @@ knows about it. GNU Emacs Lisp manipulates many different types of data. The actual data are stored in a heap and the only access that programs have to it -is through pointers. Pointers are thirty-two bits wide in most -implementations. Depending on the operating system and type of machine -for which you compile Emacs, twenty-nine bits are used to address the -object, and the remaining three bits are used for the tag that -identifies the object's type. +is through pointers. Each pointer is 32 bits wide on 32-bit machines, +and 64 bits wide on 64-bit machines; three of these bits are used for +the tag that identifies the object's type, and the remainder are used +to address the object. Because Lisp objects are represented as tagged pointers, it is always possible to determine the Lisp data type of any object. The C data type @@ -842,67 +841,53 @@ explicitly using a suitable predicate (@pxref{Type Predicates}). @cindex internals, of buffer @cindex buffer internals - Buffers contain fields not directly accessible by the Lisp programmer. -We describe them here, naming them by the names used in the C code. -Many are accessible indirectly in Lisp programs via Lisp primitives. - -Two structures are used to represent buffers in C. The + Two structures are used to represent buffers in C. The @code{buffer_text} structure contains fields describing the text of a buffer; the @code{buffer} structure holds other fields. In the case of indirect buffers, two or more @code{buffer} structures reference the same @code{buffer_text} structure. -Here is a list of the @code{struct buffer_text} fields: +Here are some of the fields in @code{struct buffer_text}: @table @code @item beg -This field contains the actual address of the buffer contents. +The address of the buffer contents. @item gpt -This holds the character position of the gap in the buffer. -@xref{Buffer Gap}. +@itemx gpt_byte +The character and byte positions of the buffer gap. @xref{Buffer +Gap}. @item z -This field contains the character position of the end of the buffer -text. - -@item gpt_byte -Contains the byte position of the gap. - -@item z_byte -Holds the byte position of the end of the buffer text. +@itemx z_byte +The character and byte positions of the end of the buffer text. @item gap_size -Contains the size of buffer's gap. @xref{Buffer Gap}. +The size of buffer's gap. @xref{Buffer Gap}. @item modiff -This field counts buffer-modification events for this buffer. It is -incremented for each such event, and never otherwise changed. - -@item save_modiff -Contains the previous value of @code{modiff}, as of the last time a -buffer was visited or saved in a file. - -@item overlay_modiff -Counts modifications to overlays analogous to @code{modiff}. +@itemx save_modiff +@itemx chars_modiff +@itemx overlay_modiff +These fields count the number of buffer-modification events performed +in this buffer. @code{modiff} is incremented after each +buffer-modification event, and is never otherwise changed; +@code{save_modiff} contains the value of @code{modiff} the last time +the buffer was visited or saved; @code{chars_modiff} counts only +modifications to the characters in the buffer, ignoring all other +kinds of changes; and @code{overlay_modiff} counts only modifications +to the overlays. @item beg_unchanged -Holds the number of characters at the start of the text that are known -to be unchanged since the last redisplay that finished. - -@item end_unchanged -Holds the number of characters at the end of the text that are known to -be unchanged since the last redisplay that finished. +@itemx end_unchanged +The number of characters at the start and end of the text that are +known to be unchanged since the last complete redisplay. @item unchanged_modified -Contains the value of @code{modiff} at the time of the last redisplay -that finished. If this value matches @code{modiff}, -@code{beg_unchanged} and @code{end_unchanged} contain no useful -information. - -@item overlay_unchanged_modified -Contains the value of @code{overlay_modiff} at the time of the last -redisplay that finished. If this value matches @code{overlay_modiff}, +@itemx overlay_unchanged_modified +The values of @code{modiff} and @code{overlay_modiff}, respectively, +after the last compelete redisplay. If their current values match +@code{modiff} or @code{overlay_modiff}, that means @code{beg_unchanged} and @code{end_unchanged} contain no useful information. @@ -912,286 +897,209 @@ marker, and successive elements in its marker @code{chain} are the other markers referring to this buffer text. @item intervals -Contains the interval tree which records the text properties of this -buffer. +The interval tree which records the text properties of this buffer. @end table -The fields of @code{struct buffer} are: +Some of the fields of @code{struct buffer} are: @table @code @item next -Points to the next buffer, in the chain of all buffers including killed -buffers. This chain is used only for garbage collection, in order to -collect killed buffers properly. Note that vectors, and most kinds of -objects allocated as vectors, are all on one chain, but buffers are on a -separate chain of their own. +Points to the next buffer, in the chain of all buffers (including +killed buffers). This chain is used only for garbage collection, in +order to collect killed buffers properly. Note that vectors, and most +kinds of objects allocated as vectors, are all on one chain, but +buffers are on a separate chain of their own. @item own_text -This is a @code{struct buffer_text} structure. In an ordinary buffer, -it holds the buffer contents. In indirect buffers, this field is not -used. +A @code{struct buffer_text} structure that ordinarily holds the buffer +contents. In indirect buffers, this field is not used. @item text -This points to the @code{buffer_text} structure that is used for this -buffer. In an ordinary buffer, this is the @code{own_text} field above. -In an indirect buffer, this is the @code{own_text} field of the base -buffer. +A pointer to the @code{buffer_text} structure for this buffer. In an +ordinary buffer, this is the @code{own_text} field above. In an +indirect buffer, this is the @code{own_text} field of the base buffer. @item pt -Contains the character position of point in a buffer. - -@item pt_byte -Contains the byte position of point in a buffer. +@itemx pt_byte +The character and byte positions of point in a buffer. @item begv -This field contains the character position of the beginning of the -accessible range of text in the buffer. - -@item begv_byte -This field contains the byte position of the beginning of the -accessible range of text in the buffer. +@itemx begv_byte +The character and byte positions of the beginning of the accessible +range of text in the buffer. @item zv -This field contains the character position of the end of the -accessible range of text in the buffer. - -@item zv_byte -This field contains the byte position of the end of the -accessible range of text in the buffer. +@itemx zv_byte +The character and byte positions of the end of the accessible range of +text in the buffer. @item base_buffer In an indirect buffer, this points to the base buffer. In an ordinary buffer, it is null. -@item local_var_flags -This field contains flags indicating that certain variables are local in -this buffer. Such variables are declared in the C code using -@code{DEFVAR_PER_BUFFER}, and their buffer-local bindings are stored in -fields in the buffer structure itself. (Some of these fields are +@item local_flags +This field contains flags indicating that certain variables are local +in this buffer. Such variables are declared in the C code using +@code{DEFVAR_PER_BUFFER}, and their buffer-local bindings are stored +in fields in the buffer structure itself. (Some of these fields are described in this table.) @item modtime -This field contains the modification time of the visited file. It is -set when the file is written or read. Before writing the buffer into a -file, this field is compared to the modification time of the file to see -if the file has changed on disk. @xref{Buffer Modification}. +The modification time of the visited file. It is set when the file is +written or read. Before writing the buffer into a file, this field is +compared to the modification time of the file to see if the file has +changed on disk. @xref{Buffer Modification}. @item auto_save_modified -This field contains the time when the buffer was last auto-saved. - -@item auto_save_failure_time -The time at which we detected a failure to auto-save, or -1 if we didn't -have a failure. +The time when the buffer was last auto-saved. @item last_window_start -This field contains the @code{window-start} position in the buffer as of -the last time the buffer was displayed in a window. +The @code{window-start} position in the buffer as of the last time the +buffer was displayed in a window. @item clip_changed -This flag is set when narrowing changes in a buffer. +This flag indicates that narrowing has changed in the buffer. +@xref{Narrowing}. @item prevent_redisplay_optimizations_p -this flag indicates that redisplay optimizations should not be used -to display this buffer. +This flag indicates that redisplay optimizations should not be used to +display this buffer. -@item undo_list -This field points to the buffer's undo list. @xref{Undo}. +@item overlay_center +This field holds the current overlay center position. @xref{Managing +Overlays}. + +@item overlays_before +@itemx overlays_after +These fields hold, respectively, a list of overlays that end at or +before the current overlay center, and a list of overlays that end +after the current overlay center. @xref{Managing Overlays}. +@code{overlays_before} is sorted in order of decreasing end position, +and @code{overlays_after} is sorted in order of increasing beginning +position. @item name -The buffer name is a string that names the buffer. It is guaranteed to -be unique. @xref{Buffer Names}. +A Lisp string that names the buffer. It is guaranteed to be unique. +@xref{Buffer Names}. -@item filename -The name of the file visited in this buffer, or @code{nil}. +@item save_length +The length of the file this buffer is visiting, when last read or +saved. This and other fields concerned with saving are not kept in +the @code{buffer_text} structure because indirect buffers are never +saved. @item directory -The directory for expanding relative file names. +The directory for expanding relative file names. This is the value of +the buffer-local variable @code{default-directory} (@pxref{File Name Expansion}). -@item save_length -Length of the file this buffer is visiting, when last read or saved. -This and other fields concerned with saving are not kept in the -@code{buffer_text} structure because indirect buffers are never saved. - -@item auto_save_file_name -File name used for auto-saving this buffer. This is not in the -@code{buffer_text} because it's not used in indirect buffers at all. +@item filename +The name of the file visited in this buffer, or @code{nil}. This is +the value of the buffer-local variable @code{buffer-file-name} +(@pxref{Buffer File Name}). -@item read_only -Non-@code{nil} means this buffer is read-only. +@item undo_list +@itemx backed_up +@itemx auto_save_file_name +@itemx read_only +@itemx file_format +@itemx file_truename +@itemx invisibility_spec +@itemx display_count +@itemx display_time +These fields store the values of Lisp variables that are automatically +buffer-local (@pxref{Buffer-Local Variables}), whose corresponding +variable names have the additional prefix @code{buffer-} and have +underscores replaced with dashes. For instance, @code{undo_list} +stores the value of @code{buffer-undo-list}. @xref{Standard +Buffer-Local Variables}. @item mark -This field contains the mark for the buffer. The mark is a marker, -hence it is also included on the list @code{markers}. @xref{The Mark}. +The mark for the buffer. The mark is a marker, hence it is also +included on the list @code{markers}. @xref{The Mark}. @item local_var_alist -This field contains the association list describing the buffer-local -variable bindings of this buffer, not including the built-in -buffer-local bindings that have special slots in the buffer object. -(Those slots are omitted from this table.) @xref{Buffer-Local -Variables}. +The association list describing the buffer-local variable bindings of +this buffer, not including the built-in buffer-local bindings that +have special slots in the buffer object. (Those slots are omitted +from this table.) @xref{Buffer-Local Variables}. @item major_mode Symbol naming the major mode of this buffer, e.g., @code{lisp-mode}. @item mode_name -Pretty name of major mode, e.g., @code{"Lisp"}. - -@item mode_line_format -Mode line element that controls the format of the mode line. If this -is @code{nil}, no mode line will be displayed. - -@item header_line_format -This field is analogous to @code{mode_line_format} for the mode -line displayed at the top of windows. +Pretty name of the major mode, e.g., @code{"Lisp"}. @item keymap -This field holds the buffer's local keymap. @xref{Keymaps}. - -@item abbrev_table -This buffer's local abbrevs. - -@item syntax_table -This field contains the syntax table for the buffer. @xref{Syntax Tables}. - -@item category_table -This field contains the category table for the buffer. - -@item case_fold_search -The value of @code{case-fold-search} in this buffer. - -@item tab_width -The value of @code{tab-width} in this buffer. - -@item fill_column -The value of @code{fill-column} in this buffer. - -@item left_margin -The value of @code{left-margin} in this buffer. - -@item auto_fill_function -The value of @code{auto-fill-function} in this buffer. +@itemx abbrev_table +@itemx syntax_table +@itemx category_table +@itemx display_table +These fields store the buffer's local keymap (@pxref{Keymaps}), abbrev +table (@pxref{Abbrev Tables}), syntax table (@pxref{Syntax Tables}), +category table (@pxref{Categories}), and display table (@pxref{Display +Tables}). @item downcase_table -This field contains the conversion table for converting text to lower case. -@xref{Case Tables}. - -@item upcase_table -This field contains the conversion table for converting text to upper case. +@itemx upcase_table +@itemx case_canon_table +These fields store the conversion tables for converting text to lower +case, upper case, and for canonicalizing text for case-fold search. @xref{Case Tables}. -@item case_canon_table -This field contains the conversion table for canonicalizing text for -case-folding search. @xref{Case Tables}. - -@item case_eqv_table -This field contains the equivalence table for case-folding search. -@xref{Case Tables}. - -@item truncate_lines -The value of @code{truncate-lines} in this buffer. - -@item ctl_arrow -The value of @code{ctl-arrow} in this buffer. - -@item selective_display -The value of @code{selective-display} in this buffer. - -@item selective_display_ellipsis -The value of @code{selective-display-ellipsis} in this buffer. - @item minor_modes An alist of the minor modes of this buffer. -@item overwrite_mode -The value of @code{overwrite_mode} in this buffer. - -@item abbrev_mode -The value of @code{abbrev-mode} in this buffer. - -@item display_table -This field contains the buffer's display table, or @code{nil} if it doesn't -have one. @xref{Display Tables}. - -@item save_modified -This field contains the time when the buffer was last saved, as an integer. -@xref{Buffer Modification}. - -@item mark_active -This field is non-@code{nil} if the buffer's mark is active. - -@item overlays_before -This field holds a list of the overlays in this buffer that end at or -before the current overlay center position. They are sorted in order of -decreasing end position. - -@item overlays_after -This field holds a list of the overlays in this buffer that end after -the current overlay center position. They are sorted in order of -increasing beginning position. - -@item overlay_center -This field holds the current overlay center position. @xref{Overlays}. - -@item enable_multibyte_characters -This field holds the buffer's local value of -@code{enable-multibyte-characters}---either @code{t} or @code{nil}. - -@item buffer_file_coding_system -The value of @code{buffer-file-coding-system} in this buffer. - -@item file_format -The value of @code{buffer-file-format} in this buffer. - -@item auto_save_file_format -The value of @code{buffer-auto-save-file-format} in this buffer. - @item pt_marker -In an indirect buffer, or a buffer that is the base of an indirect -buffer, this holds a marker that records point for this buffer when the -buffer is not current. - -@item begv_marker -In an indirect buffer, or a buffer that is the base of an indirect -buffer, this holds a marker that records @code{begv} for this buffer +@itemx begv_marker +@itemx zv_marker +These fields are only used in an indirect buffer, or in a buffer that +is the base of an indirect buffer. Each holds a marker that records +@code{pt}, @code{begv}, and @code{zv} respectively, for this buffer when the buffer is not current. -@item zv_marker -In an indirect buffer, or a buffer that is the base of an indirect -buffer, this holds a marker that records @code{zv} for this buffer when -the buffer is not current. - -@item file_truename -The truename of the visited file, or @code{nil}. - -@item invisibility_spec -The value of @code{buffer-invisibility-spec} in this buffer. +@item mode_line_format +@itemx header_line_format +@itemx case_fold_search +@itemx tab_width +@itemx fill_column +@itemx left_margin +@itemx auto_fill_function +@itemx buffer_file_type +@itemx truncate_lines +@itemx word_wrap +@itemx ctl_arrow +@itemx selective_display +@itemx selective_display_ellipses +@itemx overwrite_mode +@itemx abbrev_mode +@itemx display_table +@itemx mark_active +@itemx enable_multibyte_characters +@itemx buffer_file_coding_system +@itemx auto_save_file_format +@itemx cache_long_line_scans +@itemx point_before_scroll +@itemx left_fringe_width +@itemx right_fringe_width +@itemx fringes_outside_margins +@itemx scroll_bar_width +@itemx indicate_empty_lines +@itemx indicate_buffer_boundaries +@itemx fringe_indicator_alist +@itemx fringe_cursor_alist +@itemx scroll_up_aggressively +@itemx scroll_down_aggressively +@itemx cursor_type +@itemx cursor_in_non_selected_windows +These fields store the values of Lisp variables that are automatically +buffer-local (@pxref{Buffer-Local Variables}), whose corresponding +variable names have underscores replaced with dashes. For instance, +@code{mode_line_format} stores the value of @code{mode-line-format}. +@xref{Standard Buffer-Local Variables}. @item last_selected_window This is the last window that was selected with this buffer in it, or @code{nil} if that window no longer displays this buffer. - -@item display_count -This field is incremented each time the buffer is displayed in a window. - -@item left_margin_width -The value of @code{left-margin-width} in this buffer. - -@item right_margin_width -The value of @code{right-margin-width} in this buffer. - -@item indicate_empty_lines -Non-@code{nil} means indicate empty lines (lines with no text) with a -small bitmap in the fringe, when using a window system that can do it. - -@item display_time -This holds a time stamp that is updated each time this buffer is -displayed in a window. - -@item scroll_up_aggressively -The value of @code{scroll-up-aggressively} in this buffer. - -@item scroll_down_aggressively -The value of @code{scroll-down-aggressively} in this buffer. @end table @node Window Internals -- 2.11.4.GIT