Classes
class	pvas::StaticProvider
	A Provider based on a list of SharedPV instance. More...

class	pvas::DynamicProvider
	A Provider which has no pre-configured list of names. More...

struct	pvas::SharedPV::Config

struct	pvas::SharedPV::Handler

class	pvas::SharedPV

struct	pvas::Operation

Functions
	pvas::SharedPV::POINTER_DEFINITIONS (SharedPV)

	pvas::SharedPV::Config::Config ()

	pvas::SharedPV::Handler::POINTER_DEFINITIONS (Handler)

virtual	pvas::SharedPV::Handler::~Handler ()

virtual void	pvas::SharedPV::Handler::onFirstConnect (const SharedPV::shared_pointer &pv)

virtual void	pvas::SharedPV::Handler::onLastDisconnect (const SharedPV::shared_pointer &pv)
	Called when the last client disconnects. May close() More...

virtual void	pvas::SharedPV::Handler::onPut (const SharedPV::shared_pointer &pv, Operation &op)
	Client requests Put. More...

virtual void	pvas::SharedPV::Handler::onRPC (const SharedPV::shared_pointer &pv, Operation &op)
	Client requests RPC. More...

static shared_pointer	pvas::SharedPV::build (const std::tr1::shared_ptr< Handler > &handler, Config *conf=0)

static shared_pointer	pvas::SharedPV::buildReadOnly (Config *conf=0)
	A SharedPV which fails all Put and RPC operations. In closed state. More...

static shared_pointer	pvas::SharedPV::buildMailbox (Config *conf=0)
	A SharedPV which accepts all Put operations, and fails all RPC operations. In closed state. More...

virtual	pvas::SharedPV::~SharedPV ()

void	pvas::SharedPV::setHandler (const std::tr1::shared_ptr< Handler > &handler)
	Replace Handler given with ctor. More...

Handler::shared_pointer	pvas::SharedPV::getHandler () const

bool	pvas::SharedPV::isOpen () const
	test open-ness. cf. open() and close() More...

void	pvas::SharedPV::open (const epics::pvData::PVStructure &value)
	Shorthand for. More...

void	pvas::SharedPV::open (const epics::pvData::PVStructure &value, const epics::pvData::BitSet &valid)

void	pvas::SharedPV::open (const epics::pvData::StructureConstPtr &type)
	Shorthand for. More...

void	pvas::SharedPV::close (bool destroy=false)

std::tr1::shared_ptr< epics::pvData::PVStructure >	pvas::SharedPV::build ()

void	pvas::SharedPV::post (const epics::pvData::PVStructure &value, const epics::pvData::BitSet &changed)

void	pvas::SharedPV::fetch (epics::pvData::PVStructure &value, epics::pvData::BitSet &valid)
	Update arguments with current value, which is the initial value from open() with accumulated post() calls. More...

virtual std::tr1::shared_ptr< epics::pvAccess::Channel >	pvas::SharedPV::connect (const std::tr1::shared_ptr< epics::pvAccess::ChannelProvider > &provider, const std::string &channelName, const std::tr1::shared_ptr< epics::pvAccess::ChannelRequester > &requester) OVERRIDE FINAL

virtual void	pvas::SharedPV::disconnect (bool destroy, const epics::pvAccess::ChannelProvider *provider) OVERRIDE FINAL

void	pvas::SharedPV::setDebug (int lvl)

int	pvas::SharedPV::isDebug () const

	pvas::Operation::POINTER_DEFINITIONS (Operation)

	pvas::Operation::Operation ()
	create empty op for later assignment More...

const epics::pvData::PVStructure &	pvas::Operation::pvRequest () const
	pvRequest blob, may be used to modify handling. More...

const epics::pvData::PVStructure &	pvas::Operation::value () const

const epics::pvData::BitSet &	pvas::Operation::changed () const
	Applies to value(). Which fields of input data are actual valid. Others should not be used. More...

std::string	pvas::Operation::channelName () const
	The name of the channel through which this request was made (eg. for logging purposes). More...

const epics::pvAccess::PeerInfo *	pvas::Operation::peer () const

void	pvas::Operation::complete ()

void	pvas::Operation::complete (const epics::pvData::Status &sts)
	Complete with success or error w/o data. More...

void	pvas::Operation::complete (const epics::pvData::PVStructure &value, const epics::pvData::BitSet &changed)
	Sucessful completion with data (RPC only) More...

void	pvas::Operation::info (const std::string &)
	Send info message to client. Does not complete(). More...

void	pvas::Operation::warn (const std::string &)
	Send warning message to client. Does not complete(). More...

int	pvas::Operation::isDebug () const

std::tr1::shared_ptr< epics::pvAccess::Channel >	pvas::Operation::getChannel ()

std::tr1::shared_ptr< epics::pvAccess::ChannelBaseRequester >	pvas::Operation::getRequester ()

bool	pvas::Operation::valid () const

	pvas::Operation::operator bool_type () const

Variables
bool	pvas::SharedPV::Config::dropEmptyUpdates
	default true. Drop updates which don't include an field values. More...

epics::pvData::PVRequestMapper::mode_t	pvas::SharedPV::Config::mapperMode
	default Mask. More...

Friends
struct	pvas::SharedPV::detail::SharedChannel

struct	pvas::SharedPV::detail::SharedMonitorFIFO

struct	pvas::SharedPV::detail::SharedPut

struct	pvas::SharedPV::detail::SharedRPC

struct	pvas::Operation::detail::SharedPut

struct	pvas::Operation::detail::SharedRPC

void	pvas::SharedPV::epics::pvAccess::providerRegInit (void *)

Detailed Description

PVA Server Providers, for use with a PVA epics::pvAccess::ServerContext

These are implementations of epics::pvAccess::ChannelProvider which manage "PVs", which are sources of epics::pvAccess::Channel instances. Typically SharedPV .

Two containers are provided StaticProvider, and for some special cases DynamicProvider. It is recommended to use StaticProvider where possible, with DynamicProvider for exception cases.

A StaticProvider maintains an internal lookup table of StaticProvider::ChannelBuilder (aka. SharedPV). This table is manipulated by StaticProvider::add() and StaticProvider::remove(), which can be called at any time.

A DynamicProvider does not maintain an internal lookup table. Instead it provides the DynamicProvider::Handler interface, through which remote search and connection requests are delivered.

See examples_mailbox for a working example.

namespace pva = epics::pvAccess;
pvas::SharedPV::shared_pointer pv(pvas::SharedPV::buildMailbox());
pvas::StaticProvider sprov("arbitrary");
pva::ServerContext::shared_pointer server(
   pva::ServerContext::create(
       pva::ServerContext::Config() .provider(sprov.provider()) ));
sprov->add("pv:name", pv);

Server API shared_ptr Ownership

shared_ptr<> relationships internal to server API classes. Solid red lines are shared_ptr<>. Dashed red lines are shared_ptr<> which may exist safely in user code. Rectangles are public API classes. Circles are internal classes. "ChannelProvider" is an arbitrary ChannelProvider, possibly StaticProvider or DynamicProvider.

Internal shared_ptr<> relationships.

Function Documentation

SharedPV::shared_pointer pvas::SharedPV::build	(	const std::tr1::shared_ptr< Handler > &	handler,
		Config *	conf = `0`
	)

static

Allocate a new PV in the closed state.

Parameters

handler	Our callbacks. May be NULL. Stored internally as a shared_ptr<>
conf	Optional. Extra configuration. If !NULL, will be modified to reflect configuration actually used.

Postcondition: In the closed state

Definition at line 62 of file sharedstate_pv.cpp.

 {
     assert(!!handler);
     SharedPV::shared_pointer ret(new SharedPV(handler, conf));
     ret->internal_self = ret;
     return ret;
 }

pvd::PVStructure::shared_pointer pvas::SharedPV::build ( )

Create a new container which may be used to prepare to call post(). This container will be owned exclusively by the caller.

Definition at line 318 of file sharedstate_pv.cpp.

 {
     Guard G(mutex);
     if(!type)
         throw std::logic_error("Can't build() before open()");
     return pvd::getPVDataCreate()->createPVStructure(type);
 }

SharedPV::shared_pointer pvas::SharedPV::buildMailbox ( Config * conf = 0 )

static

A SharedPV which accepts all Put operations, and fails all RPC operations. In closed state.

Definition at line 77 of file sharedstate_pv.cpp.

 {
     std::tr1::shared_ptr<Handler> handler(new MailboxHandler);
     SharedPV::shared_pointer ret(new SharedPV(handler, conf));
     ret->internal_self = ret;
     return ret;
 }

SharedPV::shared_pointer pvas::SharedPV::buildReadOnly ( Config * conf = 0 )

static

A SharedPV which fails all Put and RPC operations. In closed state.

Definition at line 70 of file sharedstate_pv.cpp.

 {
     SharedPV::shared_pointer ret(new SharedPV(std::tr1::shared_ptr<Handler>(), conf));
     ret->internal_self = ret;
     return ret;
 }

const epics::pvData::BitSet & pvas::Operation::changed ( ) const

Applies to value(). Which fields of input data are actual valid. Others should not be used.

Definition at line 288 of file sharedstate_channel.cpp.

 {
     return impl->changed;
 }

std::string pvas::Operation::channelName ( ) const

The name of the channel through which this request was made (eg. for logging purposes).

Definition at line 293 of file sharedstate_channel.cpp.

 {
     std::string ret;
     std::tr1::shared_ptr<epics::pvAccess::Channel> chan(impl->getChannel());
     if(chan) {
         ret = chan->getChannelName();
     }
     return ret;
 }

void pvas::SharedPV::close ( bool destroy = false )

inline

Force any clients to disconnect, and prevent re-connection

Parameters

destroy Indicate whether this close() is permanent for clients. If destroy=false, the internal client list is retained, and these clients will see a subsequent open(). If destory=true, the internal client list is cleared.

Postcondition: In the closed state

Note: Provider locking rules apply (

See also: provider_roles_requester_locking).

close() is not final, even with destroy=true new clients may begin connecting, and open() may be called again. A final close() should be performed after the removal from StaticProvider/DynamicProvider which will prevent new clients.

Definition at line 153 of file sharedstate.h.

153 { realClose(destroy, true, 0); }

void pvas::Operation::complete ( )

shorthand for successful completion w/o data (Put or RPC with void return)

Definition at line 308 of file sharedstate_channel.cpp.

 {
     impl->complete(pvd::Status(), 0);
 }

void pvas::Operation::complete ( const epics::pvData::Status & sts )

Complete with success or error w/o data.

Definition at line 313 of file sharedstate_channel.cpp.

 {
     impl->complete(sts, 0);
 }

void pvas::Operation::complete	(	const epics::pvData::PVStructure &	value,
		const epics::pvData::BitSet &	changed
	)

Sucessful completion with data (RPC only)

Definition at line 318 of file sharedstate_channel.cpp.

 {
     impl->complete(pvd::Status(), &value);
 }

pvas::SharedPV::Config::Config ( )

Definition at line 55 of file sharedstate_pv.cpp.

     :dropEmptyUpdates(true)
     ,mapperMode(pvd::PVRequestMapper::Mask)
 {}

std::tr1::shared_ptr< pva::Channel > pvas::SharedPV::connect	(	const std::tr1::shared_ptr< epics::pvAccess::ChannelProvider > &	provider,
		const std::string &	channelName,
		const std::tr1::shared_ptr< epics::pvAccess::ChannelRequester > &	requester
	)

virtual

may call Handler::onFirstConnect()

Note: Provider locking rules apply (

See also: provider_roles_requester_locking).

Implements pvas::StaticProvider::ChannelBuilder.

Definition at line 370 of file sharedstate_pv.cpp.

 {
     shared_pointer self(internal_self);
     std::tr1::shared_ptr<detail::SharedChannel> ret(new detail::SharedChannel(self, provider, channelName, requester));
     return ret;
 }

void pvas::SharedPV::disconnect	(	bool	destroy,
		const epics::pvAccess::ChannelProvider *	provider
	)

virtual

Disconnect all Channels created through the given ChannelProvider. destroy==true if the ChannelProvider is shutting down.

Implements pvas::StaticProvider::ChannelBuilder.

Definition at line 380 of file sharedstate_pv.cpp.

 {
     realClose(destroy, false, provider);
 }

void pvas::SharedPV::fetch	(	epics::pvData::PVStructure &	value,
		epics::pvData::BitSet &	valid
	)

Update arguments with current value, which is the initial value from open() with accumulated post() calls.

Definition at line 356 of file sharedstate_pv.cpp.

 {
     Guard I(mutex);
     if(!type)
         throw std::logic_error("Not open()");
     else if(value.getStructure()!=type)
         throw std::logic_error("Types do not match");
 
     value.copy(*current);
     valid = this->valid;
 }

std::tr1::shared_ptr< epics::pvAccess::Channel > pvas::Operation::getChannel ( )

Definition at line 344 of file sharedstate_channel.cpp.

 {
     return impl->getChannel();
 }

SharedPV::Handler::shared_pointer pvas::SharedPV::getHandler ( ) const

Definition at line 105 of file sharedstate_pv.cpp.

 {
     Guard G(mutex);
     return handler;
 }

std::tr1::shared_ptr< pva::ChannelBaseRequester > pvas::Operation::getRequester ( )

Definition at line 349 of file sharedstate_channel.cpp.

 {
     return impl->getRequester();
 }

void pvas::Operation::info ( const std::string & msg )

Send info message to client. Does not complete().

Definition at line 324 of file sharedstate_channel.cpp.

 {
     pva::ChannelBaseRequester::shared_pointer req(impl->getRequester());
     if(req)
         req->message(msg, pvd::infoMessage);
 }

int pvas::SharedPV::isDebug ( ) const

Definition at line 391 of file sharedstate_pv.cpp.

 {
     Guard G(mutex);
     return debugLvl;
 }

int pvas::Operation::isDebug ( ) const

Definition at line 338 of file sharedstate_channel.cpp.

 {
     Guard G(impl->mutex);
     return impl->debugLvl;
 }

bool pvas::SharedPV::isOpen ( ) const

test open-ness. cf. open() and close()

Definition at line 112 of file sharedstate_pv.cpp.

 {
     Guard G(mutex);
     return !!type;
 }

virtual void pvas::SharedPV::Handler::onFirstConnect ( const SharedPV::shared_pointer & pv )

inlinevirtual

Definition at line 98 of file sharedstate.h.

98 {}

virtual void pvas::SharedPV::Handler::onLastDisconnect ( const SharedPV::shared_pointer & pv )

inlinevirtual

Called when the last client disconnects. May close()

Definition at line 100 of file sharedstate.h.

100 {}

void pvas::SharedPV::Handler::onPut	(	const SharedPV::shared_pointer &	pv,
		Operation &	op
	)

virtual

Client requests Put.

Definition at line 45 of file sharedstate_pv.cpp.

 {
     op.complete(pvd::Status::error("Put not supported"));
 }

void pvas::SharedPV::Handler::onRPC	(	const SharedPV::shared_pointer &	pv,
		Operation &	op
	)

virtual

Client requests RPC.

Definition at line 50 of file sharedstate_pv.cpp.

 {
     op.complete(pvd::Status::error("RPC not supported"));
 }

void pvas::SharedPV::open ( const epics::pvData::PVStructure & value )

Shorthand for.

open(value, pvd::BitSet().set(0))

Definition at line 222 of file sharedstate_pv.cpp.

 {
     // consider all fields to have non-default values.  For users how don't keep track of this.
     open(value, pvd::BitSet().set(0));
 }

void pvas::SharedPV::open	(	const epics::pvData::PVStructure &	value,
		const epics::pvData::BitSet &	valid
	)

Begin allowing clients to connect.

Parameters

value	The initial value of this PV. (any pending Get/Monitor operation will complete with this)
valid	Only these marked fields are considered to have non-default values.

Exceptions

std::logic_error if not in the closed state.

Postcondition: In the opened state

Note: Provider locking rules apply (

See also: provider_roles_requester_locking).

Definition at line 135 of file sharedstate_pv.cpp.

 {
     typedef std::vector<PutInfo> xputs_t;
     typedef std::vector<std::tr1::shared_ptr<detail::SharedRPC> > xrpcs_t;
     typedef std::vector<std::tr1::shared_ptr<pva::MonitorFIFO> > xmonitors_t;
     typedef std::vector<std::tr1::shared_ptr<pva::GetFieldRequester> > xgetfields_t;
 
     const pvd::StructureConstPtr newtype(value.getStructure());
     pvd::PVStructurePtr newvalue(pvd::getPVDataCreate()->createPVStructure(newtype));
     newvalue->copyUnchecked(value, valid);
 
     xputs_t p_put;
     xrpcs_t p_rpc;
     xmonitors_t p_monitor;
     xgetfields_t p_getfield;
     {
         Guard I(mutex);
 
         if(type)
             throw std::logic_error("Already open()");
 
         p_put.reserve(puts.size());
         p_rpc.reserve(rpcs.size());
         p_monitor.reserve(monitors.size());
         p_getfield.reserve(getfields.size());
 
         type = newtype;
         current = newvalue;
         this->valid = valid;
 
         FOR_EACH(puts_t::const_iterator, it, end, puts) {
             if((*it)->channel->dead) continue;
             try {
                 try {
                     (*it)->mapper.compute(*current, *(*it)->pvRequest, config.mapperMode);
                     p_put.push_back(PutInfo((*it)->shared_from_this(), (*it)->mapper.requested(), (*it)->mapper.warnings()));
                 }catch(std::runtime_error& e) {
                     // compute() error
                     p_put.push_back(PutInfo((*it)->shared_from_this(), pvd::StructureConstPtr(), pvd::Status::error(e.what())));
                 }
             }catch(std::tr1::bad_weak_ptr&) {
                 //racing destruction
             }
         }
         FOR_EACH(rpcs_t::const_iterator, it, end, rpcs) {
             if((*it)->connected || (*it)->channel->dead) continue;
             try {
                 p_rpc.push_back((*it)->shared_from_this());
             }catch(std::tr1::bad_weak_ptr&) {}
         }
         FOR_EACH(monitors_t::const_iterator, it, end, monitors) {
             if((*it)->channel->dead) continue;
             try {
                 (*it)->open(newtype);
                 // post initial update
                 (*it)->post(*current, valid);
                 p_monitor.push_back((*it)->shared_from_this());
             }catch(std::tr1::bad_weak_ptr&) {}
         }
         // consume getField
         FOR_EACH(getfields_t::iterator, it, end, getfields) {
             // TODO: this may be on a dead Channel
             p_getfield.push_back(it->lock());
         }
        getfields.clear(); // consume
     }
     // unlock for callbacks
     FOR_EACH(xputs_t::iterator, it, end, p_put) {
         detail::SharedPut::requester_type::shared_pointer requester(it->put->requester.lock());
         if(requester) {
             if(it->status.getType()==pvd::Status::STATUSTYPE_WARNING)
                 requester->message(it->status.getMessage(), pvd::warningMessage);
             requester->channelPutConnect(it->status, it->put, it->type);
         }
     }
     FOR_EACH(xrpcs_t::iterator, it, end, p_rpc) {
         detail::SharedRPC::requester_type::shared_pointer requester((*it)->requester.lock());
         if(requester) requester->channelRPCConnect(pvd::Status(), *it);
     }
     FOR_EACH(xmonitors_t::iterator, it, end, p_monitor) {
         (*it)->notify();
     }
     FOR_EACH(xgetfields_t::iterator, it, end, p_getfield) {
         if(*it) (*it)->getDone(pvd::Status(), newtype);
     }
 }

void pvas::SharedPV::open ( const epics::pvData::StructureConstPtr & type )

Shorthand for.

open(*pvd::getPVDataCreate()->createPVStructure(type), pvd::BitSet().set(0))

Definition at line 228 of file sharedstate_pv.cpp.

 {
     pvd::PVStructurePtr value(pvd::getPVDataCreate()->createPVStructure(type));
     open(*value);
 }

pvas::Operation::Operation ( )

inline

create empty op for later assignment

Definition at line 239 of file sharedstate.h.

pvas::Operation::operator bool_type ( ) const

inline

Definition at line 280 of file sharedstate.h.

280 { return valid() ? &Operation::valid : 0; }

pvas::Operation::valid

bool valid() const

Definition: sharedstate_channel.cpp:354

const pva::PeerInfo * pvas::Operation::peer ( ) const

Information about peer transport and authentication.

Returns: May be NULL if no information is available

Definition at line 303 of file sharedstate_channel.cpp.

 {
     return impl->info ? impl->info.get() : 0;
 }

pvas::SharedPV::POINTER_DEFINITIONS ( SharedPV )

pvas::SharedPV::Handler::POINTER_DEFINITIONS ( Handler )

pvas::Operation::POINTER_DEFINITIONS ( Operation )

void pvas::SharedPV::post	(	const epics::pvData::PVStructure &	value,
		const epics::pvData::BitSet &	changed
	)

Update the cached PVStructure in this SharedPV. Only those fields marked as changed will be copied in. Makes a light-weight copy.

Precondition: isOpen()==true

Exceptions

std::logic_error if !isOpen()

Note: Provider locking rules apply (

See also: provider_roles_requester_locking).

Definition at line 326 of file sharedstate_pv.cpp.

 {
     typedef std::vector<std::tr1::shared_ptr<pva::MonitorFIFO> > xmonitors_t;
     xmonitors_t p_monitor;
     {
         Guard I(mutex);
 
         if(!type)
             throw std::logic_error("Not open()");
         else if(*type!=*value.getStructure())
             throw std::logic_error("Type mis-match");
 
         if(current) {
             current->copyUnchecked(value, changed);
             valid |= changed;
         }
 
         p_monitor.reserve(monitors.size()); // ick, for lack of a list with thread-safe iteration
 
         FOR_EACH(monitors_t::const_iterator, it, end, monitors) {
             (*it)->post(value, changed);
             p_monitor.push_back((*it)->shared_from_this());
         }
     }
     FOR_EACH(xmonitors_t::iterator, it, end, p_monitor) {
         (*it)->notify();
     }
 }

const epics::pvData::PVStructure & pvas::Operation::pvRequest ( ) const

pvRequest blob, may be used to modify handling.

Definition at line 278 of file sharedstate_channel.cpp.

 {
     return *impl->pvRequest;
 }

void pvas::SharedPV::setDebug ( int lvl )

Definition at line 385 of file sharedstate_pv.cpp.

 {
     Guard G(mutex);
     debugLvl = lvl;
 }

void pvas::SharedPV::setHandler ( const std::tr1::shared_ptr< Handler > & handler )

Replace Handler given with ctor.

Definition at line 99 of file sharedstate_pv.cpp.

 {
     Guard G(mutex);
     this->handler = handler;
 }

bool pvas::Operation::valid ( void ) const

Definition at line 354 of file sharedstate_channel.cpp.

 {
     return !!impl;
 }

const epics::pvData::PVStructure & pvas::Operation::value ( ) const

Input data

Definition at line 283 of file sharedstate_channel.cpp.

 {
     return *impl->value;
 }

void pvas::Operation::warn ( const std::string & msg )

Send warning message to client. Does not complete().

Definition at line 331 of file sharedstate_channel.cpp.

 {
     pva::ChannelBaseRequester::shared_pointer req(impl->getRequester());
     if(req)
         req->message(msg, pvd::warningMessage);
 }

pvas::SharedPV::Handler::~Handler ( )

virtual

Definition at line 43 of file sharedstate_pv.cpp.

43 {}

pvas::SharedPV::~SharedPV ( )

virtual

Definition at line 94 of file sharedstate_pv.cpp.

                     {
     close();
     REFTRACE_DECREMENT(num_instances);
 }

Variable Documentation

bool pvas::SharedPV::Config::dropEmptyUpdates

default true. Drop updates which don't include an field values.

Definition at line 86 of file sharedstate.h.

epics::pvData::PVRequestMapper::mode_t pvas::SharedPV::Config::mapperMode

default Mask.

See also: epics::pvData::PVRequestMapper::mode_t

Definition at line 87 of file sharedstate.h.

Friends

friend struct detail::SharedChannel

friend

Definition at line 79 of file sharedstate.h.

friend struct detail::SharedMonitorFIFO

friend

Definition at line 80 of file sharedstate.h.

friend struct detail::SharedPut

friend

Definition at line 81 of file sharedstate.h.

friend struct detail::SharedPut

friend

Definition at line 235 of file sharedstate.h.

friend struct detail::SharedRPC

friend

Definition at line 82 of file sharedstate.h.

friend struct detail::SharedRPC

friend

Definition at line 236 of file sharedstate.h.

void epics::pvAccess::providerRegInit ( void * )

friend

Classes

Functions

Variables

Friends

Detailed Description

Server API shared_ptr Ownership

Function Documentation

Variable Documentation

Friends