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 delete 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 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.
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.
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. This is returned as a Tcl list that has the following elements:
sizeThe number of data bytes in the ring buffer.
putAvailableThe 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
maxConsumersReturns the maximum number of clients that can connect to the ring buffer at any given time.
producerThe PID of the producer process. This is -1 if there is no producer.
maxGetThe amount of data that can be gotten without blocking by the consumer that is most caught up. (maximum that can be gotten by any consumer). If no consumers are connected, this returns 0.
minGet
Same as for maxGet but gives
the amount of data that can be gotten by the
consumer that is least caught up.
consumersThis 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.
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.