Next: Buffered ports & handlers, Previous: Port data type, Up: Programmatic ports
Port handlers store a port's specific operations for the general
port operations, such as block reads and writes, buffer flushing,
&c. Port handler constructors, including make-port-handler
& the buffered port handlers in the next section, are available from
the i/o-internal
structure.
Basic port handler constructor. The arguments are used for the port handler fields. Each field contains a procedure. The expected semantics of each procedure depend on whether the port is for input or output. Input ports do not use the
buffer-forcer
field. The first two fields are independent of the type of port:
- discloser port –> disclosed
- Returns a disclosed representation of the port, i.e. a list whose
car
is the `type name' of this handler (usually with a suffix of either-input-port
or-output-port
) followed by a list of all of the components to be printed; see Writer.- closer port –> ignored
- Closes port. This operation corresponds with the
close-input-port
&close-output-port
procedures.For input ports, the remaining fields are:
- char-reader port consume? –> char
- Reads a single character from port. If consume? is true, the character should be consumed from port; if consume? is
#f
, however, the character should be left in port's input stream. If consume? is true, this operation corresponds withread-char
; if it is#f
, this operation corresponds withpeek-char
.- block-reader port block start count wait? –> count-written or EOF
- Attempts to read count characters from port's input stream into the string or byte vector block, starting at start. In the case that an insufficient number of characters is available, if wait? is true, the procedure should wait until all of the wanted characters are available; otherwise, if wait? is
#f
, the block reader should immediately return. In either case, it returns the number of characters that were read into block, or an end of file object if it immediately reached the end of the stream. Buffered ports will typically just copy elements from the buffer into block, rather than reading from any internal I/O channel in port. This operation corresponds withread-block
.- readiness-tester port –> boolean
- Returns a true value if there is a character available to be read in port or
#f
if not. This operation corresponds with thechar-ready?
procedure.For output ports, the remaining fields are:
- char-writer port char –> ignored
- Writes the single character char to port. This operation corresponds with
write-char
.- block-writer port block start count –> count-written
- Writes count characters to port from block, starting at start. Block may be a string or a byte vector. This will usually involve copying contents of block to port's buffer, if it is buffered. This operation corresponds with
write-block
.- readiness-tester port –> boolean
- Returns a true value if port is ready to receive a character and
#f
if not.- buffer-forcer port necessary? –> ignored
- For buffered ports, this is intended to force all buffered output to the actual internal I/O channel of port. Necessary? tells whether or not it is absolutely necessary to force all the output immediately; if it is
#t
, the buffer forcer is required to force all output in the buffer before it returns. If necessary? is#f
, not only may it just register an I/O transaction without waiting for it to complete, but it also should not signal an error if port is already closed. For unbuffered ports, this operation need not do anything at all.