pvac::ClientChannel Class Reference

#include "client.h"

Classes
struct	ConnectCallback
	Connection state change CB. More...
struct	GetCallback
	callback for get() and rpc() More...
struct	Impl
struct	InfoCallback
struct	MonitorCallback
	Monitor event notification. More...
struct	Options
	Channel creation options. More...
struct	PutCallback
	callbacks for put() More...

Public Member Functions
	ClientChannel ()
	Construct a null channel. All methods throw. May later be assigned from a valid ClientChannel. More...
	ClientChannel (const std::tr1::shared_ptr< epics::pvAccess::ChannelProvider > &provider, const std::string &name, const Options &opt=Options())
	~ClientChannel ()
std::string	name () const
	Channel name or an empty string. More...
bool	valid () const
	operator bool_type () const
void	reset ()
Operation	get (GetCallback *cb, epics::pvData::PVStructure::const_shared_pointer pvRequest=epics::pvData::PVStructure::const_shared_pointer())
epics::pvData::PVStructure::const_shared_pointer	get (double timeout=3.0, epics::pvData::PVStructure::const_shared_pointer pvRequest=epics::pvData::PVStructure::const_shared_pointer())
Operation	rpc (GetCallback *cb, const epics::pvData::PVStructure::const_shared_pointer &arguments, epics::pvData::PVStructure::const_shared_pointer pvRequest=epics::pvData::PVStructure::const_shared_pointer())
epics::pvData::PVStructure::const_shared_pointer	rpc (double timeout, const epics::pvData::PVStructure::const_shared_pointer &arguments, epics::pvData::PVStructure::const_shared_pointer pvRequest=epics::pvData::PVStructure::const_shared_pointer())
Operation	put (PutCallback *cb, epics::pvData::PVStructure::const_shared_pointer pvRequest=epics::pvData::PVStructure::const_shared_pointer(), bool getprevious=false)
detail::PutBuilder	put (const epics::pvData::PVStructure::const_shared_pointer &pvRequest=epics::pvData::PVStructure::const_shared_pointer())
	Synchronious put operation. More...
Monitor	monitor (MonitorCallback *cb, epics::pvData::PVStructure::const_shared_pointer pvRequest=epics::pvData::PVStructure::const_shared_pointer())
MonitorSync	monitor (const epics::pvData::PVStructure::const_shared_pointer &pvRequest=epics::pvData::PVStructure::const_shared_pointer(), epicsEvent *event=0)
Operation	info (InfoCallback *cb, const std::string &subfld=std::string())
epics::pvData::FieldConstPtr	info (double timeout=3.0, const std::string &subfld=std::string())
	Synchronious getField opreation. More...
void	addConnectListener (ConnectCallback *)
void	removeConnectListener (ConnectCallback *)
	Remove from list of listeners. More...
void	show (std::ostream &strm) const

Friends
class	ClientProvider
void	detail::registerRefTrack ()
epicsShareFunc::std::ostream &	operator<< (::std::ostream &strm, const ClientChannel &op)

Detailed Description

Represents a single channel

This class has two sets of methods, those which block for completion, and those which use callbacks to signal completion.

Those which block accept a 'timeout' argument (in seconds).

Those which use callbacks accept a 'cb' argument and return an Operation or Monitor handle object.

Definition at line 266 of file client.h.

Constructor & Destructor Documentation

pvac::ClientChannel::ClientChannel ( )

inline

Construct a null channel. All methods throw. May later be assigned from a valid ClientChannel.

Definition at line 290 of file client.h.

{}

pvac::ClientChannel::ClientChannel	(	const std::tr1::shared_ptr< epics::pvAccess::ChannelProvider > &	provider,
		const std::string &	name,
		const Options &	opt = Options()
	)

Construct a ClientChannel using epics::pvAccess::ChannelProvider::createChannel()

Does not block.

Exceptions

std::logic_error	if the provider is NULL or name is an empty string
std::runtime_error	if the ChannelProvider can't provide

pvac::ClientChannel::~ClientChannel

(

)

Definition at line 156 of file client.cpp.

{}

Member Function Documentation

void pvac::ClientChannel::addConnectListener

(

ConnectCallback *

cb

)

Append to list of listeners

Parameters

cb	Channel dis/connect notification callback. Must outlive ClientChannel or call to removeConnectListener()

Definition at line 163 of file client.cpp.

{
    if(!impl) throw std::logic_error("Dead Channel");
    ConnectEvent evt;
    {
        Guard G(impl->mutex);

        for(Impl::listeners_t::const_iterator it=impl->listeners.begin(), end=impl->listeners.end(); it!=end; ++it)
        {
            if(cb==*it) return; // no duplicates
        }
        impl->listeners.push_back(cb);
        evt.connected = impl->channel->isConnected();
    }
    try{
        cb->connectEvent(evt);
    }catch(...){
        removeConnectListener(cb);
        throw;
    }
}

Operation pvac::ClientChannel::get	(	ClientChannel::GetCallback *	cb,
		epics::pvData::PVStructure::const_shared_pointer	pvRequest = epics::pvData::PVStructure::const_shared_pointer()
	)

Issue request to retrieve current PV value

Parameters

cb	Completion notification callback. Must outlive Operation (call Operation::cancel() to force release)
pvRequest	if NULL defaults to "field()".

Definition at line 151 of file clientGet.cpp.

{
    if(!impl) throw std::logic_error("Dead Channel");
    if(!pvRequest)
        pvRequest = pvd::createRequest("field()");

    std::tr1::shared_ptr<Getter> ret(Getter::build(cb));

    {
        Guard G(ret->mutex);
        ret->op = getChannel()->createChannelGet(ret->internal_shared_from_this(),
                                                 std::tr1::const_pointer_cast<pvd::PVStructure>(pvRequest));
    }

    return Operation(ret);
}

epics::pvData::PVStructure::const_shared_pointer pvac::ClientChannel::get	(	double	timeout = 3.0,
		epics::pvData::PVStructure::const_shared_pointer	pvRequest = epics::pvData::PVStructure::const_shared_pointer()
	)

Block and retrieve current PV value

Parameters

timeout	in seconds
pvRequest	if NULL defaults to "field()".

Exceptions

Timeout

or std::runtime_error

Operation pvac::ClientChannel::info	(	InfoCallback *	cb,
		const std::string &	subfld = std::string()
	)

Request PV type info.

Note

This type may not be the same as the types used in the get/put/monitor operations.

Definition at line 99 of file clientInfo.cpp.

{
    if(!impl) throw std::logic_error("Dead Channel");

    std::tr1::shared_ptr<Infoer> ret(Infoer::build(cb, getChannel()));

    {
        Guard G(ret->mutex);
        getChannel()->getField(ret, subfld);
        // getField is an oddity as it doesn't have an associated Operation class,
        // and is thus largely out of our control.  (eg. can't cancel)
    }

    return Operation(ret);
}

epics::pvData::FieldConstPtr pvac::ClientChannel::info	(	double	timeout = 3.0,
		const std::string &	subfld = std::string()
	)

Synchronious getField opreation.

Definition at line 407 of file clientSync.cpp.

{
    InfoWait waiter;
    {
        Operation op(info(&waiter, subfld));
        waiter.wait(timeout);
    }
    switch(waiter.result.event) {
    case InfoEvent::Success:
        return waiter.result.type;
    case InfoEvent::Fail:
        throw std::runtime_error(waiter.result.message);
    default:
    case InfoEvent::Cancel: // cancel implies timeout, which should already be thrown
        THROW_EXCEPTION2(std::logic_error, "Cancelled!?!?");
    }
}

Monitor pvac::ClientChannel::monitor	(	MonitorCallback *	cb,
		epics::pvData::PVStructure::const_shared_pointer	pvRequest = epics::pvData::PVStructure::const_shared_pointer()
	)

Begin subscription

Parameters

cb	Completion notification callback. Must outlive Monitor (call Monitor::cancel() to force release)

Definition at line 241 of file clientMonitor.cpp.

{
    if(!impl) throw std::logic_error("Dead Channel");
    if(!pvRequest)
        pvRequest = pvd::createRequest("field()");

    std::tr1::shared_ptr<Monitor::Impl> ret(Monitor::Impl::build(cb));
    ret->chan = getChannel();

    {
        Guard G(ret->mutex);
        ret->op = ret->chan->createMonitor(ret->internal_shared_from_this(),
                                           std::tr1::const_pointer_cast<pvd::PVStructure>(pvRequest));
    }

    return Monitor(ret);
}

MonitorSync pvac::ClientChannel::monitor	(	const epics::pvData::PVStructure::const_shared_pointer &	pvRequest = epics::pvData::PVStructure::const_shared_pointer(),
		epicsEvent *	event = 0
	)

Begin subscription w/o callbacks

Parameters

event

If not NULL, then subscription events are signaled to this epicsEvent. Use MonitorSync::test() to see if a subscription has an event waiting. Otherwise an internal epicsEvent is allocated for use with MonitorSync::wait()

Note

For simple usage with a single MonitorSync, pass event=NULL and call MonitorSync::wait(). If more than one MonitorSync is being created, then pass a custom epicsEvent and use MonitorSync::test() to find which subscriptions have events pending.

Definition at line 371 of file clientSync.cpp.

{
    std::tr1::shared_ptr<MonitorSync::SImpl> simpl(new MonitorSync::SImpl(event));
    Monitor mon(monitor(simpl.get(), pvRequest));
    return MonitorSync(mon, simpl);
}

std::string pvac::ClientChannel::name

(

)

const

Channel name or an empty string.

Definition at line 158 of file client.cpp.

{
    return impl ? impl->channel->getChannelName() : std::string();
}

pvac::ClientChannel::operator bool_type ( ) const

inline

Definition at line 313 of file client.h.

{ return valid() ? &ClientChannel::valid : 0; }

Operation pvac::ClientChannel::put	(	PutCallback *	cb,
		epics::pvData::PVStructure::const_shared_pointer	pvRequest = epics::pvData::PVStructure::const_shared_pointer(),
		bool	getprevious = false
	)

Initiate request to change PV

Parameters

cb	Completion notification callback. Must outlive Operation (call Operation::cancel() to force release)
pvRequest	if NULL defaults to "field()".
getprevious	If true, fetch a previous value of the PV and make this available as PutCallback::Args::previous and previousmask. If false, then previous=NULL

Definition at line 211 of file clientPut.cpp.

{
    if(!impl) throw std::logic_error("Dead Channel");
    if(!pvRequest)
        pvRequest = pvd::createRequest("field()");

    std::tr1::shared_ptr<Putter> ret(Putter::build(cb, getprevious));

    {
        Guard G(ret->mutex);
        ret->op = getChannel()->createChannelPut(ret->internal_shared_from_this(),
                                                 std::tr1::const_pointer_cast<pvd::PVStructure>(pvRequest));
    }

    return Operation(ret);

}

void pvac::ClientChannel::removeConnectListener

(

ConnectCallback *

cb

)

Remove from list of listeners.

Definition at line 185 of file client.cpp.

{
    if(!impl) throw std::logic_error("Dead Channel");
    Guard G(impl->mutex);

    // ensure no in-progress callbacks
    while(impl->listeners_inprogress) {
        UnGuard U(G);
        impl->listeners_done.wait();
    }

    for(Impl::listeners_t::iterator it=impl->listeners.begin(), end=impl->listeners.end(); it!=end; ++it)
    {
        if(cb==*it) {
            impl->listeners.erase(it);
            return;
        }
    }
}

void pvac::ClientChannel::reset ( )

inline

Definition at line 316 of file client.h.

{ impl.reset(); }

Operation pvac::ClientChannel::rpc	(	GetCallback *	cb,
		const epics::pvData::PVStructure::const_shared_pointer &	arguments,
		epics::pvData::PVStructure::const_shared_pointer	pvRequest = epics::pvData::PVStructure::const_shared_pointer()
	)

Start an RPC call

Parameters

cb	Completion notification callback. Must outlive Operation (call Operation::cancel() to force release)
arguments	encoded call arguments
pvRequest	if NULL defaults to "field()".

Definition at line 158 of file clientRPC.cpp.

{
    if(!impl) throw std::logic_error("Dead Channel");
    if(!pvRequest)
        pvRequest = pvd::createRequest("field()");

    std::tr1::shared_ptr<RPCer> ret(RPCer::build(cb, arguments));

    {
        Guard G(ret->mutex);
        ret->op = getChannel()->createChannelRPC(ret->internal_shared_from_this(),
                                                 std::tr1::const_pointer_cast<pvd::PVStructure>(pvRequest));
    }

    return Operation(ret);
}

pvd::PVStructure::const_shared_pointer pvac::ClientChannel::rpc	(	double	timeout,
		const epics::pvData::PVStructure::const_shared_pointer &	arguments,
		epics::pvData::PVStructure::const_shared_pointer	pvRequest = epics::pvData::PVStructure::const_shared_pointer()
	)

Block and execute remote call

Parameters

timeout	in seconds
arguments	encoded call arguments
pvRequest	if NULL defaults to "field()".

Definition at line 91 of file clientSync.cpp.

{
    GetWait waiter;
    Operation op(rpc(&waiter, arguments, pvRequest));
    {
        Guard G(waiter.mutex);
        while(!waiter.done) {
            UnGuard U(G);
            if(!waiter.event.wait(timeout)) {
                op.cancel();
                throw Timeout();
            }
        }
    }
    if(waiter.result.event==pvac::GetEvent::Success)
        return waiter.result.value;
    else
        throw std::runtime_error(waiter.result.message);
}

void pvac::ClientChannel::show

(

std::ostream &

strm

)

const

Definition at line 206 of file client.cpp.

{
    if(impl) {
        strm<<typeid(*impl->channel.get()).name()<<" : ";
        impl->channel->printInfo(strm);
    } else {
        strm<<"NULL Channel";
    }
}

bool pvac::ClientChannel::valid ( void  ) const

inline

Definition at line 305 of file client.h.

{ return !!impl; }

Friends And Related Function Documentation

friend class ClientProvider

friend

Definition at line 275 of file client.h.

void detail::registerRefTrack ( )

friend

epicsShareFunc ::std::ostream& operator<< ( ::std::ostream &  strm, const ClientChannel &  op  )

friend

Definition at line 346 of file client.cpp.

{
    if(op.impl) {
        strm << "ClientChannel("
             << typeid(*op.impl->channel.get()).name()<<", "
                "\"" << op.impl->channel->getChannelName() <<"\", "
                "\"" << op.impl->channel->getProvider()->getProviderName() <<"\", "
                "connected="<<(op.impl->channel->isConnected()?"true":"false")
             <<"\")";
    } else {
        strm << "ClientChannel()";
    }
    return strm;
}

---

The documentation for this class was generated from the following files:

• modules/pvAccess/src/client/pva/client.h
• modules/pvAccess/src/client/client.cpp
• modules/pvAccess/src/client/clientGet.cpp
• modules/pvAccess/src/client/clientInfo.cpp
• modules/pvAccess/src/client/clientMonitor.cpp
• modules/pvAccess/src/client/clientPut.cpp
• modules/pvAccess/src/client/clientRPC.cpp
• modules/pvAccess/src/client/clientSync.cpp