device-open

Arguments: stream slot-names initargs

Number of required arguments changed in release 7.0. In release 6.2, this function had two required arguments, simple-stream and options. In 7.0, it has three. The initargs argument is essentially a new name for the old options argument. device-open now is similar to shared-initialize.

This generic function 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. See below for device-open on string-streams.

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-open is a change-class. Also, a device-open 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 initargs argument is a list of keyword/value pairs. It is restified list of the initargs argument to the shared-initialize :after method (that list is passed to device-open unchanged). Acceptable keywords include the keyword arguments to cl:open (the filespec required argument to cl:open is turned into a physical pathname and passed in the options list paired with the keyword :filename). The Allegro CL implementation of cl:open has been extended with additional named keyword arguments and also has &allow-other-keys so any keyword may appear as the identifier in the options list processed by device-open. (See the discussion of the Allegro CL implementation of cl:open in Extensions to cl:make-package, cl:disassemble, cl:open, cl:apropos in implementation.htm.)

Additional named keyword arguments 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 and :fn-out: these are preserved for compatibility, but are deprecated in favor of the better names, :input-handle and :output-handle.
• :input-handle and :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 specified. 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).

The slot-names is provided to distinguish between calls to device-open from a new stream (via initialize-instance), a reused stream from a resource (via reinitialize-instance), or a changed class, and is precisely the same value that was given to the shared-initialize which called device-open. In short, if slot-names is the value t, then the operation being performed is an initialize-instance; if slot-names is a non-nil list, then a change-class is occurring, and if it is nil, then either a change-class or a reinitialize-instance is occurring.

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

device-open for string-streams

device-open methods for string-streams should be :before methods. There is a default primary method that simply returns t if the string-stream has been opened properly and returns nil otherwise. Users should ensure that they do not overwrite more-specific :before methods (that is, write a :before method for your own subclass but not for classes you have do not defined).

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

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.