device-open

Generic Function

Package: excl

Arguments: stream options

Makes the connection between the stream structure and the actual device being opened, if appropriate, and completes the initialization of the stream structure adequately enough to perform operations on the stream. device-open is called from an :after method on shared-initialize after the CLOS stream is created and initialized. device-open returns true if successful and nil otherwise. If unsuccessful, the shared-initialize after method will call device-close on the new stream with :abort t. Writers of methods on device-open must be aware that if they call-next-method and that returns nil, it means that the next-method has failed. The primary method must either install all of the control-character processing tables, external-formats, and instance flags (see section Control-character Processing) or it must call the next more general primary method to do so, modifying the stream to specialize it after such installations, as desired. Allocation and/or installation of any buffers required for stream operation is also done by the device-open method which is at an appropriate specialization level for use of that buffer. If resourcing of buffers is desired, they may be passed in through make-instance/reinitialize-instance arguments, or previously installed buffers may be reused.

The device-open method must be prepared to recognize resource and change-class situations. If no filename is specified in the options list, and if no input-handle or output-handle is given, then the input-handle and output-handle slots should be examined; if non-nil, that means the stream is still open, and thus the operation being requested of device-read is a change-class. Also, a device-read method need not allocate a buffer every time it is called, but may instead reuse a buffer it finds in a stream, if it does not become a security issue.

The options argument is a list of pairs of options and values. It is essentially the initargs argument to the shared-initialize :after method, which is passed to device-open unchanged. The options argument is essentially the same as the keyword arguments to cl:open, which has been extended with several keywords and which also has &allow-other-keys, allowing essentially any keywords to be processed by device-open. The filespec argument is turned into a physical pathname and passed in the options list as a :filename spec. The other extra options include:

class: the class argument can determine what class to make an instance of, in the same way as in gray-streams.
mapped: if :mapped t is specified, and the file being opened is not a fifo or character-special file, then the file is opened using a mapped-file-simple-stream
fn-in, fn-out: these are preserved for compatibility, but are deprecated in favor of the better names, input-handle and output-handle.
input-handle, output-handle: these allow the specification of an already-opened "device", which can either be an open file descriptor or a stream. If either of these options are used, then cl:open should not be called, but instead make-instance should be called with no :filename spec. If a handle is a stream, then the make-instance call is said to encapsulate the stream; the result of the make-instance call is the encapsulating stream, and the handle is the encapsulated stream (which itself may be an encapsulating stream).

Current unspecified device-open methods exist on all existing leaf stream classes. Device writers must determine whether it is appropriate to use the existing version, or to write one.

See streams.htm for information on the simple-streams implementation in Allegro CL. See particularly thse sections in that document: Device-open and From-scratch device-open.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.