CRingAccess

Name

CRingAccess -- Remote Ring Access

Synopsis


#include <CRemoteAccess.h>
         
 class CRingAccess {

  static size_t setProxyRingSize(size_t newSize);
  static size_t getProxyRingSize();
  static size_t setProxyMaxConsumers(size_t newMax);
  static size_t getProxyMaxConsumers();
  static size_t setMinData(size_t minData);
  static size_t getMinData();
  static unsigned setTimeout(unsigned newTimeout);
  static unsigned getTimeout();
  static CRingBuffer* daqConsumeFrom(std::string uri);
}

Description

This class provides a unified way to get consumer access to ring buffer data in both local and remote systems. Producer access must always be to a local system and use the CRingBuffer class.

The class uses a proxy ring buffer scheme to minimize the network traffic required to serve the needs of clients in remote rings, as well as to make the programmatic interfaces consistent for both cases. The first time a client requires data from a specific remote ring, the system creates a local ring that is a combinatin of the remote host name and the remote ringname (speficially spdaq20's daq ringbuffer will have a proxy named spdaq20.daq). The software transparently interacts with the remote system's RingMaster process to arrange for data to be hoisted from the remote ring to the local proxy ring.

All clients are subsequently simply attached to the proxy ring. Once attached, clients make normal ring buffer calls from CRingBuffer to get data, and the ring is pratically indistinguishable from a remote ring.

URI's are used to provide a naming scheme to specify hostnames and ring buffer names. A ring buffer URI will be of the form: tcp://hostname/ringname. If hostname is identical to localhost, the ring buffer is assumed to be local and no proxy is created. Note that using the host's hostname does create a proxy ring, and is less efficient than using localhost.

The chapter: Networed Ring Buffer Access includes sample code for detecting and mapping the use of a system's hostname into localhost.

Public member functions

Note that all member functions are static and therefore do not require an object. See EXAMPLES below.

static size_t setProxyRingSize(size_t newSize);

When the software creates a proxy ring, it uses a ring data size stored in static data. This function sets the ring data size for proxy rings that will be subsequently created to newSize. The function returns the prior ring size.

Note that setting this value and then forming a connection to a remote ring does not ensure the proxy ring will have the requested size as the proxy ring might have already been created by another application's connection to that ring.

static size_t getProxyRingSize();

Returns the current proxy ring size parameter.

static size_t setProxyMaxConsumers(size_t newMax);

Specifies newMax to be the maximum number of concurrent consumers that can attacht to new proxy rings created by this application in the future. Note that a proxy ring counts as a single consumer for the original target ring in the remote system regardless of how many consumers are connected to the proxy ring.

See the comments in setProxyRingSize as the same caveats apply. The function returns the prior value of this configuration parameter.

static size_t getProxyMaxConsumers();

Returns the current application value of the parameter that controls the maximum number of consumers that can connect to a new proxy ring.

static size_t setMinData(size_t minData);

Sets the value for new proxy ring's stdintoring --mindata value to minData. Returns the previous value.

static size_t getMinData();

Returns the value of the parameter that sets the --mindata for stdintoring for new proxy rings.

static unsigned setTimeout(unsigned newTimeout);

Sets the value of the --timeout parameter for the stdintoring associated with new proxy rings to newTimeout. The function returns the previous value of this parameter.

static unsigned getTimeout();

Returns the value that will be given to the --timeout option for the stintoring that will be created as the producer for new proxy rings.

static CRingBuffer* daqConsumeFrom(std::string uri);

The core method of this class. Attempts to form a connection to the ring specified by uri. If the URI is a local ring, the application will connect directly to that ring. If not, proxy rings will be used as documented in DESCRIPTION above.

The return value is a pointer to a CRingBuffer that can be used to accept data from the ring.

Exceptions

Exceptions are used to signal all errors. Most exceptions thrown will be CErrnoException objects. The remaining wil be some other form of CException, or string exception objects.

EXAMPLES

The first example connects to a local ring buffer named daq.

Example 1. Using CRingAccess to connect to a local ring.


#include <CRemoteAccess>
...

CRingBuffer* pRing = CRingAccess::daqConsumeFrom("tcp://localhost/daqring");
...
            

Example 2. Using CRingAccess to connect to a remote ring


#include <CRemoteAccess>
...

CRingBuffer* pRing =
     CRingAccess::daqConsmeFrom("tcp://spdaq22.nscl.msu.edu/daqring");
...