Mercurial > hg > xemacs-beta
annotate src/lstream.h @ 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 | d1247f3cc363 |
| children | 308d34e9f07d |
| rev | line source |
|---|---|
| 428 | 1 /* Generic stream implementation -- header file. |
| 2 Copyright (C) 1995 Free Software Foundation, Inc. | |
| 788 | 3 Copyright (C) 1996, 2001, 2002 Ben Wing. |
| 428 | 4 |
| 5 This file is part of XEmacs. | |
| 6 | |
| 7 XEmacs is free software; you can redistribute it and/or modify it | |
| 8 under the terms of the GNU General Public License as published by the | |
| 9 Free Software Foundation; either version 2, or (at your option) any | |
| 10 later version. | |
| 11 | |
| 12 XEmacs is distributed in the hope that it will be useful, but WITHOUT | |
| 13 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| 14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| 15 for more details. | |
| 16 | |
| 17 You should have received a copy of the GNU General Public License | |
| 18 along with XEmacs; see the file COPYING. If not, write to | |
| 19 the Free Software Foundation, Inc., 59 Temple Place - Suite 330, | |
| 20 Boston, MA 02111-1307, USA. */ | |
| 21 | |
| 22 /* Synched up with: Not in FSF. */ | |
| 23 | |
| 24 /* Written by Ben Wing. */ | |
| 25 | |
| 440 | 26 #ifndef INCLUDED_lstream_h_ |
| 27 #define INCLUDED_lstream_h_ | |
| 428 | 28 |
| 29 /************************************************************************/ | |
| 30 /* definition of Lstream object */ | |
| 31 /************************************************************************/ | |
| 32 | |
|
5118
e0db3c197671
merge up to latest default branch, doesn't compile yet
Ben Wing <ben@xemacs.org>
parents:
3017
diff
changeset
|
33 DECLARE_LISP_OBJECT (lstream, struct lstream); |
| 428 | 34 #define XLSTREAM(x) XRECORD (x, lstream, struct lstream) |
| 617 | 35 #define wrap_lstream(p) wrap_record (p, lstream) |
| 428 | 36 #define LSTREAMP(x) RECORDP (x, lstream) |
| 37 /* #define CHECK_LSTREAM(x) CHECK_RECORD (x, lstream) | |
| 38 Lstream pointers should never escape to the Lisp level, so | |
| 39 functions should not be doing this. */ | |
| 40 | |
| 41 #ifndef EOF | |
| 42 #define EOF (-1) | |
| 43 #endif | |
| 44 | |
| 771 | 45 /* There have been some arguments over the what the type should be that |
| 665 | 46 specifies a count of bytes in a data block to be written out or read in, |
| 47 using Lstream_read(), Lstream_write(), and related functions. | |
| 48 Originally it was long, which worked fine; Martin "corrected" these to | |
| 49 size_t and ssize_t on the grounds that this is theoretically cleaner and | |
| 50 is in keeping with the C standards. Unfortunately, this practice is | |
| 51 horribly error-prone due to design flaws in the way that mixed | |
| 52 signed/unsigned arithmetic happens. In fact, by doing this change, | |
| 53 Martin introduced a subtle but fatal error that caused the operation of | |
| 54 sending large mail messages to the SMTP server under Windows to fail. | |
| 55 By putting all values back to be signed, avoiding any signed/unsigned | |
| 56 mixing, the bug immediately went away. The type then in use was | |
| 57 Lstream_Data_Count, so that it be reverted cleanly if a vote came to | |
| 58 that. Now it is Bytecount. | |
| 59 | |
| 60 Some earlier comments about why the type must be signed: This MUST BE | |
| 61 SIGNED, since it also is used in functions that return the number of | |
| 62 bytes actually read to or written from in an operation, and these | |
| 63 functions can return -1 to signal error. | |
| 462 | 64 |
| 65 Note that the standard Unix read() and write() functions define the | |
| 66 count going in as a size_t, which is UNSIGNED, and the count going | |
| 67 out as an ssize_t, which is SIGNED. This is a horrible design | |
| 68 flaw. Not only is it highly likely to lead to logic errors when a | |
| 69 -1 gets interpreted as a large positive number, but operations are | |
| 70 bound to fail in all sorts of horrible ways when a number in the | |
| 71 upper-half of the size_t range is passed in -- this number is | |
| 72 unrepresentable as an ssize_t, so code that checks to see how many | |
| 73 bytes are actually written (which is mandatory if you are dealing | |
| 74 with certain types of devices) will get completely screwed up. | |
| 771 | 75 |
| 665 | 76 --ben |
| 462 | 77 */ |
| 428 | 78 typedef enum lstream_buffering |
| 79 { | |
| 80 /* No buffering. */ | |
| 81 LSTREAM_UNBUFFERED, | |
| 82 /* Buffer until a '\n' character is reached. */ | |
| 83 LSTREAM_LINE_BUFFERED, | |
| 84 /* Buffer in standard-size (i.e. 512-byte) blocks. */ | |
| 85 LSTREAM_BLOCK_BUFFERED, | |
| 86 /* Buffer in blocks of a specified size. */ | |
| 87 LSTREAM_BLOCKN_BUFFERED, | |
| 88 /* Buffer until the stream is closed (only applies to write-only | |
| 89 streams). Only one call to the stream writer will be made, | |
| 90 and that is when the stream is closed. */ | |
| 91 LSTREAM_UNLIMITED | |
| 92 } Lstream_buffering; | |
| 93 | |
| 771 | 94 #if 0 |
| 95 | |
| 96 /* #### not currently implemented; correct EOF handling is quite tricky | |
| 97 in the presence of various levels of filtering streams, and simply | |
| 98 interpreting 0 as EOF works fairly well as long as the amount of | |
| 99 data you're attempting to read is large and you know whether the | |
| 100 source stream at the end of the chain is a pipe (or other blocking | |
| 101 source) or not. we really should fix this, though. */ | |
| 102 | |
| 103 /* Return values from Lstream_read(). We do NOT use the C lib trick | |
| 104 of returning 0 to maybe indicate EOF because that is simply too | |
| 105 random and error-prone. It is quite legitimate for there to be no | |
| 106 data available but no EOF, even when not in the presence of | |
| 107 non-blocking I/O. For example, decoding/encoding streams (and in | |
| 108 general, any type of filtering stream) may only be able to return | |
| 109 data after a certain amount of data on the other end is | |
| 110 available. */ | |
| 111 | |
| 112 #define LSTREAM_EOF -2 | |
| 113 | |
| 114 #endif /* 0 */ | |
| 115 | |
| 116 #define LSTREAM_ERROR -1 | |
| 117 | |
| 428 | 118 /* Methods defining how this stream works. Some may be undefined. */ |
| 119 | |
| 120 /* We do not implement the seek/tell paradigm. I tried to do that, | |
| 121 but getting the semantics right in the presence of buffering is | |
| 122 extremely tricky and very error-prone and basically not worth it. | |
| 123 This is especially the case with complicated streams like | |
| 124 decoding streams -- the seek pointer in this case can't be a single | |
| 125 integer but has to be a whole complicated structure that records | |
| 126 all of the stream's state at the time. | |
| 127 | |
| 128 Rewind semantics are generally easy to implement, so we do provide | |
| 129 a rewind method. Even rewind() may not be available on a stream, | |
| 130 however -- e.g. on process output. */ | |
| 131 | |
| 132 typedef struct lstream_implementation | |
| 133 { | |
| 442 | 134 const char *name; |
| 665 | 135 Bytecount size; /* Number of additional bytes to be |
| 814 | 136 allocated with this stream. Access this |
| 137 data using Lstream_data(). */ | |
| 1204 | 138 |
| 139 /* Description of the extra data (struct foo_lstream) attached to a | |
| 140 coding system. */ | |
| 141 const struct sized_memory_description *extra_description; | |
| 142 | |
| 428 | 143 /* Read some data from the stream's end and store it into DATA, which |
| 144 can hold SIZE bytes. Return the number of bytes read. A return | |
| 145 value of 0 means no bytes can be read at this time. This may | |
| 146 be because of an EOF, or because there is a granularity greater | |
| 147 than one byte that the stream imposes on the returned data, and | |
| 148 SIZE is less than this granularity. (This will happen frequently | |
| 149 for streams that need to return whole characters, because | |
| 150 Lstream_read() calls the reader function repeatedly until it | |
| 151 has the number of bytes it wants or until 0 is returned.) | |
| 152 The lstream functions do not treat a 0 return as EOF or do | |
| 153 anything special; however, the calling function will interpret | |
| 154 any 0 it gets back as EOF. This will normally not happen unless | |
| 155 the caller calls Lstream_read() with a very small size. | |
| 156 | |
| 157 This function can be NULL if the stream is output-only. */ | |
| 442 | 158 /* The omniscient mly, blinded by the irresistible thrall of Common |
| 428 | 159 Lisp, thinks that it is bogus that the types and implementations |
| 160 of input and output streams are the same. */ | |
| 665 | 161 Bytecount (*reader) (Lstream *stream, unsigned char *data, |
| 814 | 162 Bytecount size); |
| 428 | 163 /* Send some data to the stream's end. Data to be sent is in DATA |
| 164 and is SIZE bytes. Return the number of bytes sent. This | |
| 165 function can send and return fewer bytes than is passed in; in | |
| 166 that case, the function will just be called again until there is | |
| 167 no data left or 0 is returned. A return value of 0 means that no | |
| 168 more data can be currently stored, but there is no error; the | |
| 169 data will be squirrelled away until the writer can accept | |
| 170 data. (This is useful, e.g., of you're dealing with a | |
| 171 non-blocking file descriptor and are getting EWOULDBLOCK errors.) | |
| 172 This function can be NULL if the stream is input-only. */ | |
| 665 | 173 Bytecount (*writer) (Lstream *stream, const unsigned char *data, |
| 814 | 174 Bytecount size); |
| 428 | 175 /* Return non-zero if the last write operation on the stream resulted |
| 176 in an attempt to block (EWOULDBLOCK). If this method does not | |
| 177 exists, the implementation returns 0 */ | |
| 178 int (*was_blocked_p) (Lstream *stream); | |
| 179 /* Rewind the stream. If this is NULL, the stream is not seekable. */ | |
| 180 int (*rewinder) (Lstream *stream); | |
| 181 /* Indicate whether this stream is seekable -- i.e. it can be rewound. | |
| 182 This method is ignored if the stream does not have a rewind | |
| 183 method. If this method is not present, the result is determined | |
| 184 by whether a rewind method is present. */ | |
| 185 int (*seekable_p) (Lstream *stream); | |
| 186 /* Perform any additional operations necessary to flush the | |
| 187 data in this stream. */ | |
| 188 int (*flusher) (Lstream *stream); | |
| 771 | 189 /* Perform any additional operations necessary to close this stream down. |
| 190 May be NULL. This function is called when Lstream_close() is called | |
| 191 (which will be called automatically on any open streams when they are | |
| 192 garbage-collected or deleted with Lstream_delete()). When this | |
| 193 function is called, all pending data in the stream will already have | |
| 194 been written out; however, the closer write more data, e.g. an "end" | |
| 195 section at the end of a file. */ | |
| 428 | 196 int (*closer) (Lstream *stream); |
| 771 | 197 /* Clean up any remaining data at the time that a stream is |
| 198 garbage-collected or deleted with Lstream_delete(). If the stream was | |
| 199 open at this point, the finalizer is called after calling | |
| 200 Lstream_close(). Called only once (NOT called at disksave time). */ | |
| 201 void (*finalizer) (Lstream *stream); | |
| 428 | 202 /* Mark this object for garbage collection. Same semantics as |
| 203 a standard Lisp_Object marker. This function can be NULL. */ | |
| 204 Lisp_Object (*marker) (Lisp_Object lstream); | |
| 205 } Lstream_implementation; | |
| 206 | |
| 771 | 207 #define DEFINE_LSTREAM_IMPLEMENTATION(name, c_name) \ |
| 208 Lstream_implementation lstream_##c_name[1] = \ | |
| 1204 | 209 { { (name), sizeof (struct c_name##_stream), \ |
| 210 &lstream_empty_extra_description } } | |
| 211 | |
| 212 #define DEFINE_LSTREAM_IMPLEMENTATION_WITH_DATA(name, c_name) \ | |
| 213 static const struct sized_memory_description c_name##_lstream_description_0 \ | |
| 214 = { \ | |
| 215 sizeof (struct c_name##_stream), \ | |
| 216 c_name##_lstream_description \ | |
| 217 }; \ | |
| 218 Lstream_implementation lstream_##c_name[1] = \ | |
| 219 { { (name), sizeof (struct c_name##_stream), \ | |
| 220 &c_name##_lstream_description_0 } } | |
| 771 | 221 |
| 222 #define DECLARE_LSTREAM(c_name) \ | |
| 223 extern Lstream_implementation lstream_##c_name[] | |
| 428 | 224 |
| 225 #define LSTREAM_FL_IS_OPEN 1 | |
| 226 #define LSTREAM_FL_READ 2 | |
| 227 #define LSTREAM_FL_WRITE 4 | |
| 228 #define LSTREAM_FL_NO_PARTIAL_CHARS 8 | |
| 229 #define LSTREAM_FL_CLOSE_AT_DISKSAVE 16 | |
| 230 | |
| 231 struct lstream | |
| 232 { | |
|
5127
a9c41067dd88
more cleanups, terminology clarification, lots of doc work
Ben Wing <ben@xemacs.org>
parents:
5120
diff
changeset
|
233 NORMAL_LISP_OBJECT_HEADER header; |
| 442 | 234 const Lstream_implementation *imp; /* methods for this stream */ |
| 428 | 235 Lstream_buffering buffering; /* type of buffering in use */ |
| 665 | 236 Bytecount buffering_size; /* number of bytes buffered */ |
| 428 | 237 |
| 238 unsigned char *in_buffer; /* holds characters read from stream end */ | |
| 665 | 239 Bytecount in_buffer_size; /* allocated size of buffer */ |
| 240 Bytecount in_buffer_current; /* number of characters in buffer */ | |
| 241 Bytecount in_buffer_ind; /* pointer to next character to | |
| 462 | 242 take from buffer */ |
| 428 | 243 |
| 244 unsigned char *out_buffer; /* holds characters to write to stream end */ | |
| 665 | 245 Bytecount out_buffer_size; /* allocated size of buffer */ |
| 246 Bytecount out_buffer_ind; /* pointer to next buffer spot to | |
| 462 | 247 write a character */ |
| 428 | 248 |
| 249 /* The unget buffer is more or less a stack -- things get pushed | |
| 250 onto the end and read back from the end. Lstream_read() | |
| 251 basically reads backwards from the end to get stuff; Lstream_unread() | |
| 252 similarly has to push the data on backwards. */ | |
| 253 unsigned char *unget_buffer; /* holds characters pushed back onto input */ | |
| 665 | 254 Bytecount unget_buffer_size; /* allocated size of buffer */ |
| 255 Bytecount unget_buffer_ind; /* pointer to next buffer spot | |
| 462 | 256 to write a character */ |
| 428 | 257 |
| 665 | 258 Bytecount byte_count; |
| 456 | 259 int flags; |
| 260 max_align_t data[1]; | |
| 428 | 261 }; |
| 262 | |
| 1204 | 263 extern const struct sized_memory_description lstream_empty_extra_description; |
| 264 | |
| 428 | 265 #define LSTREAM_TYPE_P(lstr, type) \ |
| 266 ((lstr)->imp == lstream_##type) | |
| 267 | |
| 800 | 268 #ifdef ERROR_CHECK_TYPES |
| 826 | 269 DECLARE_INLINE_HEADER ( |
| 270 struct lstream * | |
| 428 | 271 error_check_lstream_type (struct lstream *stream, |
| 442 | 272 const Lstream_implementation *imp) |
| 826 | 273 ) |
| 428 | 274 { |
| 275 assert (stream->imp == imp); | |
| 276 return stream; | |
| 277 } | |
| 771 | 278 # define LSTREAM_TYPE_DATA(lstr, type) \ |
| 279 ((struct type##_stream *) \ | |
| 280 Lstream_data (error_check_lstream_type (lstr, lstream_##type))) | |
| 428 | 281 #else |
| 771 | 282 # define LSTREAM_TYPE_DATA(lstr, type) \ |
| 428 | 283 ((struct type##_stream *) Lstream_data (lstr)) |
| 284 #endif | |
| 285 | |
| 771 | 286 /* Declare that lstream-type TYPE has method M; used in initialization |
| 287 routines */ | |
| 428 | 288 #define LSTREAM_HAS_METHOD(type, m) \ |
| 289 (lstream_##type->m = type##_##m) | |
| 290 | |
| 291 | |
| 442 | 292 Lstream *Lstream_new (const Lstream_implementation *imp, |
| 293 const char *mode); | |
| 428 | 294 void Lstream_reopen (Lstream *lstr); |
| 295 void Lstream_set_buffering (Lstream *lstr, Lstream_buffering buffering, | |
| 296 int buffering_size); | |
| 297 int Lstream_flush (Lstream *lstr); | |
| 298 int Lstream_flush_out (Lstream *lstr); | |
| 299 int Lstream_fputc (Lstream *lstr, int c); | |
| 300 int Lstream_fgetc (Lstream *lstr); | |
| 301 void Lstream_fungetc (Lstream *lstr, int c); | |
| 665 | 302 Bytecount Lstream_read (Lstream *lstr, void *data, |
| 303 Bytecount size); | |
| 771 | 304 int Lstream_write (Lstream *lstr, const void *data, |
| 305 Bytecount size); | |
| 428 | 306 int Lstream_was_blocked_p (Lstream *lstr); |
| 665 | 307 void Lstream_unread (Lstream *lstr, const void *data, Bytecount size); |
| 428 | 308 int Lstream_rewind (Lstream *lstr); |
| 309 int Lstream_seekable_p (Lstream *lstr); | |
| 310 int Lstream_close (Lstream *lstr); | |
| 771 | 311 |
| 428 | 312 void Lstream_delete (Lstream *lstr); |
| 313 void Lstream_set_character_mode (Lstream *str); | |
| 771 | 314 void Lstream_unset_character_mode (Lstream *lstr); |
| 428 | 315 |
| 771 | 316 /* Lstream_putc: Write out one byte to the stream. This is a macro |
| 317 and so it is very efficient. The C argument is only evaluated once | |
| 318 but the STREAM argument is evaluated more than once. Returns 0 on | |
| 319 success, -1 on error. */ | |
| 428 | 320 |
| 771 | 321 #define Lstream_putc(stream, c) \ |
| 322 /* Call the function equivalent if the out buffer is full. Otherwise, \ | |
| 323 add to the end of the out buffer and, if line buffering is called for \ | |
| 324 and the character marks the end of a line, write out the buffer. */ \ | |
| 325 ((stream)->out_buffer_ind >= (stream)->out_buffer_size ? \ | |
| 326 Lstream_fputc (stream, c) : \ | |
| 327 ((stream)->out_buffer[(stream)->out_buffer_ind++] = \ | |
| 328 (unsigned char) (c), \ | |
| 329 (stream)->byte_count++, \ | |
| 330 (stream)->buffering == LSTREAM_LINE_BUFFERED && \ | |
| 331 (stream)->out_buffer[(stream)->out_buffer_ind - 1] == '\n' ? \ | |
| 428 | 332 Lstream_flush_out (stream) : 0)) |
| 333 | |
| 771 | 334 /* Lstream_getc: Read one byte from the stream and returns it as an |
| 335 unsigned char cast to an int, or EOF on end of file or error. This | |
| 336 is a macro and so it is very efficient. The STREAM argument is | |
| 337 evaluated more than once. */ | |
| 338 | |
| 339 #define Lstream_getc(stream) \ | |
| 340 /* Retrieve from unget buffer if there are any characters there; \ | |
| 341 else retrieve from in buffer if there's anything there; \ | |
| 342 else call the function equivalent */ \ | |
| 428 | 343 ((stream)->unget_buffer_ind > 0 ? \ |
| 344 ((stream)->byte_count++, \ | |
| 345 (stream)->unget_buffer[--(stream)->unget_buffer_ind]) : \ | |
| 346 (stream)->in_buffer_ind < (stream)->in_buffer_current ? \ | |
| 347 ((stream)->byte_count++, \ | |
| 348 (stream)->in_buffer[(stream)->in_buffer_ind++]) : \ | |
| 349 Lstream_fgetc (stream)) | |
| 350 | |
| 771 | 351 /* Lstream_ungetc: Push one byte back onto the input queue, cast to |
| 352 unsigned char. This will be the next byte read from the stream. | |
| 353 Any number of bytes can be pushed back and will be read in the | |
| 354 reverse order they were pushed back -- most recent first. (This is | |
| 355 necessary for consistency -- if there are a number of bytes that | |
| 356 have been unread and I read and unread a byte, it needs to be the | |
| 357 first to be read again.) This is a macro and so it is very | |
| 358 efficient. The C argument is only evaluated once but the STREAM | |
| 359 argument is evaluated more than once. | |
| 360 */ | |
| 361 | |
| 428 | 362 #define Lstream_ungetc(stream, c) \ |
| 771 | 363 /* Add to the end if it won't overflow buffer; otherwise call the \ |
| 364 function equivalent */ \ | |
| 428 | 365 ((stream)->unget_buffer_ind >= (stream)->unget_buffer_size ? \ |
| 366 Lstream_fungetc (stream, c) : \ | |
| 367 (void) ((stream)->byte_count--, \ | |
| 368 ((stream)->unget_buffer[(stream)->unget_buffer_ind++] = \ | |
| 369 (unsigned char) (c)))) | |
| 370 | |
| 371 #define Lstream_data(stream) ((void *) ((stream)->data)) | |
| 372 #define Lstream_byte_count(stream) ((stream)->byte_count) | |
| 373 | |
| 374 | |
| 375 /************************************************************************/ | |
| 867 | 376 /* working with an Lstream as a stream of Ichars */ |
| 428 | 377 /************************************************************************/ |
| 378 | |
| 379 #ifdef MULE | |
| 380 | |
| 826 | 381 DECLARE_INLINE_HEADER ( |
| 867 | 382 Ichar |
| 383 Lstream_get_ichar (Lstream *stream) | |
| 826 | 384 ) |
| 428 | 385 { |
| 386 int c = Lstream_getc (stream); | |
| 826 | 387 return (c < 0x80 /* c == EOF || byte_ascii_p (c) */ |
| 867 | 388 ? (Ichar) c |
| 389 : Lstream_get_ichar_1 (stream, c)); | |
| 428 | 390 } |
| 391 | |
| 867 | 392 /* Write an Ichar to a stream. Return value is 0 for success, -1 for |
| 771 | 393 failure. */ |
| 394 | |
| 826 | 395 DECLARE_INLINE_HEADER ( |
| 396 int | |
| 867 | 397 Lstream_put_ichar (Lstream *stream, Ichar ch) |
| 826 | 398 ) |
| 428 | 399 { |
| 867 | 400 return ichar_ascii_p (ch) ? |
| 428 | 401 Lstream_putc (stream, ch) : |
| 867 | 402 Lstream_fput_ichar (stream, ch); |
| 428 | 403 } |
| 404 | |
| 826 | 405 DECLARE_INLINE_HEADER ( |
| 406 void | |
| 867 | 407 Lstream_unget_ichar (Lstream *stream, Ichar ch) |
| 826 | 408 ) |
| 428 | 409 { |
| 867 | 410 if (ichar_ascii_p (ch)) |
| 428 | 411 Lstream_ungetc (stream, ch); |
| 412 else | |
| 867 | 413 Lstream_funget_ichar (stream, ch); |
| 428 | 414 } |
| 415 #else /* not MULE */ | |
| 416 | |
| 867 | 417 # define Lstream_get_ichar(stream) Lstream_getc (stream) |
| 418 # define Lstream_put_ichar(stream, ch) Lstream_putc (stream, ch) | |
| 419 # define Lstream_unget_ichar(stream, ch) Lstream_ungetc (stream, ch) | |
| 428 | 420 |
| 421 #endif /* not MULE */ | |
| 422 | |
| 423 | |
| 424 /************************************************************************/ | |
| 425 /* Lstream implementations */ | |
| 426 /************************************************************************/ | |
| 427 | |
| 428 /* Flags we can pass to the filedesc and stdio streams. */ | |
| 429 | |
| 430 /* If set, close the descriptor or FILE * when the stream is closed. */ | |
| 431 #define LSTR_CLOSING 1 | |
| 432 | |
| 433 /* If set, allow quitting out of the actual I/O. */ | |
| 434 #define LSTR_ALLOW_QUIT 2 | |
| 435 | |
| 436 /* If set and filedesc_stream_set_pty_flushing() has been called | |
| 437 on the stream, do not send more than pty_max_bytes on a single | |
| 438 line without flushing the data out using the eof_char. */ | |
| 439 #define LSTR_PTY_FLUSHING 4 | |
| 440 | |
| 441 /* If set, an EWOULDBLOCK error is not treated as an error but | |
| 442 simply causes the write function to return 0 as the number | |
| 443 of bytes written out. */ | |
| 444 #define LSTR_BLOCKED_OK 8 | |
| 445 | |
| 446 Lisp_Object make_stdio_input_stream (FILE *stream, int flags); | |
| 447 Lisp_Object make_stdio_output_stream (FILE *stream, int flags); | |
| 448 Lisp_Object make_filedesc_input_stream (int filedesc, int offset, int count, | |
| 449 int flags); | |
| 450 Lisp_Object make_filedesc_output_stream (int filedesc, int offset, int count, | |
| 451 int flags); | |
| 452 void filedesc_stream_set_pty_flushing (Lstream *stream, | |
| 453 int pty_max_bytes, | |
| 867 | 454 Ibyte eof_char); |
| 428 | 455 int filedesc_stream_fd (Lstream *stream); |
| 456 Lisp_Object make_lisp_string_input_stream (Lisp_Object string, | |
| 457 Bytecount offset, | |
| 458 Bytecount len); | |
| 462 | 459 Lisp_Object make_fixed_buffer_input_stream (const void *buf, |
| 665 | 460 Bytecount size); |
| 462 | 461 Lisp_Object make_fixed_buffer_output_stream (void *buf, |
| 665 | 462 Bytecount size); |
| 442 | 463 const unsigned char *fixed_buffer_input_stream_ptr (Lstream *stream); |
| 428 | 464 unsigned char *fixed_buffer_output_stream_ptr (Lstream *stream); |
| 465 Lisp_Object make_resizing_buffer_output_stream (void); | |
| 466 unsigned char *resizing_buffer_stream_ptr (Lstream *stream); | |
| 788 | 467 Lisp_Object resizing_buffer_to_lisp_string (Lstream *stream); |
| 428 | 468 Lisp_Object make_dynarr_output_stream (unsigned_char_dynarr *dyn); |
| 469 #define LSTR_SELECTIVE 1 | |
| 470 #define LSTR_IGNORE_ACCESSIBLE 2 | |
| 665 | 471 Lisp_Object make_lisp_buffer_input_stream (struct buffer *buf, Charbpos start, |
| 472 Charbpos end, int flags); | |
| 473 Lisp_Object make_lisp_buffer_output_stream (struct buffer *buf, Charbpos pos, | |
| 428 | 474 int flags); |
| 665 | 475 Charbpos lisp_buffer_stream_startpos (Lstream *stream); |
| 428 | 476 |
| 440 | 477 #endif /* INCLUDED_lstream_h_ */ |