CRingMaster Ron Fox NSCLDAQ

Name

CRingMaster -- RingMaster access.

Synopsis


#include <CRingMaster.h>
         

         class CRingMaster {
            
  CRingMaster(std::string host = std::string("localhost"));
            
  virtual ~CRingMaster();
            
  void notifyConsumerConnection(std::string ringname, int id, std::string comment);
              void notifyProducerConnection(std::string ringname, std::string comment);
              void notifyConsumerDisconnection(std::string ringname, int slot);
              void notifyProducerDisconnection(std::string ringname);
              void notifyCreate(std::string ringname);
              void notifyDestroy(std::string ringname);
              int requestData(std::string ringname);
                std::string requestUsage();
    
         }
         

Description

This class provides simple member functions to communicate with a remote ring master. Constructing an object forms the connection to the ring master, while destroying the object closes the connection. Note that in most case, application code will not need to manipulate CRingMaster objects. They are transparently manipulated by CRingBuffer and CRingAccess objects on behalf of the application.

Public member functions

CRingMaster(std::string host = std::string("localhost"));

Constructs a CRingMaster object. This forms a connection to the RingMaster server running in host. If the host parameter is not supplied, it defaults to connecting to the ring master in the local host.

virtual ~CRingMaster();

Destruction closes the ring master socket. Note that the RingMaster will release all outstanding ring consumer and producer registrations when this happens. The CRingBuffer class therefore maintains a single common CRingMaster object for the life of the application.

void notifyConsumerConnection(std::string ringname, int id, std::string comment);

Interacts with the RingMaster to inform it that the application has attached to a ring as a consumer. The CRingBuffer class does this transparently. This method will fail if the connection is not to the the local ring master. Note that local means the host name on the constructor was localhost. ringname specifies the name and id the consumer slot. comment is just a documentation comment.

void notifyProducerConnection(std::string ringname, std::string comment);

Notifies the ring master that a the application has become the producer for a ring. This is done transparently by the CRingBuffer constructor if the connection specified is CRingBuffer::producer. This method will fail if the CRingMaster object is not connected to the server on localhost. ringname is the name of the ring attached, comment is just a documentation comment.

void notifyConsumerDisconnection(std::string ringname, int slot);

Interacts with the ring master to indicate that the application has released a consumer connection to a ring buffer. ringname is the name of the ring, and slot is the ring buffer consumer slot number being released. CRingBuffer will automatically call this member function when a consumer object is destroyed. Furthermore, if the CRingMaster object is destroyed (including on application exit), the server will release any ring buffer consumer and producer resources that are still held that were notified by that CRingMaster object.

void notifyProducerDisconnection(std::string ringname);

Releases the producer resources for ringname. A CRingBuffer object that is a producer connection will transparently call this to release the ring. If the CRingMaster object is destroyed (including on application exit), the server will release any ring buffer consumer and producer resources that are still held that were notified by that CRingMaster object.

void notifyCreate(std::string ringname);

Notifies the RingMaster server that a new ring; ringname has been created. This is transparently called by the CRingBuffer::create member.

void notifyDestroy(std::string ringname);

Informs the RingMaster that a ring named ringname has been destroyed. This is normally called transparently by CRingBuffer::remove. Ring buffers persist beyond the lifetime of the creating process, and even across reboots.

int requestData(std::string ringname);

Requests data from a ring ringname that is local to the RingMaster this object is connected to. The function returns a socket file descriptor along which the data will be transmitted. The RingMaster treats this like disconnection from the object. Further requests will most likely result in error, it is best to destroy this object once this method returns successfully.

std::string requestUsage();

Requests usage information from the RingMaster. This is returned as a, possibly empty, proper Tcl list with one element per ring. Each list itself is a sublist which contains in order:

name

The name of the ring.

size

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.

Producer

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.