pvAccessCPP  7.1.2
Classes | Public Types | Public Member Functions | Friends | List of all members
epics::pvAccess::MonitorFIFO Class Reference

Utility implementation of Monitor. More...

#include <client/pv/monitor.h>

Inheritance diagram for epics::pvAccess::MonitorFIFO:
Inheritance graph
[legend]
Collaboration diagram for epics::pvAccess::MonitorFIFO:
Collaboration graph
[legend]

Classes

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

Public Types

typedef MonitorRequester requester_type
 

Public Member Functions

 POINTER_DEFINITIONS (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)
 
const std::tr1::shared_ptr< MonitorRequestergetRequester () 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 () OVERRIDE FINAL
 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 () OVERRIDE FINAL
 Start monitoring. More...
 
virtual epics::pvData::Status stop () OVERRIDE FINAL
 Stop Monitoring. More...
 
virtual MonitorElementPtr poll () OVERRIDE FINAL
 If monitor has occurred return data. More...
 
virtual void release (MonitorElementPtr const &monitorElement) OVERRIDE FINAL
 Release a MonitorElement that was returned by poll. More...
 
virtual void getStats (Stats &s) const OVERRIDE FINAL
 
virtual void reportRemoteQueueStatus (epics::pvData::int32 freeElements) OVERRIDE FINAL
 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)
 
 POINTER_DEFINITIONS (Destroyable)
 

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

◆ 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
requesterDownstream/consumer callbacks
pvRequestDownstream provided options
sourceUpstream/producer callbacks
confUpstream provided options. Updated with actual values used. May be NULL to use defaults.

Member Function Documentation

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

◆ 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
freeElementsnumber 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: