Utility implementation of Monitor. More...

#include <client/pv/monitor.h>

Inheritance diagram for epics::pvAccess::MonitorFIFO:

[legend]

Collaboration diagram for epics::pvAccess::MonitorFIFO:

[legend]

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.

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

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.

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.

virtual epics::pvData::Status	start ()
	Start monitoring.

virtual epics::pvData::Status	stop ()
	Stop Monitoring.

virtual MonitorElementPtr	poll ()
	If monitor has occurred return data.

virtual void	release (MonitorElementPtr const &monitorElement)
	Release a MonitorElement that was returned by poll.

virtual void	getStats (Stats &s) const

virtual void	reportRemoteQueueStatus (epics::pvData::int32 freeElements)
	Report remote queue status.

size_t	freeCount () const
	Number of unused FIFO slots at this moment, which may changed in the next.

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.

Member Typedef Documentation

◆ const_shared_pointer

std::tr1::shared_ptr<const MonitorFIFO> epics::pvAccess::MonitorFIFO::const_shared_pointer

Definition at line 262 of file monitor.h.

◆ const_weak_pointer

std::tr1::weak_ptr<const MonitorFIFO> epics::pvAccess::MonitorFIFO::const_weak_pointer

Definition at line 262 of file monitor.h.

◆ requester_type

MonitorRequester epics::pvAccess::Monitor::requester_type

inherited

Definition at line 72 of file monitor.h.

◆ shared_pointer

std::tr1::shared_ptr<MonitorFIFO> epics::pvAccess::MonitorFIFO::shared_pointer

Definition at line 262 of file monitor.h.

◆ weak_pointer

std::tr1::weak_ptr<MonitorFIFO> epics::pvAccess::MonitorFIFO::weak_pointer

Definition at line 262 of file monitor.h.

Constructor & Destructor Documentation

◆ MonitorFIFO()

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

◆ destroy()

virtual void epics::pvAccess::MonitorFIFO::destroy ( )

virtual

Destroy this instance.

Reimplemented from epics::pvAccess::Destroyable.

◆ getRequester()

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.

◆ getStats()

virtual void epics::pvAccess::MonitorFIFO::getStats ( Stats & s ) const

virtual

Reimplemented from epics::pvAccess::Monitor.

◆ notify()

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.

◆ poll()

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.

◆ release()

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.

◆ reportRemoteQueueStatus()

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.

◆ setFreeHighMark()

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)

◆ start()

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

virtual

Start monitoring.

Returns: completion status.

Implements epics::pvAccess::Monitor.

◆ stop()

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

virtual

Stop Monitoring.

Returns: completion status.

Implements epics::pvAccess::Monitor.

◆ tryPost()

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

Classes

Public Types

Public Member Functions

Friends

Detailed Description

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.

Member Typedef Documentation

◆ const_shared_pointer

◆ const_weak_pointer

◆ requester_type

◆ shared_pointer

◆ weak_pointer

Constructor & Destructor Documentation

◆ MonitorFIFO()

Member Function Documentation

◆ destroy()

◆ getRequester()

◆ getStats()

◆ notify()

◆ poll()

◆ release()

◆ reportRemoteQueueStatus()

◆ setFreeHighMark()

◆ start()

◆ stop()

◆ tryPost()