MacroPackage: exclToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version


Arguments: (class-name &optional stream) &body body

Returns the resulting values of the body forms. Within the body, all sm, funcall-stm-handler, and funcall-stm-handler-2 forms are expanded in such a way that the access into the stream requires only one or two memory-reference instructions, as indicated next.

The decision as to whether to use the optional stream argument or not depends on whether there are more than one access anticipated. If two or more accesses are done within the body form, then the stream argument should be specified. If only one access is done, it is not necessary to specify the stream argument. However, if two with-stream-class forms are nested and the outer form specifies a stream argument, then the inner form must also specify the stream argument, otherwise the accesses within the inner form will be from the wrong object.


This example is taken from real source. Note that the stream argument is specified, because there are 3 accesses here: one to grab the co-state slot, one to funcall the j-write-char function, and one to get the plist slot of the stream. All three accesses take one instruction each, after with-stream-class arranges for an extra variable to be pre-loaded with the instance slots vector of the stream.

(defmethod (setf stream-external-format)
    :after (external-format (stream single-channel-simple-stream))
  (with-stream-class (single-channel-simple-stream stream)
    (when (sm co-state stream)
      ;; stream has an ef writer state, flush ef here.
      (funcall-stm-handler-2 j-write-char nil stream))
     stream external-format (getf (sm plist stream) 'access))))

This example demonstrates a nested with-stream-class. Note that the optional stream argument to the outer form isn't really necessary, but presumably a real-life situation would have more than one access to stream. Also, note that if the inner macro did not specify a new optional stream argument (i.e. dribble), then the funcall-stm-handler-2 would have gotten its write-char handler from the wrong stream.

(defun do-a-dribble (stream char)
  (with-stream-class (dual-channel-simple-stream stream)
    (let ((dribble (sm dribble stream)))
       (when dribble
         (with-stream-class (stream dribble)
	    j-write-char char dribble))))))

You must load the :iodefs module to use this macro. Do that by evaluating (require :iodefs). (It is not an error to evaluate that form if the module is already loaded.) This macro is intended for implementing device-level functionality and should not be used except for that purpose. See Simple-stream Description in streams.htm for a description of the device-level.

See streams.htm for information on the simple-streams implementation in Allegro CL.

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

Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version