Next: , Up: Programmatic ports


4.5.2.1 Port data type

The ports structure defines the basis of the port data type and exports the following procedures.

— procedure: make-port handler status lock data buffer index limit pending-eof? –> port

Port constructor. The arguments are all the fields of ports, which are described below. Note that make-port is rarely called directly; usually one will use one of the buffered port constructors instead.

— procedure: port-handler port –> port-handler
— procedure: port-buffer port –> buffer or #f
— procedure: port-lock port –> value
— procedure: port-status port –> integer-status
— procedure: port-data port –> value
— procedure: port-index port –> integer or #f
— procedure: port-limit port –> integer or #f
— procedure: port-pending-eof? port –> boolean

Accessors for the port fields:

handler
The handler is the functional parameterization mechanism: it provides all the port's operations, such as reading/writing blocks, disclosing (see Writer) the port, closing the port, &c. See Port handlers.
buffer
The buffer is used for buffered ports, where it is a byte vector. It may be any value for unbuffered ports.
lock
This misnamed field was originally used for a mutual exclusion lock, before optimistic concurrency was made the native synchronization mechanism in Scheme48. It is now used as a `timestamp' for buffered ports: it is provisionally written to with a unique value when a thread resets the index to reuse the buffer, and it is provisionally read from when reading from the buffer. In this way, if the buffer is reset while another thread is reading from it, the other thread's proposal is invalidated by the different value in memory than what was there when it logged the old timestamp in its proposal.
status
A mask from the port-status-options enumeration; see Miscellaneous I/O internals.
data
Arbitrary data for particular kinds of ports. For example, for a port that tracks line & column information (see I/O extensions), this might be a record containing the underlying port, the line number, and the column number.
index
The current index into a buffered port's buffer. If the port is not buffered, this is #f.
limit
The limit of the index field for a buffered port's buffer. When the index field is equal to the limit field, the buffer is full. If the port is not buffered, this is #f.
pending-eof?
For output ports, this is a boolean flag indicating whether the buffer has been forced to output recently. For input ports, this is a boolean flag indicating whether an end of file is pending after reading through the current buffer.

— procedure: set-port-lock! port value –> unspecified
— procedure: set-port-status! port status –> unspecified
— procedure: set-port-data! port data –> unspecified
— procedure: set-port-index! port index –> unspecified
— procedure: set-port-limit! port index –> unspecified
— procedure: set-port-pending-eof?! port pending-eof? –> unspecified

These assign respective fields of ports. The buffer and handler fields, however, are immutable.

— procedure: provisional-port-handler port –> port-handler
— procedure: provisional-port-lock port –> value
— procedure: provisional-port-status port –> integer-status
— procedure: provisional-port-data port –> value
— procedure: provisional-port-index port –> integer or #f
— procedure: provisional-port-limit port –> integer or #f
— procedure: provisional-port-pending-eof? port –> boolean
— procedure: provisional-set-port-lock! port value –> unspecified
— procedure: provisional-set-port-status! port status –> unspecified
— procedure: provisional-set-port-data! port data –> unspecified
— procedure: provisional-set-port-index! port index –> unspecified
— procedure: provisional-set-port-limit! port index –> unspecified
— procedure: provisional-set-port-pending-eof?! port pending-eof? –> unspecified

Provisional versions of the above port accessors & modifiers; that is, accessors & modifiers that log in the current proposal, if there is one.