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)