TCL Ring package. Ron Fox NSCLDAQ


ringbuffer -- Access Rings from tcl.


package require ring

ringbuffer create name ?size? ?maxconsumers??

ringbuffer format name ?maxconsumers?

ringbuffer disconnect producer name

ringbuffer disconnect consumer name index

ringbuffer usage ?name?

ringbuffer list

ringbuffer remove ringname


The ringbuffer command is a command ensemble. Command ensembles are a set of related commands that have a subcommand that actually defines the action of the command. An example of a Tcl core command ensemble is the Tcl string command.

The ringbuffer subcommands provide management access to ring buffers used for primary data flow in the NSCL data acquisition system.


ringbuffer create name ?size ?maxconsumers??

Creates a new ring buffer named name. The optional size command parameter sets the number of bytes of data storage in the ring. The maxconsumers the maximum number of simultaneously attached consumers.

ringbuffer format name ?maxconsumers?

Formats an existing ring buffer named name. Formatting a ring buffer rewrites the header in the ring buffer. The ring buffer header includes control information that describes the ring buffer as well as the put and get pointers for the producer and consumer clients. It is not safe to do this when the ring buffer is active.

The maxconsumers optional parameter sets the maximum number of consumer get pointers that will be created. If this value is larger than the original value when the ring buffer was created, the extra space is taken from the data area. If smaller, the data area will grow accordingly as well. Each consumer pointer requires a pid_t and a off_t of storage.

ringbuffer disconnect producer name

Forces a disconnect of the producer client of the ring named name. This does not actually kill any active producer client, but just marks the producer pointer as available. This is intended to be used if you suspect that a producer has exited in a way that left its put pointer marked as in use.

ringbuffer disconnect consumer name index

Forces a disconnect of a consumer client of the ring named name. The get pointer selected by index is marked as free. This should only be used if you suspect that a program has exited without freeing its client consumer ring buffer poniter.

ringbuffer usage ?name?

Returns (as the command result), the ring buffer usage information for that ring if the name is present or the usage information for all rings if not present.

If the name is given, the command result is a list containing:


The number of data bytes in the ring buffer.


The number of bytes that can be put by the producer without blocking. Note that in order to be able to distinguish between the full and empty ring buffer cases, this can never be larger than size - 1


Returns the maximum number of clients that can connect to the ring buffer at any given time.


The PID of the producer process. This is -1 if there is no producer.


The amount of data that can be gotten without blocking by the consumer that is least caught up. (maximum that can be gotten by any consumer). If no consumers are connected, this returns 0.


Same as for maxGet but gives the amount of data that can be gotten by the consumer that is most caught up.


This is a list of consumers attached to the ring buffer. Each consumer is represented by a pair of values. The first, the consumer's pocess ID. The second, the amount of data that consumer could get without blocking.

If the name is not provided, the result is a list that describes the characteristics and usage of all rings. Each element of the list is a sublist containing:


The name of the ring.


Size of the ring buffer part of the ring shared memory region in bytes.

Free space

Number of bytes of free space in the ring. This is the size of the largest possible put into the ring at this instant in time.


The process id of the producer or -1 if there is no producer for this ringbuffer.

Maximum available.

The size of the backlog in bytes for the consumer that is least caught up.

Minimum Available

The size of the backlog in bytes for the consumer that is most caught up.

Consumer information

This is a list containing one element per currently attached consumer. The elements themselves are two element lists containing in order the PID of the consumer and the size of that consumer's backlog in bytes.


Provides a Tcl formatted list containing the names of the existing rings.

ringbuffer removering

Deletes the shared memory region associated with the ring buffer ring. When the last client detaches from the ring buffer, the ring buffer will cease to exist. This makes the semantics of this operation very much like that of the Unix rm command.