1.0.4.79: remove lock from *descriptor-handlers*
[sbcl.git] / src / code / ansi-stream.lisp
1 ;;;; the abstract class ANSI-STREAM
2
3 ;;;; This software is part of the SBCL system. See the README file for
4 ;;;; more information.
5 ;;;;
6 ;;;; This software is derived from the CMU CL system, which was
7 ;;;; written at Carnegie Mellon University and released into the
8 ;;;; public domain. The software is in the public domain and is
9 ;;;; provided with absolutely no warranty. See the COPYING and CREDITS
10 ;;;; files for more information.
11
12 (in-package "SB!IMPL")
13 \f
14 ;;; HOW THE ANSI-STREAM STRUCTURE IS USED
15 ;;;
16 ;;; Many of the slots of the ANSI-STREAM structure contain functions
17 ;;; which are called to perform some operation on the stream. Closed
18 ;;; streams have #'CLOSED-FLAME in all of their function slots. If
19 ;;; one side of an I/O or echo stream is closed, the whole stream is
20 ;;; considered closed. The functions in the operation slots take
21 ;;; arguments as follows:
22 ;;;
23 ;;; In:                 Stream, Eof-Errorp, Eof-Value
24 ;;; Bin:                Stream, Eof-Errorp, Eof-Value
25 ;;; N-Bin:              Stream, Buffer, Start, Numbytes, Eof-Errorp
26 ;;; Out:                Stream, Character
27 ;;; Bout:               Stream, Integer
28 ;;; Sout:               Stream, String, Start, End
29 ;;; Misc:               Stream, Operation, &Optional Arg1, Arg2
30 ;;;
31 ;;; In order to save space, some of the less common stream operations
32 ;;; are handled by just one function, the MISC method. This function
33 ;;; is passed a keyword which indicates the operation to perform.
34 ;;; The following keywords are used:
35 ;;;  :listen            - Return the following values:
36 ;;;                          t if any input waiting.
37 ;;;                          :eof if at eof.
38 ;;;                          nil if no input is available and not at eof.
39 ;;;  :unread            - Unread the character Arg.
40 ;;;  :close             - Do any stream specific stuff to close the stream.
41 ;;;                       The methods are set to closed-flame by the close
42 ;;;                       function, so that need not be done by this
43 ;;;                       function.
44 ;;;  :clear-input       - Clear any unread input
45 ;;;  :finish-output,
46 ;;;  :force-output      - Cause output to happen
47 ;;;  :clear-output      - Clear any undone output
48 ;;;  :element-type      - Return the type of element the stream deals with.
49 ;;;  :line-length       - Return the length of a line of output.
50 ;;;  :charpos           - Return current output position on the line.
51 ;;;  :file-length       - Return the file length of a file stream.
52 ;;;  :file-position     - Return or change the current position of a
53 ;;;                       file stream.
54 ;;;  :file-name         - Return the name of an associated file.
55 ;;;  :interactive-p     - Is this an interactive device?
56 ;;;
57 ;;; In order to do almost anything useful, it is necessary to
58 ;;; define a new type of structure that includes stream, so that the
59 ;;; stream can have some state information.
60 ;;;
61 ;;; THE STREAM IN-BUFFER:
62 ;;;
63 ;;; The IN-BUFFER in the stream holds characters or bytes that
64 ;;; are ready to be read by some input function. If there is any
65 ;;; stuff in the IN-BUFFER, then the reading function can use it
66 ;;; without calling any stream method. Any stream may put stuff in
67 ;;; the IN-BUFFER, and may also assume that any input in the IN-BUFFER
68 ;;; has been consumed before any in-method is called. If a text
69 ;;; stream has in IN-BUFFER, then the first character should not be
70 ;;; used to buffer normal input so that it is free for unreading into.
71 ;;;
72 ;;; When the ANSI-STREAM-IN-BUFFER slot, and its index, is only
73 ;;; accessed by the normal stream functions, the number of function
74 ;;; calls is halved, thus potentially doubling the speed of simple
75 ;;; operations. If the FAST-READ-CHAR and FAST-READ-BYTE macros are
76 ;;; used, nearly all function call overhead is removed, vastly
77 ;;; speeding up these important operations.
78 \f
79 ;;; the size of a stream in-buffer
80 ;;;
81 ;;; KLUDGE: The EVAL-WHEN wrapper isn't needed except when using CMU
82 ;;; CL as a cross-compilation host. Without it, cmucl-2.4.19 issues
83 ;;; full WARNINGs (not just STYLE-WARNINGs!) when processing this
84 ;;; file, and when processing other files which use ANSI-STREAM.
85 ;;; -- WHN 2000-12-13
86 (eval-when (:compile-toplevel :load-toplevel :execute)
87   (defconstant +ansi-stream-in-buffer-length+ 512))
88
89 (deftype ansi-stream-in-buffer ()
90   `(simple-array (unsigned-byte 8) (,+ansi-stream-in-buffer-length+)))
91
92 (deftype ansi-stream-cin-buffer ()
93   `(simple-array character (,+ansi-stream-in-buffer-length+)))
94
95 ;;; base class for ANSI standard streams (as opposed to the Gray
96 ;;; streams extension)
97 (defstruct (ansi-stream (:constructor nil)
98                         (:copier nil))
99
100   ;; input buffer
101   ;;
102   ;; (If a stream does not have an input buffer, then the IN-BUFFER
103   ;; slot must must be NIL, and the IN-INDEX must be
104   ;; +ANSI-STREAM-IN-BUFFER-LENGTH+.)
105   (in-buffer nil :type (or ansi-stream-in-buffer null))
106   (cin-buffer nil :type (or ansi-stream-cin-buffer null))
107   (in-index +ansi-stream-in-buffer-length+ :type index)
108
109   ;; buffered input functions
110   (in #'ill-in :type function)                  ; READ-CHAR function
111   (bin #'ill-bin :type function)                ; byte input function
112   (n-bin #'ill-bin :type function)              ; n-byte input function
113
114   ;; output functions
115   (out #'ill-out :type function)                ; WRITE-CHAR function
116   (bout #'ill-bout :type function)              ; byte output function
117   (sout #'ill-out :type function)               ; string output function
118
119   ;; other, less-used methods
120   (misc #'no-op-placeholder :type function))
121
122 (def!method print-object ((x ansi-stream) stream)
123   (print-unreadable-object (x stream :type t :identity t)))