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 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.
Creates a new ring buffer named
size command parameter
sets the number of bytes of data storage in the ring. The
maxconsumers the maximum number of
simultaneously attached consumers.
Formats an existing ring buffer named
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.
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.
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.
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.
Returns (as the command result), the ring buffer usage
information for that ring if the
present or the usage information for all rings if not present.
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.
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.
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.
The size of the backlog in bytes for the consumer that is least caught up.
The size of the backlog in bytes for the consumer that is most caught up.
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.
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.