Mercurial > hg > xemacs-beta
comparison man/internals/internals.texi @ 5127:a9c41067dd88 ben-lisp-object
more cleanups, terminology clarification, lots of doc work
-------------------- ChangeLog entries follow: --------------------
man/ChangeLog addition:
2010-03-05 Ben Wing <ben@xemacs.org>
* internals/internals.texi (Introduction to Allocation):
* internals/internals.texi (Integers and Characters):
* internals/internals.texi (Allocation from Frob Blocks):
* internals/internals.texi (lrecords):
* internals/internals.texi (Low-level allocation):
Rewrite section on allocation of Lisp objects to reflect the new
reality. Remove references to nonexistent XSETINT and XSETCHAR.
modules/ChangeLog addition:
2010-03-05 Ben Wing <ben@xemacs.org>
* postgresql/postgresql.c (allocate_pgconn):
* postgresql/postgresql.c (allocate_pgresult):
* postgresql/postgresql.h (struct Lisp_PGconn):
* postgresql/postgresql.h (struct Lisp_PGresult):
* ldap/eldap.c (allocate_ldap):
* ldap/eldap.h (struct Lisp_LDAP):
Same changes as in src/ dir. See large log there in ChangeLog,
but basically:
ALLOC_LISP_OBJECT -> ALLOC_NORMAL_LISP_OBJECT
LISP_OBJECT_HEADER -> NORMAL_LISP_OBJECT_HEADER
../hlo/src/ChangeLog addition:
2010-03-05 Ben Wing <ben@xemacs.org>
* alloc.c:
* alloc.c (old_alloc_sized_lcrecord):
* alloc.c (very_old_free_lcrecord):
* alloc.c (copy_lisp_object):
* alloc.c (zero_sized_lisp_object):
* alloc.c (zero_nonsized_lisp_object):
* alloc.c (lisp_object_storage_size):
* alloc.c (free_normal_lisp_object):
* alloc.c (FREE_FIXED_TYPE_WHEN_NOT_IN_GC):
* alloc.c (ALLOC_FROB_BLOCK_LISP_OBJECT):
* alloc.c (Fcons):
* alloc.c (noseeum_cons):
* alloc.c (make_float):
* alloc.c (make_bignum):
* alloc.c (make_bignum_bg):
* alloc.c (make_ratio):
* alloc.c (make_ratio_bg):
* alloc.c (make_ratio_rt):
* alloc.c (make_bigfloat):
* alloc.c (make_bigfloat_bf):
* alloc.c (size_vector):
* alloc.c (make_compiled_function):
* alloc.c (Fmake_symbol):
* alloc.c (allocate_extent):
* alloc.c (allocate_event):
* alloc.c (make_key_data):
* alloc.c (make_button_data):
* alloc.c (make_motion_data):
* alloc.c (make_process_data):
* alloc.c (make_timeout_data):
* alloc.c (make_magic_data):
* alloc.c (make_magic_eval_data):
* alloc.c (make_eval_data):
* alloc.c (make_misc_user_data):
* alloc.c (Fmake_marker):
* alloc.c (noseeum_make_marker):
* alloc.c (size_string_direct_data):
* alloc.c (make_uninit_string):
* alloc.c (make_string_nocopy):
* alloc.c (mark_lcrecord_list):
* alloc.c (alloc_managed_lcrecord):
* alloc.c (free_managed_lcrecord):
* alloc.c (sweep_lcrecords_1):
* alloc.c (malloced_storage_size):
* buffer.c (allocate_buffer):
* buffer.c (compute_buffer_usage):
* buffer.c (DEFVAR_BUFFER_LOCAL_1):
* buffer.c (nuke_all_buffer_slots):
* buffer.c (common_init_complex_vars_of_buffer):
* buffer.h (struct buffer_text):
* buffer.h (struct buffer):
* bytecode.c:
* bytecode.c (make_compiled_function_args):
* bytecode.c (size_compiled_function_args):
* bytecode.h (struct compiled_function_args):
* casetab.c (allocate_case_table):
* casetab.h (struct Lisp_Case_Table):
* charset.h (struct Lisp_Charset):
* chartab.c (fill_char_table):
* chartab.c (Fmake_char_table):
* chartab.c (make_char_table_entry):
* chartab.c (copy_char_table_entry):
* chartab.c (Fcopy_char_table):
* chartab.c (put_char_table):
* chartab.h (struct Lisp_Char_Table_Entry):
* chartab.h (struct Lisp_Char_Table):
* console-gtk-impl.h (struct gtk_device):
* console-gtk-impl.h (struct gtk_frame):
* console-impl.h (struct console):
* console-msw-impl.h (struct Lisp_Devmode):
* console-msw-impl.h (struct mswindows_device):
* console-msw-impl.h (struct msprinter_device):
* console-msw-impl.h (struct mswindows_frame):
* console-msw-impl.h (struct mswindows_dialog_id):
* console-stream-impl.h (struct stream_console):
* console-stream.c (stream_init_console):
* console-tty-impl.h (struct tty_console):
* console-tty-impl.h (struct tty_device):
* console-tty.c (allocate_tty_console_struct):
* console-x-impl.h (struct x_device):
* console-x-impl.h (struct x_frame):
* console.c (allocate_console):
* console.c (nuke_all_console_slots):
* console.c (DEFVAR_CONSOLE_LOCAL_1):
* console.c (common_init_complex_vars_of_console):
* data.c (make_weak_list):
* data.c (make_weak_box):
* data.c (make_ephemeron):
* database.c:
* database.c (struct Lisp_Database):
* database.c (allocate_database):
* database.c (finalize_database):
* device-gtk.c (allocate_gtk_device_struct):
* device-impl.h (struct device):
* device-msw.c:
* device-msw.c (mswindows_init_device):
* device-msw.c (msprinter_init_device):
* device-msw.c (finalize_devmode):
* device-msw.c (allocate_devmode):
* device-tty.c (allocate_tty_device_struct):
* device-x.c (allocate_x_device_struct):
* device.c:
* device.c (nuke_all_device_slots):
* device.c (allocate_device):
* dialog-msw.c (handle_question_dialog_box):
* elhash.c:
* elhash.c (struct Lisp_Hash_Table):
* elhash.c (finalize_hash_table):
* elhash.c (make_general_lisp_hash_table):
* elhash.c (Fcopy_hash_table):
* elhash.h (htentry):
* emacs.c (main_1):
* eval.c:
* eval.c (size_multiple_value):
* event-stream.c (finalize_command_builder):
* event-stream.c (allocate_command_builder):
* event-stream.c (free_command_builder):
* event-stream.c (event_stream_generate_wakeup):
* event-stream.c (event_stream_resignal_wakeup):
* event-stream.c (event_stream_disable_wakeup):
* event-stream.c (event_stream_wakeup_pending_p):
* events.h (struct Lisp_Timeout):
* events.h (struct command_builder):
* extents-impl.h:
* extents-impl.h (struct extent_auxiliary):
* extents-impl.h (struct extent_info):
* extents-impl.h (set_extent_no_chase_aux_field):
* extents-impl.h (set_extent_no_chase_normal_field):
* extents.c:
* extents.c (gap_array_marker):
* extents.c (gap_array):
* extents.c (extent_list_marker):
* extents.c (extent_list):
* extents.c (stack_of_extents):
* extents.c (gap_array_make_marker):
* extents.c (extent_list_make_marker):
* extents.c (allocate_extent_list):
* extents.c (SLOT):
* extents.c (mark_extent_auxiliary):
* extents.c (allocate_extent_auxiliary):
* extents.c (attach_extent_auxiliary):
* extents.c (size_gap_array):
* extents.c (finalize_extent_info):
* extents.c (allocate_extent_info):
* extents.c (uninit_buffer_extents):
* extents.c (allocate_soe):
* extents.c (copy_extent):
* extents.c (vars_of_extents):
* extents.h:
* faces.c (allocate_face):
* faces.h (struct Lisp_Face):
* faces.h (struct face_cachel):
* file-coding.c:
* file-coding.c (finalize_coding_system):
* file-coding.c (sizeof_coding_system):
* file-coding.c (Fcopy_coding_system):
* file-coding.h (struct Lisp_Coding_System):
* file-coding.h (MARKED_SLOT):
* fns.c (size_bit_vector):
* font-mgr.c:
* font-mgr.c (finalize_fc_pattern):
* font-mgr.c (print_fc_pattern):
* font-mgr.c (Ffc_pattern_p):
* font-mgr.c (Ffc_pattern_create):
* font-mgr.c (Ffc_name_parse):
* font-mgr.c (Ffc_name_unparse):
* font-mgr.c (Ffc_pattern_duplicate):
* font-mgr.c (Ffc_pattern_add):
* font-mgr.c (Ffc_pattern_del):
* font-mgr.c (Ffc_pattern_get):
* font-mgr.c (fc_config_create_using):
* font-mgr.c (fc_strlist_to_lisp_using):
* font-mgr.c (fontset_to_list):
* font-mgr.c (Ffc_config_p):
* font-mgr.c (Ffc_config_up_to_date):
* font-mgr.c (Ffc_config_build_fonts):
* font-mgr.c (Ffc_config_get_cache):
* font-mgr.c (Ffc_config_get_fonts):
* font-mgr.c (Ffc_config_set_current):
* font-mgr.c (Ffc_config_get_blanks):
* font-mgr.c (Ffc_config_get_rescan_interval):
* font-mgr.c (Ffc_config_set_rescan_interval):
* font-mgr.c (Ffc_config_app_font_add_file):
* font-mgr.c (Ffc_config_app_font_add_dir):
* font-mgr.c (Ffc_config_app_font_clear):
* font-mgr.c (size):
* font-mgr.c (Ffc_config_substitute):
* font-mgr.c (Ffc_font_render_prepare):
* font-mgr.c (Ffc_font_match):
* font-mgr.c (Ffc_font_sort):
* font-mgr.c (finalize_fc_config):
* font-mgr.c (print_fc_config):
* font-mgr.h:
* font-mgr.h (struct fc_pattern):
* font-mgr.h (XFC_PATTERN):
* font-mgr.h (struct fc_config):
* font-mgr.h (XFC_CONFIG):
* frame-gtk.c (allocate_gtk_frame_struct):
* frame-impl.h (struct frame):
* frame-msw.c (mswindows_init_frame_1):
* frame-x.c (allocate_x_frame_struct):
* frame.c (nuke_all_frame_slots):
* frame.c (allocate_frame_core):
* gc.c:
* gc.c (GC_CHECK_NOT_FREE):
* glyphs.c (finalize_image_instance):
* glyphs.c (allocate_image_instance):
* glyphs.c (Fcolorize_image_instance):
* glyphs.c (allocate_glyph):
* glyphs.c (unmap_subwindow_instance_cache_mapper):
* glyphs.c (register_ignored_expose):
* glyphs.h (struct Lisp_Image_Instance):
* glyphs.h (struct Lisp_Glyph):
* glyphs.h (struct glyph_cachel):
* glyphs.h (struct expose_ignore):
* gui.c (allocate_gui_item):
* gui.h (struct Lisp_Gui_Item):
* keymap.c (struct Lisp_Keymap):
* keymap.c (make_keymap):
* lisp.h:
* lisp.h (struct Lisp_String_Direct_Data):
* lisp.h (struct Lisp_String_Indirect_Data):
* lisp.h (struct Lisp_Vector):
* lisp.h (struct Lisp_Bit_Vector):
* lisp.h (DECLARE_INLINE_LISP_BIT_VECTOR):
* lisp.h (struct weak_box):
* lisp.h (struct ephemeron):
* lisp.h (struct weak_list):
* lrecord.h:
* lrecord.h (struct lrecord_implementation):
* lrecord.h (MC_ALLOC_CALL_FINALIZER):
* lrecord.h (struct lcrecord_list):
* lstream.c (finalize_lstream):
* lstream.c (sizeof_lstream):
* lstream.c (Lstream_new):
* lstream.c (Lstream_delete):
* lstream.h (struct lstream):
* marker.c:
* marker.c (finalize_marker):
* marker.c (compute_buffer_marker_usage):
* mule-charset.c:
* mule-charset.c (make_charset):
* mule-charset.c (compute_charset_usage):
* objects-impl.h (struct Lisp_Color_Instance):
* objects-impl.h (struct Lisp_Font_Instance):
* objects-tty-impl.h (struct tty_color_instance_data):
* objects-tty-impl.h (struct tty_font_instance_data):
* objects-tty.c (tty_initialize_color_instance):
* objects-tty.c (tty_initialize_font_instance):
* objects.c (finalize_color_instance):
* objects.c (Fmake_color_instance):
* objects.c (finalize_font_instance):
* objects.c (Fmake_font_instance):
* objects.c (reinit_vars_of_objects):
* opaque.c:
* opaque.c (sizeof_opaque):
* opaque.c (make_opaque_ptr):
* opaque.c (free_opaque_ptr):
* opaque.h:
* opaque.h (Lisp_Opaque):
* opaque.h (Lisp_Opaque_Ptr):
* print.c (printing_unreadable_lcrecord):
* print.c (external_object_printer):
* print.c (debug_p4):
* process.c (finalize_process):
* process.c (make_process_internal):
* procimpl.h (struct Lisp_Process):
* rangetab.c (Fmake_range_table):
* rangetab.c (Fcopy_range_table):
* rangetab.h (struct Lisp_Range_Table):
* scrollbar.c:
* scrollbar.c (create_scrollbar_instance):
* scrollbar.c (compute_scrollbar_instance_usage):
* scrollbar.h (struct scrollbar_instance):
* specifier.c (finalize_specifier):
* specifier.c (sizeof_specifier):
* specifier.c (set_specifier_caching):
* specifier.h (struct Lisp_Specifier):
* specifier.h (struct specifier_caching):
* symeval.h:
* symeval.h (SYMBOL_VALUE_MAGIC_P):
* symeval.h (DEFVAR_SYMVAL_FWD):
* symsinit.h:
* syntax.c (init_buffer_syntax_cache):
* syntax.h (struct syntax_cache):
* toolbar.c:
* toolbar.c (allocate_toolbar_button):
* toolbar.c (update_toolbar_button):
* toolbar.h (struct toolbar_button):
* tooltalk.c (struct Lisp_Tooltalk_Message):
* tooltalk.c (make_tooltalk_message):
* tooltalk.c (struct Lisp_Tooltalk_Pattern):
* tooltalk.c (make_tooltalk_pattern):
* ui-gtk.c:
* ui-gtk.c (allocate_ffi_data):
* ui-gtk.c (emacs_gtk_object_finalizer):
* ui-gtk.c (allocate_emacs_gtk_object_data):
* ui-gtk.c (allocate_emacs_gtk_boxed_data):
* ui-gtk.h:
* window-impl.h (struct window):
* window-impl.h (struct window_mirror):
* window.c (finalize_window):
* window.c (allocate_window):
* window.c (new_window_mirror):
* window.c (mark_window_as_deleted):
* window.c (make_dummy_parent):
* window.c (compute_window_mirror_usage):
* window.c (compute_window_usage):
Overall point of this change and previous ones in this repository:
(1) Introduce new, clearer terminology: everything other than int
or char is a "record" object, which comes in two types: "normal
objects" and "frob-block objects". Fix up all places that
referred to frob-block objects as "simple", "basic", etc.
(2) Provide an advertised interface for doing operations on Lisp
objects, including creating new types, that is clean and
consistent in its naming, uses the above-referenced terms and
avoids referencing "lrecords", "old lcrecords", etc., which should
hide under the surface.
(3) Make the size_in_bytes and finalizer methods take a
Lisp_Object rather than a void * for consistency with other methods.
(4) Separate finalizer method into finalizer and disksaver, so
that normal finalize methods don't have to worry about disksaving.
Other specifics:
(1) Renaming:
LISP_OBJECT_HEADER -> NORMAL_LISP_OBJECT_HEADER
ALLOC_LISP_OBJECT -> ALLOC_NORMAL_LISP_OBJECT
implementation->basic_p -> implementation->frob_block_p
ALLOCATE_FIXED_TYPE_AND_SET_IMPL -> ALLOC_FROB_BLOCK_LISP_OBJECT
*FCCONFIG*, wrap_fcconfig -> *FC_CONFIG*, wrap_fc_config
*FCPATTERN*, wrap_fcpattern -> *FC_PATTERN*, wrap_fc_pattern
(the last two changes make the naming of these macros consistent
with the naming of all other macros, since the objects are named
fc-config and fc-pattern with a hyphen)
(2) Lots of documentation fixes in lrecord.h.
(3) Eliminate macros for copying, freeing, zeroing objects, getting
their storage size. Instead, new functions:
zero_sized_lisp_object()
zero_nonsized_lisp_object()
lisp_object_storage_size()
free_normal_lisp_object()
(copy_lisp_object() already exists)
LISP_OBJECT_FROB_BLOCK_P() (actually a macro)
Eliminated:
free_lrecord()
zero_lrecord()
copy_lrecord()
copy_sized_lrecord()
old_copy_lcrecord()
old_copy_sized_lcrecord()
old_zero_lcrecord()
old_zero_sized_lcrecord()
LISP_OBJECT_STORAGE_SIZE()
COPY_SIZED_LISP_OBJECT()
COPY_SIZED_LCRECORD()
COPY_LISP_OBJECT()
ZERO_LISP_OBJECT()
FREE_LISP_OBJECT()
(4) Catch the remaining places where lrecord stuff was used directly
and use the advertised interface, e.g. alloc_sized_lrecord() ->
ALLOC_SIZED_LISP_OBJECT().
(5) Make certain statically-declared pseudo-objects
(buffer_local_flags, console_local_flags) have their lheader
initialized correctly, so things like copy_lisp_object() can work
on them. Make extent_auxiliary_defaults a proper heap object
Vextent_auxiliary_defaults, and make extent auxiliaries dumpable
so that this object can be dumped. allocate_extent_auxiliary()
now just creates the object, and attach_extent_auxiliary()
creates an extent auxiliary and attaches to an extent, like the
old allocate_extent_auxiliary().
(6) Create EXTENT_AUXILIARY_SLOTS macro, similar to the foo-slots.h
files but in a macro instead of a file. The purpose is to avoid
duplication when iterating over all the slots in an extent auxiliary.
Use it.
(7) In lstream.c, don't zero out object after allocation because
allocation routines take care of this.
(8) In marker.c, fix a mistake in computing marker overhead.
(9) In print.c, clean up printing_unreadable_lcrecord(),
external_object_printer() to avoid lots of ifdef NEW_GC's.
(10) Separate toolbar-button allocation into a separate
allocate_toolbar_button() function for use in the example code
in lrecord.h.
| author | Ben Wing <ben@xemacs.org> |
|---|---|
| date | Fri, 05 Mar 2010 04:08:17 -0600 |
| parents | d4f666cda5e6 |
| children | 7be849cb8828 |
comparison
equal
deleted
inserted
replaced
| 5126:2a462149bd6a | 5127:a9c41067dd88 |
|---|---|
| 7750 characters. No special allocation or garbage collection is necessary | 7750 characters. No special allocation or garbage collection is necessary |
| 7751 for such objects. Lisp objects of these types do not need to be | 7751 for such objects. Lisp objects of these types do not need to be |
| 7752 @code{GCPRO}ed. | 7752 @code{GCPRO}ed. |
| 7753 @end itemize | 7753 @end itemize |
| 7754 | 7754 |
| 7755 In the remaining two categories, the type is stored in the object | 7755 In the remaining two categories, the type is stored in the object |
| 7756 itself. The tag for all such objects is the generic @dfn{lrecord} | 7756 itself. The tag for all such objects is the generic @dfn{lrecord} |
| 7757 (Lisp_Type_Record) tag. The first bytes of the object's structure are an | 7757 (Lisp_Type_Record) tag. The first bytes of the object's structure are an |
| 7758 integer (actually a char) characterising the object's type and some | 7758 integer (actually a char) characterising the object's type and some |
| 7759 flags, in particular the mark bit used for garbage collection. A | 7759 flags, in particular the mark bit used for garbage collection. A |
| 7760 structure describing the type is accessible thru the | 7760 structure describing the type is accessible thru the |
| 8486 @node Integers and Characters, Allocation from Frob Blocks, Garbage Collection - Step by Step, Allocation of Objects in XEmacs Lisp | 8486 @node Integers and Characters, Allocation from Frob Blocks, Garbage Collection - Step by Step, Allocation of Objects in XEmacs Lisp |
| 8487 @section Integers and Characters | 8487 @section Integers and Characters |
| 8488 @cindex integers and characters | 8488 @cindex integers and characters |
| 8489 @cindex characters, integers and | 8489 @cindex characters, integers and |
| 8490 | 8490 |
| 8491 Integer and character Lisp objects are created from integers using the | 8491 Integer and character Lisp objects are created from integers using the |
| 8492 macros @code{XSETINT()} and @code{XSETCHAR()} or the equivalent | |
| 8493 functions @code{make_int()} and @code{make_char()}. (These are actually | 8492 functions @code{make_int()} and @code{make_char()}. (These are actually |
| 8494 macros on most systems.) These functions basically just do some moving | 8493 macros on most systems.) These functions basically just do some moving |
| 8495 of bits around, since the integral value of the object is stored | 8494 of bits around, since the integral value of the object is stored |
| 8496 directly in the @code{Lisp_Object}. | 8495 directly in the @code{Lisp_Object}. |
| 8497 | 8496 |
| 8498 @code{XSETINT()} and the like will truncate values given to them that | |
| 8499 are too big; i.e. you won't get the value you expected but the tag bits | |
| 8500 will at least be correct. | |
| 8501 | |
| 8502 @node Allocation from Frob Blocks, lrecords, Integers and Characters, Allocation of Objects in XEmacs Lisp | 8497 @node Allocation from Frob Blocks, lrecords, Integers and Characters, Allocation of Objects in XEmacs Lisp |
| 8503 @section Allocation from Frob Blocks | 8498 @section Allocation from Frob Blocks |
| 8504 @cindex allocation from frob blocks | 8499 @cindex allocation from frob blocks |
| 8505 @cindex frob blocks, allocation from | 8500 @cindex frob blocks, allocation from |
| 8506 | 8501 |
| 8507 The uninitialized memory required by a @code{Lisp_Object} of a particular type | 8502 The uninitialized memory required by a @code{Lisp_Object} of a |
| 8508 is allocated using | 8503 particular type is allocated using @code{ALLOCATE_FIXED_TYPE()}. This |
| 8509 @code{ALLOCATE_FIXED_TYPE()}. This only occurs inside of the | 8504 only occurs inside of the lowest-level object-creating functions in |
| 8510 lowest-level object-creating functions in @file{alloc.c}: | 8505 @file{alloc.c}: @code{Fcons()}, @code{make_float()}, |
| 8511 @code{Fcons()}, @code{make_float()}, @code{Fmake_byte_code()}, | 8506 @code{Fmake_byte_code()}, @code{Fmake_symbol()}, |
| 8512 @code{Fmake_symbol()}, @code{allocate_extent()}, | 8507 @code{allocate_extent()}, @code{allocate_event()}, |
| 8513 @code{allocate_event()}, @code{Fmake_marker()}, and | 8508 @code{Fmake_marker()}, and @code{make_uninit_string()}. The idea is |
| 8514 @code{make_uninit_string()}. The idea is that, for each type, there are | 8509 that, for each type, there are a number of frob blocks (each 2K in |
| 8515 a number of frob blocks (each 2K in size); each frob block is divided up | 8510 size); each frob block is divided up into object-sized chunks. Each |
| 8516 into object-sized chunks. Each frob block will have some of these | 8511 frob block will have some of these chunks that are currently assigned |
| 8517 chunks that are currently assigned to objects, and perhaps some that are | 8512 to objects, and perhaps some that are free. (If a frob block has |
| 8518 free. (If a frob block has nothing but free chunks, it is freed at the | 8513 nothing but free chunks, it is freed at the end of the garbage |
| 8519 end of the garbage collection cycle.) The free chunks are stored in a | 8514 collection cycle.) The free chunks are stored in a free list, which |
| 8520 free list, which is chained by storing a pointer in the first four bytes | 8515 is chained by storing a pointer in the first four bytes of the |
| 8521 of the chunk. (Except for the free chunks at the end of the last frob | 8516 chunk. (Except for the free chunks at the end of the last frob block, |
| 8522 block, which are handled using an index which points past the end of the | 8517 which are handled using an index which points past the end of the |
| 8523 last-allocated chunk in the last frob block.) | 8518 last-allocated chunk in the last frob block.) |
| 8524 @code{ALLOCATE_FIXED_TYPE()} first tries to retrieve a chunk from the | 8519 @code{ALLOCATE_FIXED_TYPE()} first tries to retrieve a chunk from the |
| 8525 free list; if that fails, it calls | 8520 free list; if that fails, it calls |
| 8526 @code{ALLOCATE_FIXED_TYPE_FROM_BLOCK()}, which looks at the end of the | 8521 @code{ALLOCATE_FIXED_TYPE_FROM_BLOCK()}, which looks at the end of the |
| 8527 last frob block for space, and creates a new frob block if there is | 8522 last frob block for space, and creates a new frob block if there is |
| 8528 none. (There are actually two versions of these macros, one of which is | 8523 none. (There are actually two versions of these macros, one of which |
| 8529 more defensive but less efficient and is used for error-checking.) | 8524 is more defensive but less efficient and is used for error-checking.) |
| 8530 | 8525 |
| 8531 @node lrecords, Low-level allocation, Allocation from Frob Blocks, Allocation of Objects in XEmacs Lisp | 8526 @node lrecords, Low-level allocation, Allocation from Frob Blocks, Allocation of Objects in XEmacs Lisp |
| 8532 @section lrecords | 8527 @section lrecords |
| 8533 @cindex lrecords | 8528 @cindex lrecords |
| 8534 | 8529 |
| 8535 [see @file{lrecord.h}] | 8530 [see @file{lrecord.h}] |
| 8536 | 8531 |
| 8537 @strong{This node needs updating for the ``new garbage collection | 8532 @strong{This node needs updating for the ``new garbage collection |
| 8538 algorithms'' (KKCC) and the ``incremental'' collector.} | 8533 algorithms'' (KKCC) and the ``incremental'' collector.} |
| 8539 | 8534 |
| 8540 All lrecords have at the beginning of their structure a @code{struct | 8535 All lrecords have at the beginning of their structure a @code{struct |
| 8541 lrecord_header}. This just contains a type number and some flags, | 8536 lrecord_header}. This just contains a type number and some flags, |
| 8542 including the mark bit. All builtin type numbers are defined as | 8537 including the mark bit. All builtin type numbers are defined as |
| 8543 constants in @code{enum lrecord_type}, to allow the compiler to generate | 8538 constants in @code{enum lrecord_type}, to allow the compiler to generate |
| 8544 more efficient code for @code{@var{type}P}. The type number, thru the | 8539 more efficient code for @code{@var{type}P}. The type number, thru the |
| 8545 @code{lrecord_implementation_table}, gives access to a @code{struct | 8540 @code{lrecord_implementation_table}, gives access to a @code{struct |
| 8546 lrecord_implementation}, which is a structure containing method pointers | 8541 lrecord_implementation}, which is a structure containing method pointers |
| 8547 and such. There is one of these for each type, and it is a global, | 8542 and such. There is one of these for each type, and it is a global, |
| 8548 constant, statically-declared structure that is declared in the | 8543 constant, statically-declared structure that is declared in the |
| 8549 @code{DEFINE_LRECORD_IMPLEMENTATION()} macro. | 8544 @code{DEFINE_*_LISP_OBJECT()} macro. |
| 8550 | 8545 |
| 8551 Simple lrecords (of type (b) above) just have a @code{struct | 8546 Frob-block lrecords just have a @code{struct lrecord_header} at their |
| 8552 lrecord_header} at their beginning. lcrecords, however, actually have a | 8547 beginning. lcrecords, however, actually have a |
| 8553 @code{struct lcrecord_header}. This, in turn, has a @code{struct | 8548 @code{struct old_lcrecord_header}. This, in turn, has a @code{struct |
| 8554 lrecord_header} at its beginning, so sanity is preserved; but it also | 8549 lrecord_header} at its beginning, so sanity is preserved; but it also |
| 8555 has a pointer used to chain all lcrecords together, and a special ID | 8550 has a pointer used to chain all lcrecords together, and a special ID |
| 8556 field used to distinguish one lcrecord from another. (This field is used | 8551 field used to distinguish one lcrecord from another. (This field is used |
| 8557 only for debugging and could be removed, but the space gain is not | 8552 only for debugging and could be removed, but the space gain is not |
| 8558 significant.) | 8553 significant.) |
| 8559 | 8554 |
| 8560 @strong{lcrecords are now obsolete when using the write-barrier-based | 8555 @strong{lcrecords are now obsolete when using the write-barrier-based |
| 8561 collector.} | 8556 collector.} |
| 8562 | 8557 |
| 8563 Simple lrecords are created using @code{ALLOCATE_FIXED_TYPE()}, just | 8558 Frob-block objects are created using @code{ALLOC_FROB_BLOCK_LISP_OBJECT()}. |
| 8564 like for other frob blocks. The only change is that the implementation | 8559 All this does is call @code{ALLOCATE_FIXED_TYPE()} to allocate an |
| 8565 pointer must be initialized correctly. (The implementation structure for | 8560 object, and @code{set_lheader_implementation()} to initialize the header. |
| 8566 an lrecord, or rather the pointer to it, is named @code{lrecord_float}, | 8561 |
| 8567 @code{lrecord_extent}, @code{lrecord_buffer}, etc.) | 8562 Normal objects (i.e. lcrecords) are created using |
| 8568 | 8563 @code{ALLOC_NORMAL_LISP_OBJECT()}, which takes a type name (resolved |
| 8569 lcrecords are created using @code{alloc_lcrecord()}. This takes a | 8564 internally to a structure named @code{lrecord_foo} for type |
| 8570 size to allocate and an implementation pointer. (The size needs to be | 8565 @code{foo}). If they are of variable size, however, they are created |
| 8571 passed because some lcrecords, such as window configurations, are of | 8566 with @code{ALLOC_SIZED_LISP_OBJECT()}, which takes a size to allocate |
| 8572 variable size.) This basically just @code{malloc()}s the storage, | 8567 in addition to a type. This basically just @code{malloc()}s the |
| 8573 initializes the @code{struct lcrecord_header}, and chains the lcrecord | 8568 storage, initializes the @code{struct lcrecord_header}, and chains the |
| 8574 onto the head of the list of all lcrecords, which is stored in the | 8569 lcrecord onto the head of the list of all lcrecords, which is stored |
| 8575 variable @code{all_lcrecords}. The calls to @code{alloc_lcrecord()} | 8570 in the variable @code{all_lcrecords}. The calls to the above |
| 8576 generally occur in the lowest-level allocation function for each lrecord | 8571 allocation macros generally occur in the lowest-level allocation |
| 8577 type. | 8572 function for each lrecord type. |
| 8578 | 8573 |
| 8579 Whenever you create an lrecord, you need to call either | 8574 Whenever you create a normal object, you need to call one of the |
| 8580 @code{DEFINE_LRECORD_IMPLEMENTATION()} or | 8575 @code{DEFINE_*_LISP_OBJECT()} macros. This needs to be |
| 8581 @code{DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION()}. This needs to be | |
| 8582 specified in a @file{.c} file, at the top level. What this actually | 8576 specified in a @file{.c} file, at the top level. What this actually |
| 8583 does is define and initialize the implementation structure for the | 8577 does is define and initialize the implementation structure for the |
| 8584 lrecord. (And possibly declares a function @code{error_check_foo()} that | 8578 lrecord. (And possibly declares a function @code{error_check_foo()} that |
| 8585 implements the @code{XFOO()} macro when error-checking is enabled.) The | 8579 implements the @code{XFOO()} macro when error-checking is enabled.) The |
| 8586 arguments to the macros are the actual type name (this is used to | 8580 arguments to the macros are the actual type name (this is used to |
| 8593 are used to encapsulate type-specific information about the object, such | 8587 are used to encapsulate type-specific information about the object, such |
| 8594 as how to print it or mark it for garbage collection, so that it's easy | 8588 as how to print it or mark it for garbage collection, so that it's easy |
| 8595 to add new object types without having to add a specific case for each | 8589 to add new object types without having to add a specific case for each |
| 8596 new type in a bunch of different places. | 8590 new type in a bunch of different places. |
| 8597 | 8591 |
| 8598 The difference between @code{DEFINE_LRECORD_IMPLEMENTATION()} and | 8592 The various macros for defining Lisp objects are as follows: |
| 8599 @code{DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION()} is that the former is | 8593 |
| 8600 used for fixed-size object types and the latter is for variable-size | 8594 @itemize @bullet |
| 8601 object types. Most object types are fixed-size; some complex | 8595 @item |
| 8602 types, however (e.g. window configurations), are variable-size. | 8596 @code{DEFINE_*_LISP_OBJECT} is for objects with constant size. (Either |
| 8603 Variable-size object types have an extra method, which is called | 8597 @code{DEFINE_DUMPABLE_LISP_OBJECT} for objects that can be saved in a |
| 8604 to determine the actual size of a particular object of that type. | 8598 dumped executable, or @code{DEFINE_NODUMP_LISP_OBJECT} for objects |
| 8605 (Currently this is only used for keeping allocation statistics.) | 8599 that cannot be saved -- e.g. that contain pointers to non-persistent |
| 8606 | 8600 external objects such as window-system windows.) |
| 8607 For the purpose of keeping allocation statistics, the allocation | 8601 |
| 8602 @item | |
| 8603 @code{DEFINE_*_SIZABLE_LISP_OBJECT} is for objects whose size varies. | |
| 8604 This includes some simple types such as vectors, bit vectors and | |
| 8605 opaque objects, as well complex types, especially types such as | |
| 8606 specifiers, lstreams or coding systems that have subtypes and include | |
| 8607 subtype-specific data attached to the end of the structure. | |
| 8608 Variable-size objects have an extra method that returns the size of | |
| 8609 the object. This is not used at allocation (rather, the size is | |
| 8610 specified in the call to the allocation macro), but is used for | |
| 8611 operations such as copying a Lisp object, as well as for keeping | |
| 8612 allocation statistics. | |
| 8613 | |
| 8614 @item | |
| 8615 @code{DEFINE_*_FROB_BLOCK_LISP_OBJECT} is for objects that are | |
| 8616 allocated in large blocks (``frob blocks''), which are parceled up | |
| 8617 individually. Such objects need special handling in @file{alloc.c}. | |
| 8618 This does not apply to NEW_GC, because it does this automatically. | |
| 8619 | |
| 8620 @item | |
| 8621 @code{DEFINE_*_INTERNAL_LISP_OBJECT} is for ``internal'' objects that | |
| 8622 should never be visible on the Lisp level. This is a shorthand for | |
| 8623 the most common type of internal objects, which have no equal or hash | |
| 8624 method (since they generally won't appear in hash tables), no | |
| 8625 finalizer and @code{internal_object_printer()} as their print method | |
| 8626 (which prints that the object is internal and shouldn't be visible | |
| 8627 externally). For internal objects needing a finalizer, equal or hash | |
| 8628 method, or wanting to customize the print method, use the normal | |
| 8629 @code{DEFINE_*_LISP_OBJECT} mechanism for defining these objects. | |
| 8630 | |
| 8631 @item | |
| 8632 @code{DEFINE_*_GENERAL_LISP_OBJECT} is for objects that need to | |
| 8633 provide one of the less common methods that are omitted on most | |
| 8634 objects. These methods include the methods supporting the unified | |
| 8635 property interface using @code{get}, @code{put}, @code{remprop} and | |
| 8636 @code{object-plist}, and (for dumpable objects only) the | |
| 8637 @code{disksaver} method. | |
| 8638 | |
| 8639 @item | |
| 8640 @code{DEFINE_MODULE_*} is for objects defined in an external module. | |
| 8641 @end itemize | |
| 8642 | |
| 8643 @code{MAKE_LISP_OBJECT} and @code{MAKE_MODULE_LISP_OBJECT} are what | |
| 8644 underlies all of these; they define a structure containing pointers to | |
| 8645 object methods and other info such as the size of the structure | |
| 8646 containing the object. | |
| 8647 | |
| 8648 For the purpose of keeping allocation statistics, the allocation | |
| 8608 engine keeps a list of all the different types that exist. Note that, | 8649 engine keeps a list of all the different types that exist. Note that, |
| 8609 since @code{DEFINE_LRECORD_IMPLEMENTATION()} is a macro that is | 8650 since @code{DEFINE_*_LISP_OBJECT()} is a macro that is |
| 8610 specified at top-level, there is no way for it to initialize the global | 8651 specified at top-level, there is no way for it to initialize the |
| 8611 data structures containing type information, like | 8652 global data structures containing type information, like |
| 8612 @code{lrecord_implementations_table}. For this reason a call to | 8653 @code{lrecord_implementations_table}. For this reason a call to |
| 8613 @code{INIT_LRECORD_IMPLEMENTATION} must be added to the same source file | 8654 @code{INIT_LISP_OBJECT()} must be added to the same source |
| 8614 containing @code{DEFINE_LRECORD_IMPLEMENTATION}, but instead of to the | 8655 file containing @code{DEFINE_*_LISP_OBJECT()}, but instead of |
| 8615 top level, to one of the init functions, typically | 8656 to the top level, to one of the init functions, typically |
| 8616 @code{syms_of_@var{foo}.c}. @code{INIT_LRECORD_IMPLEMENTATION} must be | 8657 @code{syms_of_@var{foo}.c}. @code{INIT_LISP_OBJECT()} must |
| 8617 called before an object of this type is used. | 8658 be called before an object of this type is used. |
| 8618 | 8659 |
| 8619 The type number is also used to index into an array holding the number | 8660 The type number is also used to index into an array holding the number |
| 8620 of objects of each type and the total memory allocated for objects of | 8661 of objects of each type and the total memory allocated for objects of |
| 8621 that type. The statistics in this array are computed during the sweep | 8662 that type. The statistics in this array are computed during the sweep |
| 8622 stage. These statistics are returned by the call to | 8663 stage. These statistics are returned by the call to |
| 8623 @code{garbage-collect}. | 8664 @code{garbage-collect}. |
| 8624 | 8665 |
| 8625 Note that for every type defined with a @code{DEFINE_LRECORD_*()} | 8666 Note that for every type defined with a @code{DEFINE_*_LISP_OBJECT()} |
| 8626 macro, there needs to be a @code{DECLARE_LRECORD_IMPLEMENTATION()} | 8667 macro, there needs to be a @code{DECLARE_LISP_OBJECT()} somewhere in a |
| 8627 somewhere in a @file{.h} file, and this @file{.h} file needs to be | 8668 @file{.h} file, and this @file{.h} file needs to be included by |
| 8628 included by @file{inline.c}. | 8669 @file{inline.c}. |
| 8629 | 8670 |
| 8630 Furthermore, there should generally be a set of @code{XFOOBAR()}, | 8671 Furthermore, there should generally be a set of @code{XFOOBAR()}, |
| 8631 @code{FOOBARP()}, etc. macros in a @file{.h} (or occasionally @file{.c}) | 8672 @code{FOOBARP()}, etc. macros in a @file{.h} (or occasionally |
| 8632 file. To create one of these, copy an existing model and modify as | 8673 @file{.c}) file. To create one of these, copy an existing model and |
| 8633 necessary. | 8674 modify as necessary. |
| 8634 | 8675 |
| 8635 @strong{Please note:} If you define an lrecord in an external | 8676 @strong{Please note:} If you define an lrecord in an external |
| 8636 dynamically-loaded module, you must use @code{DECLARE_EXTERNAL_LRECORD}, | 8677 dynamically-loaded module, you must use |
| 8637 @code{DEFINE_EXTERNAL_LRECORD_IMPLEMENTATION}, and | 8678 @code{DECLARE_MODULE_LISP_OBJECT()}, |
| 8638 @code{DEFINE_EXTERNAL_LRECORD_SEQUENCE_IMPLEMENTATION} instead of the | 8679 @code{DEFINE_MODULE_*_LISP_OBJECT()}, and |
| 8639 non-EXTERNAL forms. These macros will dynamically add new type numbers | 8680 @code{INIT_MODULE_LISP_OBJECT()} instead of the non-MODULE |
| 8640 to the global enum that records them, whereas the non-EXTERNAL forms | 8681 forms. These macros will dynamically add new type numbers to the |
| 8641 assume that the programmer has already inserted the correct type numbers | 8682 global enum that records them, whereas the non-MODULE forms assume |
| 8642 into the enum's code at compile-time. | 8683 that the programmer has already inserted the correct type numbers into |
| 8684 the enum's code at compile-time. | |
| 8643 | 8685 |
| 8644 The various methods in the lrecord implementation structure are: | 8686 The various methods in the lrecord implementation structure are: |
| 8645 | 8687 |
| 8646 @enumerate | 8688 @enumerate |
| 8647 @item | 8689 @item |
| 8701 operating-system and window-system resources associated with the object | 8743 operating-system and window-system resources associated with the object |
| 8702 (e.g. pixmaps, fonts), etc. | 8744 (e.g. pixmaps, fonts), etc. |
| 8703 | 8745 |
| 8704 The finalize method can be NULL if nothing needs to be done. | 8746 The finalize method can be NULL if nothing needs to be done. |
| 8705 | 8747 |
| 8706 WARNING #1: The finalize method is also called at the end of the dump | |
| 8707 phase; this time with the for_disksave parameter set to non-zero. The | |
| 8708 object is @emph{not} about to disappear, so you have to make sure to | |
| 8709 @emph{not} free any extra @code{malloc()}ed memory if you're going to | |
| 8710 need it later. (Also, signal an error if there are any operating-system | |
| 8711 and window-system resources here, because they can't be dumped.) | |
| 8712 | |
| 8713 Finalize methods should, as a rule, set to zero any pointers after | 8748 Finalize methods should, as a rule, set to zero any pointers after |
| 8714 they've been freed, and check to make sure pointers are not zero before | 8749 they've been freed, and check to make sure pointers are not zero |
| 8715 freeing. Although I'm pretty sure that finalize methods are not called | 8750 before freeing. Although I'm pretty sure that finalize methods are |
| 8716 twice on the same object (except for the @code{for_disksave} proviso), | 8751 not called twice on the same object, we've gotten nastily burned in |
| 8717 we've gotten nastily burned in some cases by not doing this. | 8752 some cases by not doing this. |
| 8718 | 8753 |
| 8719 WARNING #2: The finalize method is @emph{only} called for | 8754 WARNING #1: The finalize method is @emph{only} called for |
| 8720 lcrecords, @emph{not} for simply lrecords. If you need a | 8755 normal objects, @emph{not} for frob-block objects. If you need a |
| 8721 finalize method for simple lrecords, you have to stick | 8756 finalize method for frob-block objects, you have to stick |
| 8722 it in the @code{ADDITIONAL_FREE_foo()} macro in @file{alloc.c}. | 8757 it in the @code{ADDITIONAL_FREE_foo()} macro in @file{alloc.c}. |
| 8723 | 8758 |
| 8724 WARNING #3: Things are in an @emph{extremely} bizarre state | 8759 WARNING #2: Things are in an @emph{extremely} bizarre state |
| 8725 when @code{ADDITIONAL_FREE_foo()} is called, so you have to | 8760 when @code{ADDITIONAL_FREE_foo()} is called, so you have to |
| 8726 be incredibly careful when writing one of these functions. | 8761 be incredibly careful when writing one of these functions. |
| 8727 See the comment in @code{gc_sweep()}. If you ever have to add | 8762 See the comment in @code{gc_sweep()}. If you ever have to add |
| 8728 one of these, consider using an lcrecord or dealing with | 8763 one of these, consider using an lcrecord or dealing with |
| 8729 the problem in a different fashion. | 8764 the problem in a different fashion. |
| 8759 To hash two or more values together into a single value, use | 8794 To hash two or more values together into a single value, use |
| 8760 @code{HASH2()}, @code{HASH3()}, @code{HASH4()}, etc. | 8795 @code{HASH2()}, @code{HASH3()}, @code{HASH4()}, etc. |
| 8761 | 8796 |
| 8762 @item | 8797 @item |
| 8763 @dfn{getprop}, @dfn{putprop}, @dfn{remprop}, and @dfn{plist} methods. | 8798 @dfn{getprop}, @dfn{putprop}, @dfn{remprop}, and @dfn{plist} methods. |
| 8764 These are used for object types that have properties. I don't feel like | 8799 These are used for object types that have properties, and are called |
| 8765 documenting them here. If you create one of these objects, you have to | 8800 when @code{get}, @code{put}, @code{remprop}, and @code{object-plist}, |
| 8766 use different macros to define them, | 8801 respectively are called on the object. If you create one of these |
| 8767 i.e. @code{DEFINE_LRECORD_IMPLEMENTATION_WITH_PROPS()} or | 8802 objects, you have to use a different macro to define them, |
| 8768 @code{DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION_WITH_PROPS()}. | 8803 i.e. @code{DEFINE_*_GENERAL_LISP_OBJECT()}. |
| 8769 | 8804 |
| 8770 @item | 8805 @item |
| 8771 A @dfn{size_in_bytes} method, when the object is of variable-size. | 8806 A @dfn{size_in_bytes} method, when the object is of variable-size. |
| 8772 (i.e. declared with a @code{_SEQUENCE_IMPLEMENTATION} macro.) This should | 8807 (i.e. declared with a @code{DEFINE_*_SIZABLE_*_LISP_OBJECT} macro.) |
| 8773 simply return the object's size in bytes, exactly as you might expect. | 8808 This should simply return the object's size in bytes, exactly as you |
| 8774 For an example, see the methods for window configurations and opaques. | 8809 might expect. For an example, see the methods for lstreams and opaques. |
| 8810 | |
| 8811 @item | |
| 8812 A @dfn{disksave} method. This is called at the end of the dump phase. | |
| 8813 It is used for objects that contain pointers or handles to objects | |
| 8814 created in external libraries, such as window-system windows or file | |
| 8815 handles. Such external objects cannot be dumped, so it is necessary | |
| 8816 to release them at dump time and arrange somehow or other for them to | |
| 8817 be resurrected if necessary later on. | |
| 8818 | |
| 8819 It seems that even non-dumpable objects may be around at dump time, | |
| 8820 and a disksaver may be provided. (In fact, the only object currently | |
| 8821 with a disksaver, lstream, is non-dumpable.) | |
| 8822 | |
| 8823 Objects rarely need to provide this method; most of the time it will | |
| 8824 be NULL. If you want to provide this method, you have to use the | |
| 8825 @code{DEFINE_*_GENERAL_LISP_OBJECT()} macro to define your object. | |
| 8775 @end enumerate | 8826 @end enumerate |
| 8776 | 8827 |
| 8777 @node Low-level allocation, Cons, lrecords, Allocation of Objects in XEmacs Lisp | 8828 @node Low-level allocation, Cons, lrecords, Allocation of Objects in XEmacs Lisp |
| 8778 @section Low-level allocation | 8829 @section Low-level allocation |
| 8779 @cindex low-level allocation | 8830 @cindex low-level allocation |