easyPVA C++ Overview

Introduction

EasyPVA is a synchronous API for accessing PVData via PVAccess. It also provides a number of convience methods. It allows the client to request access without checking for failure, but throws an exception when a reuest fails. A client can also check for failues and thus prevent failures.

The EasyPVA API has the following features:

Provides a synchronous API rather than the callback API provided by pvAccess.
Makes common requests easy.
Provides full access to the pvAccess API for more demanding applications
Allows efficient client side programs.
Takes care of most object resource management problems.

Simple examples of using easyPVA:

// easyGet
EasyPVAPtr easyPVA = EasyPVA::create();
double value = easyPVA->channel("exampleDouble")->get()->getData()->getDouble();

// easyPut
EasyChannelPtr channel = easyPVA->channel("exampleDouble");
EasyPutPtr put = channel->put();
EasyPutDataPtr putData = put->getData();
putData->putDouble(3.0); put->put();

// easyMonitor
EasyMonitorPtr monitor = easyPVA->channel("examplePowerSupply")->monitor("");
EasyMonitorDataPtr easyData = monitor->getData();
while(true) {
    monitor->waitEvent();
    cout << "changed\n";
    easyData->showChanged(cout);
    cout << "overrun\n";
    easyData->showOverrun(cout);
    monitor->releaseEvent();
}

// easyProcess
EasyChannelPtr channel = easyPVA->channel("exampleDouble");
EasyProcessPtr process = channel->createProcess();
process->process();

EasyPVA

An instance of EasyPVA is obtained via the call:

EasyPVAPtr easyPVA = EasyPVA::create();

EasyPVA has methods to create instances of EasyChannel. The client can specify the provider name or use the default provider. The client can manage it's own channels or can let easyPVA cache channels. An example of using the cache method is:

string channelName("exampleDouble");
EasyChannelPtr easyChannel = easyPVA->channel(channelName);

This will attempt to connect to channel exampleDouble. Since the client did not specify a timeout an exception wll be thrown if the connection request fails. The client will block until the connection is made or an exception is thrown. If the request succeeds, easyPVA caches the easyChannel so that if the client makes another request for the same channel the cached object is returned to the client.

An example of using a non cached method is:

string channelName("exampleDouble");
EasyChannelPtr easyChannel = easyPVA->createChannel(channelName);

This will create an EasyChannel and return it to the client. The client must itself connect. This is useful if the client wants to connect to multiple channels in parallel.

EasyChannel - Wrapper For Single Channel

EasyChannel

This provides methods for connecting to a channel and for creating instances of EasyField, EasyProcess, ..., EasyRPC.

Connection must be made before any crete method is called or an exception is raised. The following is a synchronous connection request:

easyChannel->connect(5.0); // BLOCKS

This blocks until then connection is made or until timout occurs. An exception is raised if the connection request fails.

The same request can be made without blocking and without exceptions.

easyChannel->issueConnect(); // DOES NOT BLOCK
.....
Status status =easyChannel->waitConnect(5.0);  // BLOCKS
if(!status.isOK()) {
   // failure do something
}

Once the channel is connected other Easy objects can be created. For example:

EasyGetPtr easyGet = easyChannel->get(); // DOES BLOCK

This is a caching request. If the client already has made an identical request the client will receive the cached object. If a new easyGet is created than it is connected before it is returned to the client.

The client can also managed it's own objects:

EasyGetPtr easyGet = easyChannel->createGet(); // DOES NOT BLOCK

The client must connect the easyGet.

EasyGetData

This provides the data returned by easyGet and easyPutGet. It is obtained via:

EasyGetDataPtr easyData = easyGet->getData();

It provides methods to get everything returned by channelGet. In addition there are methods that make it easier to handle a value field that is a scalar or a scalarArray. Also for a scalar that is a double or a scalarArray with element type double.

An example is:

double value = easyData->getDouble();

It also keeps a bitSet showing which fields have changed since the last channelGet or channelPutGet.

EasyMonitorData

To the client this looks identical to EasyGetData except that it provides two BitSets: changedBitSet and overrrunBitSet. It is used by easyMonitor.

EasyPutData

This is used to provided data for easyPut and easyPutGet. It has many of the same methods as easyGetData. It does not have a bitSet. It also has put methods like:

void easyData->putDouble(5.0);

EasyGet

This provides methods to connect to channelGet and to issue get request. To connect via a single synchronous call:

eastGet->connect();  // BLOCKS

This can also be done in two steps:

easyGet->issueConnect(); // DOES NOT BLOCK
...
Status status = easyGet->waitConnect(); // BLOCKS

Once connected gets are issued via either:

void easyGet->get();

easyGet->issueGet(); // DOES NOT BLOCK
...
Status status = easyGet->waitGet(); // BLOCKS

EasyPut

This is similar to easyGet except that it wraps channelPut instead of channelGet.

Once connected puts are issued via either:

void easyPut->put();

easyPut->issuePut(); // DOES NOT BLOCK
...
Status status = easyPut->waitPut(); // BLOCKS

EasyMonitor

Connecting is similar to easyGet and easyPut. The other methods are:

start: Starts monitoring
stop: Stops monitoring
poll: polls for a monitorEvent. The data is avalable via easyMonitorData.
releaseEvent: Release the data from the last poll. Note that this must be called before another poll is requested.
waitEvent: Block until a monitorEvent is available. If true is returned a poll has already been issued.
setRequester: A client callback is registered to receive notice of monitorEvents.

EasyProcess

Connecting is similar to easyGet. It has methods:

process: call issueProcess and waitProcess.
issueProcess: call channelProcess->process() and return immediately.
waitProcess: Wait for process to complete.

EasyPutGet