ringbuffer

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:

ringbuffer status --user=`whoami`,root
		  

The ring buffer status is listed in tabular form. Here is some sample output:

+------+------------+-------+-------------+--------+---------+---------+------+-------------+
|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.