epics::pvAccess::MonitorFIFO Class Reference

Utility implementation of Monitor. More...

#include <client/pv/monitor.h>

Inheritance diagram for epics::pvAccess::MonitorFIFO:

Collaboration diagram for epics::pvAccess::MonitorFIFO:

Classes
struct	Source
	Source methods may be called with downstream mutex locked. More...

Public Types
typedef std::tr1::shared_ptr < MonitorFIFO >	shared_pointer
typedef std::tr1::shared_ptr < const MonitorFIFO >	const_shared_pointer
typedef std::tr1::weak_ptr < MonitorFIFO >	weak_pointer
typedef std::tr1::weak_ptr < const MonitorFIFO >	const_weak_pointer
typedef MonitorRequester	requester_type

Public Member Functions
	MonitorFIFO (const std::tr1::shared_ptr< MonitorRequester > &requester, const pvData::PVStructure::const_shared_pointer &pvRequest, const Source::shared_pointer &source=Source::shared_pointer(), Config *conf=0)
const std::tr1::shared_ptr < MonitorRequester >	getRequester () const
	Access to MonitorRequester passed to ctor, or NULL if it has already been destroyed. More...
void	show (std::ostream &strm) const
virtual void	destroy ()
	Destroy this instance.
void	setFreeHighMark (double level)
	Level, as a percentage of empty buffer slots, at which to call Source::freeHighMark(). More...
void	open (const epics::pvData::StructureConstPtr &type)
	Mark subscription as "open" with the associated structure type.
void	close ()
	Abnormal closure (eg. due to upstream dis-connection)
void	finish ()
	Successful closure (eg. RDB query done)
bool	tryPost (const pvData::PVStructure &value, const epics::pvData::BitSet &changed, const epics::pvData::BitSet &overrun=epics::pvData::BitSet(), bool force=false)
	Consume a free slot if available. More...
void	post (const pvData::PVStructure &value, const epics::pvData::BitSet &changed, const epics::pvData::BitSet &overrun=epics::pvData::BitSet())
	Consume a free slot if available, otherwise squash with most recent.
void	notify ()
	Call after calling any other upstream interface methods (open()/close()/finish()/post()/...) when no upstream mutexes are locked. More...
virtual epics::pvData::Status	start ()
	Start monitoring. More...
virtual epics::pvData::Status	stop ()
	Stop Monitoring. More...
virtual MonitorElementPtr	poll ()
	If monitor has occurred return data. More...
virtual void	release (MonitorElementPtr const &monitorElement)
	Release a MonitorElement that was returned by poll. More...
virtual void	getStats (Stats &s) const
virtual void	reportRemoteQueueStatus (epics::pvData::int32 freeElements)
	Report remote queue status. More...
size_t	freeCount () const
	Number of unused FIFO slots at this moment, which may changed in the next.
	POINTER_DEFINITIONS (Monitor)

Friends
void	providerRegInit (void *)

Detailed Description

Utility implementation of Monitor.

The Monitor interface defines the downstream (consumer facing) side of a FIFO. This class is a concrete implementation of this FIFO, including the upstream (producer facing) side.

In addition to MonitorRequester, which provides callbacks to the downstream side, The MonitorFIFO::Source class provides callbacks to the upstream side.

The simplest usage is to create (as shown below), then put update into the FIFO using post() and tryPost(). These methods behave the same when the queue is not full, but differ when it is. Additionally, tryPost() has an argument 'force'. Together there are three actions

post(value, changed) - combines the new update with the last (most recent) in the FIFO.

tryPost(value, changed, ..., false) - Makes no change to the FIFO and returns false.

tryPost(value, changed, ..., true) - Over-fills the FIFO with the new element, then returns false.

Note

Calls to post() or tryPost() must be followed with a call to notify(). Callers of notify() must not hold any locks, or a deadlock is possible.

The intent of tryPost() with force=true is to aid code which is transferring values from some upstream buffer and this FIFO. Such code can be complicated if an item is removed from the upstream buffer, but can't be put into this downstream FIFO. Rather than being forced to effectivly maintain a third FIFO, code can use force=true.

In either case, tryPost()==false indicates the the FIFO is full.

eg. simple usage in a sub-class for Channel named MyChannel.

pva::Monitor::shared_pointer
MyChannel::createMonitor(const pva::MonitorRequester::shared_pointer &requester,
                         const pvd::PVStructure::shared_pointer &pvRequest)
{
    std::tr1::shared_ptr<pva::MonitorFIFO> ret(new pva::MonitorFIFO(requester, pvRequest));
    ret->open(spamtype);
    ret->notify();
    // ret->post(...); // maybe initial update
}

Definition at line 258 of file monitor.h.

Constructor & Destructor Documentation

epics::pvAccess::MonitorFIFO::MonitorFIFO	(	const std::tr1::shared_ptr< MonitorRequester > &	requester,
		const pvData::PVStructure::const_shared_pointer &	pvRequest,
		const Source::shared_pointer &	source = Source::shared_pointer(),
		Config *	conf = 0
	)

Parameters

requester	Downstream/consumer callbacks
pvRequest	Downstream provided options
source	Upstream/producer callbacks
conf	Upstream provided options. Updated with actual values used. May be NULL to use defaults.

Member Function Documentation

const std::tr1::shared_ptr<MonitorRequester> epics::pvAccess::MonitorFIFO::getRequester ( ) const

inline

Access to MonitorRequester passed to ctor, or NULL if it has already been destroyed.

Since

>6.1.0

Definition at line 297 of file monitor.h.

void epics::pvAccess::MonitorFIFO::notify

(

)

Call after calling any other upstream interface methods (open()/close()/finish()/post()/...) when no upstream mutexes are locked.

Do not call from Source::freeHighMark(). This is done automatically. Call any MonitorRequester methods.

virtual MonitorElementPtr epics::pvAccess::MonitorFIFO::poll ( )

virtual

If monitor has occurred return data.

Returns

monitorElement for modified data. Must call get to determine if data is available.

May recursively call MonitorRequester::unlisten()

Implements epics::pvAccess::Monitor.

virtual void epics::pvAccess::MonitorFIFO::release ( MonitorElementPtr const &  monitorElement )

virtual

Release a MonitorElement that was returned by poll.

A poll() must be called after the release() to check the presence of any modified data.

Parameters

monitorElement

Implements epics::pvAccess::Monitor.

virtual void epics::pvAccess::MonitorFIFO::reportRemoteQueueStatus ( epics::pvData::int32  freeElements )

virtual

Report remote queue status.

Parameters

freeElements

number of free elements.

Reimplemented from epics::pvAccess::Monitor.

void epics::pvAccess::MonitorFIFO::setFreeHighMark

(

double

level

)

Level, as a percentage of empty buffer slots, at which to call Source::freeHighMark().

Trigger condition is when number of free buffer slots goes above this level. In range [0.0, 1.0)

virtual epics::pvData::Status epics::pvAccess::MonitorFIFO::start ( )

virtual

Start monitoring.

Returns

completion status.

Implements epics::pvAccess::Monitor.

virtual epics::pvData::Status epics::pvAccess::MonitorFIFO::stop ( )

virtual

Stop Monitoring.

Returns

completion status.

Implements epics::pvAccess::Monitor.

bool epics::pvAccess::MonitorFIFO::tryPost	(	const pvData::PVStructure &	value,
		const epics::pvData::BitSet &	changed,
		const epics::pvData::BitSet &	overrun = epics::pvData::BitSet(),
		bool	force = false
	)

Consume a free slot if available.

otherwise ... if !force take no action and return false. if force then attempt to allocate and fill a new slot, then return false. The extra slot will be free'd after it is consumed.

---

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

• client/pv/monitor.h