ports: avoid adding port table entries and finalizers if possible
[bpt/guile.git] / libguile / ports.h
1 /* classes: h_files */
2
3 #ifndef SCM_PORTS_H
4 #define SCM_PORTS_H
5
6 /* Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2003, 2004,
7 * 2006, 2008, 2009, 2010, 2011, 2012 Free Software Foundation, Inc.
8 *
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public License
11 * as published by the Free Software Foundation; either version 3 of
12 * the License, or (at your option) any later version.
13 *
14 * This library is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with this library; if not, write to the Free Software
21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
22 * 02110-1301 USA
23 */
24
25 \f
26
27 #include "libguile/__scm.h"
28
29 #include <stdio.h>
30 #include <string.h>
31 #include <unistd.h>
32 #include "libguile/gc.h"
33 #include "libguile/tags.h"
34 #include "libguile/error.h"
35 #include "libguile/print.h"
36 #include "libguile/struct.h"
37 #include "libguile/threads.h"
38 #include "libguile/strings.h"
39
40 \f
41
42 #define SCM_INITIAL_PUTBACK_BUF_SIZE 4
43
44 /* values for the rw_active flag. */
45 typedef enum scm_t_port_rw_active {
46 SCM_PORT_NEITHER = 0,
47 SCM_PORT_READ = 1,
48 SCM_PORT_WRITE = 2
49 } scm_t_port_rw_active;
50
51 typedef enum scm_t_port_encoding_mode {
52 SCM_PORT_ENCODING_MODE_UTF8,
53 SCM_PORT_ENCODING_MODE_ICONV
54 } scm_t_port_encoding_mode;
55
56 /* This is a separate object so that only those ports that use iconv
57 cause finalizers to be registered. */
58 typedef struct scm_t_iconv_descriptors
59 {
60 /* input/output iconv conversion descriptors */
61 void *input_cd;
62 void *output_cd;
63 } scm_t_iconv_descriptors;
64
65 /* C representation of a Scheme port. */
66
67 typedef struct
68 {
69 SCM port; /* Link back to the port object. */
70 scm_i_pthread_mutex_t *lock; /* A recursive lock for this port. */
71
72 int revealed; /* 0 not revealed, > 1 revealed.
73 * Revealed ports do not get GC'd.
74 */
75 /* data for the underlying port implementation as a raw C value. */
76 scm_t_bits stream;
77
78 SCM file_name; /* debugging support. */
79 long line_number; /* debugging support. */
80 int column_number; /* debugging support. */
81
82 /* port buffers. the buffer(s) are set up for all ports.
83 in the case of string ports, the buffer is the string itself.
84 in the case of unbuffered file ports, the buffer is a
85 single char: shortbuf. */
86
87 /* this buffer is filled from read_buf to read_end using the ptob
88 buffer_fill. then input requests are taken from read_pos until
89 it reaches read_end. */
90
91 unsigned char *read_buf; /* buffer start. */
92 const unsigned char *read_pos;/* the next unread char. */
93 unsigned char *read_end; /* pointer to last buffered char + 1. */
94 scm_t_off read_buf_size; /* size of the buffer. */
95
96 /* when chars are put back into the buffer, e.g., using peek-char or
97 unread-string, the read-buffer pointers are switched to cbuf.
98 the original pointers are saved here and restored when the put-back
99 chars have been consumed. */
100 unsigned char *saved_read_buf;
101 const unsigned char *saved_read_pos;
102 unsigned char *saved_read_end;
103 scm_t_off saved_read_buf_size;
104
105 /* write requests are saved into this buffer at write_pos until it
106 reaches write_buf + write_buf_size, then the ptob flush is
107 called. */
108
109 unsigned char *write_buf; /* buffer start. */
110 unsigned char *write_pos; /* pointer to last buffered char + 1. */
111 unsigned char *write_end; /* pointer to end of buffer + 1. */
112 scm_t_off write_buf_size; /* size of the buffer. */
113
114 unsigned char shortbuf; /* buffer for "unbuffered" streams. */
115
116 int rw_random; /* true if the port is random access.
117 implies that the buffers must be
118 flushed before switching between
119 reading and writing, seeking, etc. */
120
121 scm_t_port_rw_active rw_active; /* for random access ports,
122 indicates which of the buffers
123 is currently in use. can be
124 SCM_PORT_WRITE, SCM_PORT_READ,
125 or SCM_PORT_NEITHER. */
126
127
128 /* a buffer for un-read chars and strings. */
129 unsigned char *putback_buf;
130 size_t putback_buf_size; /* allocated size of putback_buf. */
131
132 /* Character encoding support */
133 char *encoding;
134 scm_t_port_encoding_mode encoding_mode;
135 scm_t_string_failed_conversion_handler ilseq_handler;
136 scm_t_iconv_descriptors *iconv_descriptors;
137 } scm_t_port;
138
139
140 SCM_INTERNAL SCM scm_i_port_weak_set;
141
142
143 #define SCM_READ_BUFFER_EMPTY_P(c_port) (c_port->read_pos >= c_port->read_end)
144
145 \f
146
147 #define SCM_EOF_OBJECT_P(x) (scm_is_eq ((x), SCM_EOF_VAL))
148
149 /* PORT FLAGS
150 * A set of flags characterizes a port.
151 * Note that we reserve the bits 1 << 24 and above for use by the
152 * routines in the port's scm_ptobfuns structure.
153 */
154 #define SCM_OPN (1L<<16) /* Is the port open? */
155 #define SCM_RDNG (2L<<16) /* Is it a readable port? */
156 #define SCM_WRTNG (4L<<16) /* Is it writable? */
157 #define SCM_BUF0 (8L<<16) /* Is it unbuffered? */
158 #define SCM_BUFLINE (64L<<16) /* Is it line-buffered? */
159
160 #define SCM_PORTP(x) (SCM_HAS_TYP7 (x, scm_tc7_port))
161 #define SCM_OPPORTP(x) (SCM_PORTP (x) && (SCM_CELL_WORD_0 (x) & SCM_OPN))
162 #define SCM_INPUT_PORT_P(x) (SCM_PORTP (x) && (SCM_CELL_WORD_0 (x) & SCM_RDNG))
163 #define SCM_OUTPUT_PORT_P(x) (SCM_PORTP (x) && (SCM_CELL_WORD_0 (x) & SCM_WRTNG))
164 #define SCM_OPINPORTP(x) (SCM_OPPORTP (x) && SCM_INPUT_PORT_P (x))
165 #define SCM_OPOUTPORTP(x) (SCM_OPPORTP (x) && SCM_OUTPUT_PORT_P (x))
166 #define SCM_OPENP(x) (SCM_OPPORTP (x))
167 #define SCM_CLOSEDP(x) (!SCM_OPENP (x))
168 #define SCM_CLR_PORT_OPEN_FLAG(p) \
169 SCM_SET_CELL_WORD_0 ((p), SCM_CELL_WORD_0 (p) & ~SCM_OPN)
170
171 #define SCM_PTAB_ENTRY(x) ((scm_t_port *) SCM_CELL_WORD_1 (x))
172 #define SCM_PORT_DESCRIPTOR(port) ((scm_t_ptob_descriptor *) SCM_CELL_WORD_2 (port))
173 #define SCM_SETPTAB_ENTRY(x, ent) (SCM_SET_CELL_WORD_1 ((x), (scm_t_bits) (ent)))
174 #define SCM_STREAM(x) (SCM_PTAB_ENTRY(x)->stream)
175 #define SCM_SETSTREAM(x, s) (SCM_PTAB_ENTRY(x)->stream = (scm_t_bits) (s))
176 #define SCM_FILENAME(x) (SCM_PTAB_ENTRY(x)->file_name)
177 #define SCM_SET_FILENAME(x, n) (SCM_PTAB_ENTRY(x)->file_name = (n))
178 #define SCM_LINUM(x) (SCM_PTAB_ENTRY(x)->line_number)
179 #define SCM_COL(x) (SCM_PTAB_ENTRY(x)->column_number)
180 #define SCM_REVEALED(x) (SCM_PTAB_ENTRY(x)->revealed)
181 #define SCM_SETREVEALED(x, s) (SCM_PTAB_ENTRY(x)->revealed = (s))
182
183 #define SCM_INCLINE(port) do {SCM_LINUM (port) += 1; SCM_COL (port) = 0;} while (0)
184 #define SCM_ZEROCOL(port) do {SCM_COL (port) = 0;} while (0)
185 #define SCM_INCCOL(port) do {SCM_COL (port) += 1;} while (0)
186 #define SCM_DECCOL(port) do {if (SCM_COL (port) > 0) SCM_COL (port) -= 1;} while (0)
187 #define SCM_TABCOL(port) do {SCM_COL (port) += 8 - SCM_COL (port) % 8;} while (0)
188
189 /* Maximum number of port types. */
190 #define SCM_I_MAX_PORT_TYPE_COUNT 256
191
192 \f
193
194 typedef enum scm_t_port_type_flags {
195 SCM_PORT_TYPE_HAS_FLUSH = 1 << 0
196 } scm_t_port_type_flags;
197
198 /* port-type description. */
199 typedef struct scm_t_ptob_descriptor
200 {
201 char *name;
202 SCM (*mark) (SCM);
203 size_t (*free) (SCM);
204 int (*print) (SCM exp, SCM port, scm_print_state *pstate);
205 SCM (*equalp) (SCM, SCM);
206 int (*close) (SCM port);
207
208 void (*write) (SCM port, const void *data, size_t size);
209 void (*flush) (SCM port);
210
211 void (*end_input) (SCM port, int offset);
212 int (*fill_input) (SCM port);
213 int (*input_waiting) (SCM port);
214
215 scm_t_off (*seek) (SCM port, scm_t_off OFFSET, int WHENCE);
216 void (*truncate) (SCM port, scm_t_off length);
217
218 unsigned flags;
219 } scm_t_ptob_descriptor;
220
221 #define SCM_TC2PTOBNUM(x) (0x0ff & ((x) >> 8))
222 #define SCM_PTOBNUM(x) (SCM_TC2PTOBNUM (SCM_CELL_TYPE (x)))
223 /* SCM_PTOBNAME can be 0 if name is missing */
224 #define SCM_PTOBNAME(ptobnum) (scm_c_port_type_ref (ptobnum)->name)
225
226 /* Port types, and their vtables. */
227 SCM_INTERNAL long scm_c_num_port_types (void);
228 SCM_API scm_t_ptob_descriptor* scm_c_port_type_ref (long ptobnum);
229 SCM_API long scm_c_port_type_add_x (scm_t_ptob_descriptor *desc);
230 SCM_API scm_t_bits scm_make_port_type (char *name,
231 int (*fill_input) (SCM port),
232 void (*write) (SCM port,
233 const void *data,
234 size_t size));
235 SCM_API void scm_set_port_mark (scm_t_bits tc, SCM (*mark) (SCM));
236 SCM_API void scm_set_port_free (scm_t_bits tc, size_t (*free) (SCM));
237 SCM_API void scm_set_port_print (scm_t_bits tc,
238 int (*print) (SCM exp,
239 SCM port,
240 scm_print_state *pstate));
241 SCM_API void scm_set_port_equalp (scm_t_bits tc, SCM (*equalp) (SCM, SCM));
242 SCM_API void scm_set_port_close (scm_t_bits tc, int (*close) (SCM));
243
244 SCM_API void scm_set_port_flush (scm_t_bits tc, void (*flush) (SCM port));
245 SCM_API void scm_set_port_end_input (scm_t_bits tc,
246 void (*end_input) (SCM port,
247 int offset));
248 SCM_API void scm_set_port_seek (scm_t_bits tc,
249 scm_t_off (*seek) (SCM port,
250 scm_t_off OFFSET,
251 int WHENCE));
252 SCM_API void scm_set_port_truncate (scm_t_bits tc,
253 void (*truncate) (SCM port,
254 scm_t_off length));
255 SCM_API void scm_set_port_input_waiting (scm_t_bits tc, int (*input_waiting) (SCM));
256
257 /* The input, output, error, and load ports. */
258 SCM_API SCM scm_current_input_port (void);
259 SCM_API SCM scm_current_output_port (void);
260 SCM_API SCM scm_current_error_port (void);
261 SCM_API SCM scm_current_warning_port (void);
262 SCM_API SCM scm_current_load_port (void);
263 SCM_API SCM scm_set_current_input_port (SCM port);
264 SCM_API SCM scm_set_current_output_port (SCM port);
265 SCM_API SCM scm_set_current_error_port (SCM port);
266 SCM_API SCM scm_set_current_warning_port (SCM port);
267 SCM_API void scm_dynwind_current_input_port (SCM port);
268 SCM_API void scm_dynwind_current_output_port (SCM port);
269 SCM_API void scm_dynwind_current_error_port (SCM port);
270 SCM_INTERNAL void scm_i_dynwind_current_load_port (SCM port);
271
272 /* Mode bits. */
273 SCM_INTERNAL long scm_i_mode_bits (SCM modes);
274 SCM_API long scm_mode_bits (char *modes);
275 SCM_API SCM scm_port_mode (SCM port);
276
277 /* Low-level constructors. */
278 SCM_API SCM
279 scm_c_make_port_with_encoding (scm_t_bits tag,
280 unsigned long mode_bits,
281 const char *encoding,
282 scm_t_string_failed_conversion_handler handler,
283 scm_t_bits stream);
284 SCM_API SCM scm_c_make_port (scm_t_bits tag, unsigned long mode_bits,
285 scm_t_bits stream);
286 SCM_API SCM scm_new_port_table_entry (scm_t_bits tag);
287
288 /* Predicates. */
289 SCM_API SCM scm_port_p (SCM x);
290 SCM_API SCM scm_input_port_p (SCM x);
291 SCM_API SCM scm_output_port_p (SCM x);
292 SCM_API SCM scm_port_closed_p (SCM port);
293 SCM_API SCM scm_eof_object_p (SCM x);
294
295 /* Closing ports. */
296 SCM_API SCM scm_close_port (SCM port);
297 SCM_API SCM scm_close_input_port (SCM port);
298 SCM_API SCM scm_close_output_port (SCM port);
299
300 /* Encoding characters to byte streams, and decoding byte streams to
301 characters. */
302 SCM_INTERNAL const char *scm_i_default_port_encoding (void);
303 SCM_INTERNAL void scm_i_set_default_port_encoding (const char *);
304 SCM_INTERNAL scm_t_iconv_descriptors *scm_i_port_iconv_descriptors (SCM port);
305 SCM_INTERNAL void scm_i_set_port_encoding_x (SCM port, const char *str);
306 SCM_API SCM scm_port_encoding (SCM port);
307 SCM_API SCM scm_set_port_encoding_x (SCM port, SCM encoding);
308 SCM_INTERNAL scm_t_string_failed_conversion_handler scm_i_get_conversion_strategy (SCM port);
309 SCM_INTERNAL void scm_i_set_conversion_strategy_x (SCM port,
310 scm_t_string_failed_conversion_handler h);
311 SCM_API SCM scm_port_conversion_strategy (SCM port);
312 SCM_API SCM scm_set_port_conversion_strategy_x (SCM port, SCM behavior);
313
314 /* Acquiring and releasing the port lock. */
315 SCM_API void scm_dynwind_lock_port (SCM port);
316 SCM_INLINE int scm_c_lock_port (SCM port, scm_i_pthread_mutex_t **lock);
317 SCM_INLINE int scm_c_try_lock_port (SCM port, scm_i_pthread_mutex_t **lock);
318
319 /* Revealed counts. */
320 SCM_API int scm_revealed_count (SCM port);
321 SCM_API SCM scm_port_revealed (SCM port);
322 SCM_API SCM scm_set_port_revealed_x (SCM port, SCM rcount);
323 SCM_API SCM scm_adjust_port_revealed_x (SCM port, SCM addend);
324
325 /* Input. */
326 SCM_API int scm_get_byte_or_eof (SCM port);
327 SCM_INLINE int scm_get_byte_or_eof_unlocked (SCM port);
328 SCM_API int scm_peek_byte_or_eof (SCM port);
329 SCM_INLINE int scm_peek_byte_or_eof_unlocked (SCM port);
330 SCM_API size_t scm_c_read (SCM port, void *buffer, size_t size);
331 SCM_API size_t scm_c_read_unlocked (SCM port, void *buffer, size_t size);
332 SCM_API scm_t_wchar scm_getc (SCM port);
333 SCM_API scm_t_wchar scm_getc_unlocked (SCM port);
334 SCM_API SCM scm_read_char (SCM port);
335
336 /* Pushback. */
337 SCM_INTERNAL void scm_unget_byte (int c, SCM port);
338 SCM_INTERNAL void scm_unget_byte_unlocked (int c, SCM port);
339 SCM_API void scm_ungetc (scm_t_wchar c, SCM port);
340 SCM_API void scm_ungetc_unlocked (scm_t_wchar c, SCM port);
341 SCM_API void scm_ungets (const char *s, int n, SCM port);
342 SCM_API void scm_ungets_unlocked (const char *s, int n, SCM port);
343 SCM_API SCM scm_peek_char (SCM port);
344 SCM_API SCM scm_unread_char (SCM cobj, SCM port);
345 SCM_API SCM scm_unread_string (SCM str, SCM port);
346
347 /* Manipulating the buffers. */
348 SCM_API void scm_port_non_buffer (scm_t_port *pt);
349 SCM_API int scm_fill_input (SCM port);
350 SCM_API int scm_fill_input_unlocked (SCM port);
351 SCM_INTERNAL size_t scm_take_from_input_buffers (SCM port, char *dest, size_t read_len);
352 SCM_API SCM scm_drain_input (SCM port);
353 SCM_API void scm_end_input (SCM port);
354 SCM_API void scm_end_input_unlocked (SCM port);
355 SCM_API SCM scm_force_output (SCM port);
356 SCM_API void scm_flush (SCM port);
357 SCM_API void scm_flush_unlocked (SCM port);
358
359 /* Output. */
360 SCM_API void scm_putc (char c, SCM port);
361 SCM_INLINE void scm_putc_unlocked (char c, SCM port);
362 SCM_API void scm_puts (const char *str_data, SCM port);
363 SCM_INLINE void scm_puts_unlocked (const char *str_data, SCM port);
364 SCM_API void scm_c_write (SCM port, const void *buffer, size_t size);
365 SCM_API void scm_c_write_unlocked (SCM port, const void *buffer, size_t size);
366 SCM_API void scm_lfwrite (const char *ptr, size_t size, SCM port);
367 SCM_API void scm_lfwrite_unlocked (const char *ptr, size_t size, SCM port);
368 SCM_INTERNAL void scm_lfwrite_substr (SCM str, size_t start, size_t end,
369 SCM port);
370
371 /* Querying and setting positions, and character availability. */
372 SCM_API SCM scm_char_ready_p (SCM port);
373 SCM_API SCM scm_seek (SCM object, SCM offset, SCM whence);
374 SCM_API SCM scm_truncate_file (SCM object, SCM length);
375 SCM_API SCM scm_port_line (SCM port);
376 SCM_API SCM scm_set_port_line_x (SCM port, SCM line);
377 SCM_API SCM scm_port_column (SCM port);
378 SCM_API SCM scm_set_port_column_x (SCM port, SCM line);
379 SCM_API SCM scm_port_filename (SCM port);
380 SCM_API SCM scm_set_port_filename_x (SCM port, SCM filename);
381
382 /* Implementation helpers for port printing functions. */
383 SCM_API int scm_port_print (SCM exp, SCM port, scm_print_state *);
384 SCM_API void scm_print_port_mode (SCM exp, SCM port);
385
386 /* Iterating over all ports. */
387 SCM_API SCM scm_port_for_each (SCM proc);
388 SCM_API void scm_c_port_for_each (void (*proc)(void *data, SCM p), void *data);
389 SCM_API SCM scm_flush_all_ports (void);
390
391 /* Void ports. */
392 SCM_API SCM scm_void_port (char * mode_str);
393 SCM_API SCM scm_sys_make_void_port (SCM mode);
394
395 /* Initialization. */
396 SCM_INTERNAL void scm_init_ports (void);
397
398
399 /* Inline function implementations. */
400
401 #if SCM_CAN_INLINE || defined SCM_INLINE_C_IMPLEMENTING_INLINES
402 SCM_INLINE_IMPLEMENTATION int
403 scm_c_lock_port (SCM port, scm_i_pthread_mutex_t **lock)
404 {
405 *lock = SCM_PTAB_ENTRY (port)->lock;
406
407 if (*lock)
408 return scm_i_pthread_mutex_lock (*lock);
409 else
410 return 0;
411 }
412
413 SCM_INLINE_IMPLEMENTATION int
414 scm_c_try_lock_port (SCM port, scm_i_pthread_mutex_t **lock)
415 {
416 *lock = SCM_PTAB_ENTRY (port)->lock;
417 if (*lock)
418 {
419 int ret = scm_i_pthread_mutex_trylock (*lock);
420 if (ret != 0)
421 *lock = NULL;
422 return ret;
423 }
424 else
425 return 0;
426 }
427
428 SCM_INLINE_IMPLEMENTATION int
429 scm_get_byte_or_eof_unlocked (SCM port)
430 {
431 int c;
432 scm_t_port *pt = SCM_PTAB_ENTRY (port);
433
434 if (pt->rw_active == SCM_PORT_WRITE)
435 /* may be marginally faster than calling scm_flush. */
436 SCM_PORT_DESCRIPTOR (port)->flush (port);
437
438 if (pt->rw_random)
439 pt->rw_active = SCM_PORT_READ;
440
441 if (pt->read_pos >= pt->read_end)
442 {
443 if (SCM_UNLIKELY (scm_fill_input_unlocked (port) == EOF))
444 return EOF;
445 }
446
447 c = *(pt->read_pos++);
448
449 return c;
450 }
451
452 /* Like `scm_get_byte_or_eof' but does not change PORT's `read_pos'. */
453 SCM_INLINE_IMPLEMENTATION int
454 scm_peek_byte_or_eof_unlocked (SCM port)
455 {
456 int c;
457 scm_t_port *pt = SCM_PTAB_ENTRY (port);
458
459 if (pt->rw_active == SCM_PORT_WRITE)
460 /* may be marginally faster than calling scm_flush. */
461 SCM_PORT_DESCRIPTOR (port)->flush (port);
462
463 if (pt->rw_random)
464 pt->rw_active = SCM_PORT_READ;
465
466 if (pt->read_pos >= pt->read_end)
467 {
468 if (SCM_UNLIKELY (scm_fill_input_unlocked (port) == EOF))
469 return EOF;
470 }
471
472 c = *pt->read_pos;
473
474 return c;
475 }
476
477 SCM_INLINE_IMPLEMENTATION void
478 scm_putc_unlocked (char c, SCM port)
479 {
480 SCM_ASSERT_TYPE (SCM_OPOUTPORTP (port), port, 0, NULL, "output port");
481 scm_lfwrite_unlocked (&c, 1, port);
482 }
483
484 SCM_INLINE_IMPLEMENTATION void
485 scm_puts_unlocked (const char *s, SCM port)
486 {
487 SCM_ASSERT_TYPE (SCM_OPOUTPORTP (port), port, 0, NULL, "output port");
488 scm_lfwrite_unlocked (s, strlen (s), port);
489 }
490 #endif /* SCM_CAN_INLINE || defined SCM_INLINE_C_IMPLEMENTING_INLINES */
491
492 #endif /* SCM_PORTS_H */
493
494 /*
495 Local Variables:
496 c-file-style: "gnu"
497 End:
498 */