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.
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 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:
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 least 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 most 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.
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.
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.