Class PVRequestMapper

Nested Relationships

Nested Types

Class Documentation

class PVRequestMapper

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.

Public Types

enum mode_t

Values:

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.

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

Public Functions

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

See also

compute()

void reset()

return to state of default ctor

inline const StructureConstPtr &base() const
Returns

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

inline const StructureConstPtr &requested() const
Returns

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

inline const BitSet &requestedMask() const

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.

PVStructurePtr buildRequested() const
Returns

A new instance of the requested() Structure

PVStructurePtr buildBase() const
Returns

A new instance of the base() Structure

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

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

See also

mode_t for a description of mapping modes.

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.

Throws

  • std::runtime_error – For errors involving invalid pvRequest

  • std::logic_error – if the provided base is not a “top level” PVStructure.

Post

Updates warnings()

inline const std::string &warnings() const

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

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

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

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

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

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

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

void swap(PVRequestMapper &other)

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