ringbuffer create ?--datasize=n? ?--maxconsumers=n? name
ringbuffer format ?--maxconsumers=n? name
ringbuffer delete name
ringbuffer status ?--host=hostname? ?--all? ?--user=user1?,...?? ?pattern?
ringbuffer list ?--host=hostname?
The ringbuffer command is an ensemble of commands that manipulate NSCL ring buffers. A command ensemble is a single command that has subcommands. The subcommands determine what is actually done. See ENSEMBLE COMMANDS for a description of each ensemble subcommand.
Creates a new ring buffer. The name
parameter is mandatory and is the name of the new ring buffer.
The ringbuffer name must not have any /
characters embedded in it. Since the
ringbuffer command is actually a
Tcl script it's probably a good
idea to avoid characters that have special meaning to Tcl
as well.
Formats the header of the ring buffer name
.
name
must already exist.
If provided, the value of the optional option
--maxconsumers
determines how many
consumers can simultaneously connect to the ring buffer.
Marks the ring buffer
name
for deletion.
name
immediately is no longer available for new attachments.
Once all existing attached clients have detached, the
ring buffer shared memory region will be deleted.
Outputs the status of all active ring buffers that match
pattern
to stdout. If pattern
is not supplied, it defaults to * which
matches the names of all ring buffers. Note that if you use
patterns with wildcards you should quote the pattern to
suppress the command shell's attempts to do file name
expansions. Note that a ring buffer is active if it has
attached clients.
If the --host
option is supplied, its value
is the name of the system whose ring buffers are inquired.
This defaults to localhost.
When either --host
is not supplied or its
value is
localhost, the --all
and --user
options can filter the set of
rings that will be present in the output table.
By defafult, only rings the user 'owns' will be shown. Note
that proxy rings are normally owned by root and therefore
won't be shown by default.
If the --all
switch is supplied, or
--host
is not localhost, all rings will
be listed. Remote ring lists cannot be filtered at this time
because filtering is performed by observing the owner of the
shared memory special file and that cannot be done simply
for remote rings. In the future, extensions to the ring
master protocol may support this filtering.
If supplied, the value of --user
must be
a comma separated list of usernames. Only rings whose owners
are in that list will be displayed. If both --user
and --all
are explicitly specified, an
error is signalled.
Note that since proxy rings are owned by root, it is not possible to restrict the listing to the set of proxy rings that are associated with specific users. The command below, therefore lists all rings owned by the current user and all proxy rings:
The ring buffer status is listed in tabular form. Here is some sample output:
Example 1. Sample output from ringbuffer status
+------+------------+-------+-------------+--------+---------+---------+------+-------------+ |Name |data-size(k)|free(k)|max_consumers|producer|maxget(k)|minget(k)|client|clientdata(k)| +------+------------+-------+-------------+--------+---------+---------+------+-------------+ |timing|8195 |6147 |100 |22311 |2048 |2048 |- |- | |- |- |- |- |- |- |- |22281 |2048 | |- |- |- |- |- |- |- |22297 |2048 | +------+------------+-------+-------------+--------+---------+---------+------+-------------+
The Name column gives the name of a ring buffer. The remaining line provides information about the ring buffer and any consumer it may have. Subsequent lines provide information about consumers.
Information provided about the ring buffer includes data-size(k) the size of the data area in kilobytes. free the number of kilobytes the producer can put without blocking. max_consumers the maximum number of consumers that can connect to the ring. producer the PID of the producer process, which is -1 if there is no producer. maxget(K) the amount of data available for the consumer that is furthest behind in consuming data in kilobytes. minget the amount of data avilable to the consumer that is most caught up in kilobytes.
Subsequent lines of the table provide the process id of a client and the numuber of kilobytes of un-consumed data for the client (clientdata(k)) in kilobytes.
Lists the names of the active ringbuffers one per line to stdout.
By default the ring buffers active in localhost
are listed. Using the --host
option allows
you to specify a different host. Active ring buffers are only
those that have clients attached.