# PvaClient

## Overview

pvaClient is a synchronous wrapper for the pvAccess API, which is a callback based API. Thus it is easier to use than pvAccess itself. In addition pvaClient provides many convenience methods.

Class PvaClient is a class that is used by all the other pvaClient classes. An application that uses pvaClient must call:

    PvaClientPtr pvaClient = PvaClient::get(providers);

before it uses any other pvaClient classes.

This is a singleton method, i. e. only one instance of PvaClient is created.

pvaClient must not be deleted until the client no longer wants to use any part of pvaClient.

providers is a blank separated set of provider names. For example:

    PvaClientPtr pvaClient = PvaClient::get("ca pva");

The providers ca and pva are special. For each of these a client context is created when the PvaClient is constructed and the context destroyed when PvaClient is deleted.

## Channel Caching

PvaClient has a method:

    PvaClientChannelPtr channel(
        string const & channelName,
        string const &providerName = "pva",
        double timeOut = 5.0);

This method creates a PvaClientChannel and then connects to the channel.

If a call is successful then multiple calls to the same channelName and providerName share the same PvaClientChannel, i. e. the PvaClientChannel is cached.

pvaClientChannelGet and pvaClientChannelPut also implement caching.

For example consider a client that makes multiple calls like:

    double value;
    value =  pva->channel(channelName)->get()->getData()->getDouble();
    ...
    value =  pva->channel(channelName)->get()->getData()->getDouble();

Only the first call creates a new PvaClientChannel and a new PvaClientGet. The second call reuses the cached PvaClientChannel and PvaClientGet.

## Non Cached Channels

PvaClient has a method:

    PvaClientChannelPtr createChannel(
        string const & channelName,
        string const &providerName = "pva");

This method is just creates a new PvaClientChannel and returns it to the caller. The caller must call the PvaClientChannel connect methods.

## Blocking vs Non-Blocking Methods

Each component of pvaClient provides a set of blocking and non-blocking calls. For example several components (examples are PvaClientChannel and PvaChannelGet) have methods:

connect
  This calls issueConnect and then waitConnect. If waitConnect fails an exception is thrown. Since waitConnect is a blocking method so is this.
issueConnect
  This is a request to connect, i. e. issue a request to the server to create something on the server. This is a non blocking call.
waitConnect
  This waits for the server to respond to issueConnect. It blocks until the server responds or a timeout occurs.