|Allegro CL version 9.0|
Unrevised from 8.2 to 9.0.
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
:abort t. Writers of methods on device-open must be aware that if
call-next-method and that
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
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
filespec required argument to cl:open is turned into a physical pathname and
passed in the options list paired with the
: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
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 tis specified, and the file being opened is not a fifo or character-special file, then the file is opened using a
:fn-out: these are preserved for compatibility, but are deprecated in favor of the better names,
: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
:filenamespecified. 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-
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 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-2017, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
|Allegro CL version 9.0|
Unrevised from 8.2 to 9.0.