Next: , Previous: Port data type, Up: Programmatic ports


4.5.2.2 Port handlers

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.

— procedure: make-port-handler discloser closer char-reader/writer block-reader/writer readiness-tester buffer-forcer –> port-handler

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 with read-char; if it is #f, this operation corresponds with peek-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 with read-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 the char-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.