#include "createRequest.h"

Public Types
enum	mode_t { Mask, Slice }

Public Member Functions
	PVRequestMapper ()

	PVRequestMapper (const PVStructure &base, const PVStructure &pvRequest, mode_t mode=Mask)

void	reset ()
	return to state of default ctor More...

const StructureConstPtr &	base () const

const StructureConstPtr &	requested () const

const BitSet &	requestedMask () const

PVStructurePtr	buildRequested () const

PVStructurePtr	buildBase () const

void	compute (const PVStructure &base, const PVStructure &pvRequest, mode_t mode=Mask)

const std::string &	warnings () const
	After compute(), check if !warnings().empty() More...

void	copyBaseToRequested (const PVStructure &base, const BitSet &baseMask, PVStructure &request, BitSet &requestMask) const

void	copyBaseFromRequested (PVStructure &base, BitSet &baseMask, const PVStructure &request, const BitSet &requestMask) const

void	maskBaseToRequested (const BitSet &baseMask, BitSet &requestMask) const

void	maskBaseFromRequested (BitSet &baseMask, const BitSet &requestMask) const

void	swap (PVRequestMapper &other)
	Exchange contents of two mappers. O(0) and never throws. More...

Detailed Description

Helper for implementations of epics::pvAccess::ChannelProvider in interpreting the 'field' substructure of a pvRequest. Copies between an internal (base) Structure, and a client/user visible (requested) Structure.

Note: PVRequestMapper is not re-entrant. It is copyable and swap()able.

Definition at line 74 of file createRequest.h.

Member Enumeration Documentation

enum epics::pvData::PVRequestMapper::mode_t

Enumerator

Mask

Masking mode.

   Requested Structure is identical to Base.
   The 'field' substructure of the provided pvRequest is used to construct a BitSet
   where the bits corresponding to the "selected" fields are set.  This mask can be
   access via. requestedMask().  The copy* and mask* methods operate only
   on "selected" fields.

Slice

Slice mode

   The Requested Structure is a strict sub-set of the Base Structure containing
   those fields "selected" by the 'field' substructure of the provided pvRequest.

Definition at line 76 of file createRequest.h.

                 {
         Mask,
         Slice,
     };

Constructor & Destructor Documentation

epics::pvData::PVRequestMapper::PVRequestMapper ( )

Definition at line 26 of file requestmapper.cpp.

26 {}

epics::pvData::PVRequestMapper::PVRequestMapper	(	const PVStructure &	base,
		const PVStructure &	pvRequest,
		mode_t	mode = `Mask`
	)

See also: compute()

Definition at line 28 of file requestmapper.cpp.

 {
     compute(base, pvRequest, mode);
 }

Member Function Documentation

const StructureConstPtr& epics::pvData::PVRequestMapper::base ( ) const

inline

Returns: the Structure of the PVStructure previously passed to compute(). NULL if never computed()'d

Definition at line 104 of file createRequest.h.

104 { return typeBase; }

PVStructurePtr epics::pvData::PVRequestMapper::buildBase ( ) const

Returns: A new instance of the base() Structure

Definition at line 42 of file requestmapper.cpp.

 {
     if(!typeBase)
         THROW_EXCEPTION2(std::logic_error, "No mapping compute()d");
     return typeBase->build();
 }

PVStructurePtr epics::pvData::PVRequestMapper::buildRequested ( ) const

Returns: A new instance of the requested() Structure

Definition at line 35 of file requestmapper.cpp.

 {
     if(!typeRequested)
         THROW_EXCEPTION2(std::logic_error, "No mapping compute()d");
     return typeRequested->build();
 }

void epics::pvData::PVRequestMapper::compute	(	const PVStructure &	base,
		const PVStructure &	pvRequest,
		mode_t	mode = `Mask`
	)

(re)compute the selected subset of provided base structure.

Parameters

base	A full base structure. Must be "top level" (field offset zero).
pvRequest	The user/client provided request modifier
mode	Control how the mapping is constructed.

See also: mode_t for a description of mapping modes.

Postcondition: Updates warnings()

Exceptions

std::runtime_error	For errors involving invalid pvRequest
std::logic_error	if the provided base is not a "top level" PVStructure.

Definition at line 49 of file requestmapper.cpp.

 {
     if(base.getFieldOffset()!=0)
         THROW_EXCEPTION2(std::logic_error, "Mapper must be used with top level PVStructure");
 
     bool ok = true;
 
     // we want to be transactional, which requires a second copy of everything.
     PVRequestMapper temp;
 
     // whether to preserve IDs of partial structures.
     bool keepids = false;
     PVScalar::const_shared_pointer pbp(pvRequest.getSubField<PVScalar>("record._options.keepIDs"));
     try {
         if(pbp) keepids = pbp->getAs<boolean>();
     }catch(std::runtime_error& e){
         std::ostringstream msg;
         msg<<"Can't parse keepIDs : '"<<e.what()<<"' ";
         temp.messages+=msg.str();
     }
 
     PVStructure::const_shared_pointer fields(pvRequest.getSubField<PVStructure>("field"));
     if(!fields || fields->getPVFields().empty()) {
         // not selection, or empty selection, treated as select all
         temp.typeBase = temp.typeRequested = base.getStructure();
 
         for(size_t i=1, N=base.getNextFieldOffset(); i<N; i++)
             temp.maskRequested.set(i);
 
     } else {
         FieldBuilderPtr builder(getFieldCreate()->createFieldBuilder());
 
         if(keepids)
             builder = builder->setId(base.getStructure()->getID());
 
         ok &= temp._compute(base, *fields, builder, keepids, 0); // fills in builder
 
         temp.typeBase = base.getStructure();
         temp.typeRequested = builder->createStructure();
         // possible that typeBase==typeRequested if all fields explicitly selected
     }
 
     if(mode==Mask) {
         // short circuit use of masked Structure, but keep maskRequested
         temp.typeRequested = temp.typeBase;
     }
 
     {
         PVStructurePtr proto(temp.typeRequested->build());
 
         // base -> request may be sparce mapping
         temp.base2req.resize(base.getNextFieldOffset());
         // request -> base is dense mapping
         temp.req2base.resize(proto->getNextFieldOffset());
 
         // special handling for whole structure mapping.  in part because getSubField(0) isn't allowed
         temp.base2req[0] = Mapping(0, false);
         temp.req2base[0] = Mapping(0, false);
 
         // Iterate prototype of requested to map with base field offsets.
         // which is handled as a special case below.
         // We also don't try to prevent redundant copies if both leaf and compress bits are set.
         for(size_t r=1, N=proto->getNextFieldOffset(); r<N; r++) {
             PVField::const_shared_pointer fld_req(proto->getSubFieldT(r)),
                     fld_base(base.getSubFieldT(fld_req->getFullName()));
             const size_t b = fld_base->getFieldOffset();
 
             if(!temp.requestedMask().get(b))
                 continue;
 
             bool leaf = fld_base->getField()->getType()!=structure;
 
             // initialize mapping when our bit is set
             temp.base2req[b] = Mapping(r, leaf);
             temp.req2base[r] = Mapping(b, leaf);
 
             // add ourself to all "compress" bit mappings of enclosing structures
             for(const PVStructure *parent = fld_req->getParent(); parent; parent = parent->getParent()) {
                 temp.req2base[parent->getFieldOffset()].tomask  .set(b);
                 temp.req2base[parent->getFieldOffset()].frommask.set(r);
             }
 
             for(const PVStructure *parent = fld_base->getParent(); parent; parent = parent->getParent()) {
                 temp.base2req[parent->getFieldOffset()].tomask  .set(r);
                 temp.base2req[parent->getFieldOffset()].frommask.set(b);
             }
         }
     }
 
     temp.maskRequested.set(0);
 
     if(temp.maskRequested.nextSetBit(1)==-1) {
         ok = false;
         temp.messages+="Empty field selection";
     }
 
     if(!ok)
         throw std::runtime_error(temp.messages);
 
     swap(temp);
 }

void epics::pvData::PVRequestMapper::copyBaseFromRequested	(	PVStructure &	base,
		BitSet &	baseMask,
		const PVStructure &	request,
		const BitSet &	requestMask
	)		const

Copy field values into Base structure from Requested structure

Parameters

base	An instance of the base Structure. Field values are copied into it. Need not be the same instance passed to compute().
baseMask	A bit mask indicating which base fields were copied. BitSet::clear() is not called.
request	An instance of the requested() Structure. Field values are copied from it.
requestMask	A bit mask selecting those requested fields to copy.

Definition at line 235 of file requestmapper.cpp.

         {
     assert(base.getStructure()==typeBase);
     assert(request.getStructure()==typeRequested);
     _map(request, requestMask, base, baseMask, true);
 }

void epics::pvData::PVRequestMapper::copyBaseToRequested	(	const PVStructure &	base,
		const BitSet &	baseMask,
		PVStructure &	request,
		BitSet &	requestMask
	)		const

Copy field values from Base structure into Requested structure

Parameters

base	An instance of the base Structure. Field values are copied from it. Need not be the same instance passed to compute().
baseMask	A bit mask selecting those base fields to copy.
request	An instance of the requested() Structure. Field values are copied to it.
requestMask	A bit mask indicating which requested fields were copied. BitSet::clear() is not called.

Definition at line 224 of file requestmapper.cpp.

         {
     assert(base.getStructure()==typeBase);
     assert(request.getStructure()==typeRequested);
     _map(base, baseMask, request, requestMask, false);
 }

void epics::pvData::PVRequestMapper::maskBaseFromRequested	(	BitSet &	baseMask,
		const BitSet &	requestMask
	)		const

inline

Translate requested bit mask into base bit mask. BitSet::clear() is not called.

Definition at line 187 of file createRequest.h.

191 { _mapMask(requestMask, baseMask, true); }

void epics::pvData::PVRequestMapper::maskBaseToRequested	(	const BitSet &	baseMask,
		BitSet &	requestMask
	)		const

inline

Translate Base bit mask into requested bit mask. BitSet::clear() is not called.

Definition at line 179 of file createRequest.h.

183 { _mapMask(baseMask, requestMask, false); }

const StructureConstPtr& epics::pvData::PVRequestMapper::requested ( ) const

inline

Returns: the Structure which is the selected sub-set of the base Structure. NULL if never computed()'d

Definition at line 106 of file createRequest.h.

106 { return typeRequested; }

const BitSet& epics::pvData::PVRequestMapper::requestedMask ( ) const

inline

A mask of all fields in the base structure which are also in the requested structure, and any parent/structure "compress" bits. eg. bit 0 is always set.

PVRequestMapper mapper(...);
...
BitSet changed = ...; // a base changed mask
bool wouldcopy = changed.logical_and(mapper.requestedMask());
// wouldcopy==false means that copyBaseToRequested(..., changed, ...) would be a no-op

eg. allows early detection of empty monitor updates.

Definition at line 121 of file createRequest.h.

121 { return maskRequested; }

void epics::pvData::PVRequestMapper::reset ( )

return to state of default ctor

Definition at line 317 of file requestmapper.cpp.

 {
     typeBase.reset();
     typeRequested.reset();
     maskRequested.clear();
     base2req.clear();
     req2base.clear();
     messages.clear();
     scratch.clear(); // paranoia
 }

void epics::pvData::PVRequestMapper::swap ( PVRequestMapper & other )

Exchange contents of two mappers. O(0) and never throws.

Definition at line 306 of file requestmapper.cpp.

 {
     typeBase.swap(other.typeBase);
     typeRequested.swap(other.typeRequested);
     maskRequested.swap(other.maskRequested);
     base2req.swap(other.base2req);
     req2base.swap(other.req2base);
     messages.swap(other.messages);
     scratch.swap(other.scratch); // paranoia
 }

const std::string& epics::pvData::PVRequestMapper::warnings ( ) const

inline

After compute(), check if !warnings().empty()

Definition at line 143 of file createRequest.h.

143 { return messages; }

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

modules/pvData/src/copy/pv/createRequest.h
modules/pvData/src/copy/requestmapper.cpp

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation