NAME
buffer - Tcl interface to CMT Buffer Manager
SYNOPSIS
buffer create ?options?
buffer delete bufferid
buffer config bufferid ?options?
buffer addtag bufferid tag
buffer dtag bufferid tag
buffer gettags bufferid
buffer find ?options?
buffer findOrCreate ?options?
DESCRIPTION
The buffer command provides a Tcl level interface to the CMT
Buffer Manager. The various options are different buffer
management commands that can be run.
OPTIONS
buffer create ?options?
Creates a new buffer configured with the given options and
returns the bufferid required by other buffer manager com-
mands. Valid options are:
-size
The size of the buffer, in bytes
-shared
Whether the buffer should be in shared memory (if
the value is true) or the application heap (if the
value is false). Default is false (application
heap).
-xattach
Whether XShmAttach should be called for this
buffer. This option is only relevant for buffers
in shared memory. Default value is false.
-state
The state of the buffer (any character string).
Default is the empty string.
-callback
The callback that should be executed to free the
buffer when the reference count reaches 0. (See
also attach and detach)
buffer delete bufferid
Takes the bufferid of an existing buffer and destroys the
buffer, freeing all memory associated with it. Note that
applications will not do this very often. Rather, they
should put a buffer in the state free, so that another
object can re-use the buffer later.
buffer config bufferid ?options?
Without any other arguments, the name, default value, and
current value of all configuration slots on the buffer buf-
ferid are printed. With a single argument that specifies a
configuration slot, the default and current values of that
slot are printed. If more than one argument is present, the
argument should be pairs of slots and values. Each slot is
re-configured to the given value. Valid slots are those
listed for the create option.
Most objects will not need to explicitly configure existing
buffers. The attach and detach facility should be used for
managing object state. Other parameters should not be modi-
fied since buffers may be shared between multiple objects
and other objects probably will not expect buffer parameters
to change unexpectedly.
buffer addtag bufferid tag
Adds tag to the list of tags kept for the buffer bufferid.
buffer dtag bufferid tag
If tag is in the list of tags for bufferid, it is removed
from the list. If it is not in the list, no error is gen-
erated.
buffer gettags bufferid
Returns a list of all the tags that have been added to buf-
ferid.
buffer find ?options?
Searches all the existing buffers for a buffer or buffers
matching the given parameters. If the -unique option is
specified, a single bufferid is returned. Otherwise, a list
of all matching bufferid's is returned. Valid parameters
are:
-minsize
The minimum size of a buffer that should match, in
bytes
-maxsize
The maximum size of a buffer that should match, in
bytes
-shared
Whether buffers that match should be in shared
memory (if the value is true) or the application
heap (if the value is false).
-xattach
Whether buffers that match should be attached to
the X server.
-state
Match only buffers in the given state.
-tag
Match only buffers that contain this tag
buffer findOrCreate ?options?
Operates in a similar fashion to the find command, but if a
matching buffer is not found, an appropriate buffer is
created, with the state set to free. Valid options are the
same as those for the find command.
buffer attach bufferid
Increments the reference count on the buffer identified by
bufferid. If a particular buffer is going to be passed
between objects, the first action that the object that
creates the buffer takes should be to attach to it.
buffer detach bufferid
Decrements the reference count on the buffer identified by
bufferid. When the count reaches 0, the buffer is freed.
It is freed by calling the callback routine that set through
the configure command, or by setting the state to free if a
callback has not been set.
KEYWORDS
cm, cmt, buffer
AUTHOR
Andrew Swan (aswan@CS.Berkeley.EDU)