Server API

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

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...
class	pvas::SharedPV
	A Shared State Process Variable (PV) More...
struct	pvas::SharedPV::Handler
	Callbacks associated with a SharedPV. More...
struct	pvas::Operation
	An in-progress network operation (Put or RPC). More...

Typedefs
typedef std::tr1::shared_ptr < SharedPV >	pvas::SharedPV::shared_pointer
typedef std::tr1::shared_ptr < const SharedPV >	pvas::SharedPV::const_shared_pointer
typedef std::tr1::weak_ptr < SharedPV >	pvas::SharedPV::weak_pointer
typedef std::tr1::weak_ptr < const SharedPV >	pvas::SharedPV::const_weak_pointer
typedef std::tr1::shared_ptr < Handler >	pvas::SharedPV::Handler::shared_pointer
typedef std::tr1::shared_ptr < const Handler >	pvas::SharedPV::Handler::const_shared_pointer
typedef std::tr1::weak_ptr < Handler >	pvas::SharedPV::Handler::weak_pointer
typedef std::tr1::weak_ptr < const Handler >	pvas::SharedPV::Handler::const_weak_pointer
typedef std::tr1::shared_ptr < Operation >	pvas::Operation::shared_pointer
typedef std::tr1::shared_ptr < const Operation >	pvas::Operation::const_shared_pointer
typedef std::tr1::weak_ptr < Operation >	pvas::Operation::weak_pointer
typedef std::tr1::weak_ptr < const Operation >	pvas::Operation::const_weak_pointer

Functions
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()
virtual void	pvas::SharedPV::Handler::onPut (const SharedPV::shared_pointer &pv, Operation &op)
	Client requests Put.
virtual void	pvas::SharedPV::Handler::onRPC (const SharedPV::shared_pointer &pv, Operation &op)
	Client requests RPC.
static shared_pointer	pvas::SharedPV::build (const std::tr1::shared_ptr< Handler > &handler, Config *conf=0)
	Allocate a new PV in the closed state. More...
static shared_pointer	pvas::SharedPV::buildReadOnly (Config *conf=0)
	A SharedPV which fails all Put and RPC operations. In closed state.
static shared_pointer	pvas::SharedPV::buildMailbox (Config *conf=0)
	A SharedPV which accepts all Put operations, and fails all RPC operations. In closed state.
void	pvas::SharedPV::setHandler (const std::tr1::shared_ptr< Handler > &handler)
	Replace Handler given with ctor.
Handler::shared_pointer	pvas::SharedPV::getHandler () const
bool	pvas::SharedPV::isOpen () const
	test open-ness. cf. open() and close()
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)
	Begin allowing clients to connect. More...
void	pvas::SharedPV::open (const epics::pvData::StructureConstPtr &type)
	Shorthand for. More...
void	pvas::SharedPV::close (bool destroy=false)
	Force any clients to disconnect, and prevent re-connection. More...
std::tr1::shared_ptr < epics::pvData::PVStructure >	pvas::SharedPV::build ()
	Create a new container which may be used to prepare to call post(). More...
void	pvas::SharedPV::post (const epics::pvData::PVStructure &value, const epics::pvData::BitSet &changed)
	Update the cached PVStructure in this SharedPV. More...
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.
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)
	may call Handler::onFirstConnect() More...
virtual void	pvas::SharedPV::disconnect (bool destroy, const epics::pvAccess::ChannelProvider *provider)
	Disconnect all Channels created through the given ChannelProvider. More...
void	pvas::SharedPV::setDebug (int lvl)
int	pvas::SharedPV::isDebug () const
	pvas::Operation::Operation ()
	create empty op for later assignment
const epics::pvData::PVStructure &	pvas::Operation::pvRequest () const
	pvRequest blob, may be used to modify handling.
const epics::pvData::PVStructure &	pvas::Operation::value () const
	Input data.
const epics::pvData::BitSet &	pvas::Operation::changed () const
	Applies to value(). Which fields of input data are actual valid. Others should not be used.
std::string	pvas::Operation::channelName () const
	The name of the channel through which this request was made (eg. for logging purposes).
const epics::pvAccess::PeerInfo *	pvas::Operation::peer () const
	Information about peer transport and authentication. More...
void	pvas::Operation::complete ()
	shorthand for successful completion w/o data (Put or RPC with void return)
void	pvas::Operation::complete (const epics::pvData::Status &sts)
	Complete with success or error w/o data.
void	pvas::Operation::complete (const epics::pvData::PVStructure &value, const epics::pvData::BitSet &changed)
	Sucessful completion with data (RPC only)
void	pvas::Operation::info (const std::string &)
	Send info message to client. Does not complete().
void	pvas::Operation::warn (const std::string &)
	Send warning message to client. Does not complete().
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.
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 Server Mailbox Example 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.

Function Documentation

static 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

std::tr1::shared_ptr<epics::pvData::PVStructure> 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.

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.

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  )

virtual

may call Handler::onFirstConnect()

Note

Provider locking rules apply (

See Also

provider_roles_requester_locking).

Implements pvas::StaticProvider::ChannelBuilder.

virtual 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.

void pvas::SharedPV::open

(

const epics::pvData::PVStructure &

value

)

Shorthand for.

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).

void pvas::SharedPV::open

(

const epics::pvData::StructureConstPtr &

type

)

Shorthand for.

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

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

(

)

const

Information about peer transport and authentication.

Returns

May be NULL if no information is available

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).

Variable Documentation

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.