CRingSelectionPredicate

Name

CRingSelectionPredicate -- Base class for predicates that select items from ring buffers.

Synopsis


#include <CRingSelectionPredicate.h>
         
 class CRingSelectionPredicate {

  CRingSelectionPredicate();
  CRingSelectionPredicate(unsigned int nType, uint32_t* types);
  CRingSelectionPredicate(unsigned int nType, uint32_t* type, bool* sample);
  CRingSelectionPredicate(const CRingSelectionPredicate& rhs);

  virtual ~CRingSelectionPredicate();

  CRingSelectionPredicate& operator=(const CRingSelectionPredicate& rhs);
  const int operator==(const CRingSelectionPredicate& rhs);
  const int operator!=(const CRingSelectionPredicate& rhs);
  virtual bool operator()(CRingBuffer& ring);
  virtual = 0 bool selectThis(uint32_t type);
  void selectItem(CRingBuffer& ring);
  protected void addSelectionItem(uint32_t type, bool sample =  false);
  protected SelectionMapIterator find(uint32_t type);
  protected SelectionMapIterator end();
  protected uint32_t longswap(uint32_t input);
  protected void addSelectionItems(std::vector<ItemType> selections);
}

Description

CRingSelectionPredicate is an abstract base class that can be subclassed to create specific predicates to selectively grab items from a ring buffer via CRingItem::getFromRing.

The base class provides a set of item types and flags, and functions to maintain that set. The meaning of those are up to the specific concrete predicate. The operator() is provided that is sufficient for predicates that treat the flag as a request to sample data of that type by checking if a type is acceptable or not via the pure virtual function selectThis.

Member functions

Public members

CRingSelectionPredicate();

Default constructor for a the base class, the list of type/flag pairs remains empty.

CRingSelectionPredicate(unsigned int nType, uint32_t* types);

Constructs the base class with nType type/flag pairs where types is an array of types and all of the flags are set to be false.

CRingSelectionPredicate(unsigned int nType, uint32_t* type, bool* sample);

Constructs a base class as above, however the state of the flag that corresponds to each type is specfied in the corresponding element of sample.

CRingSelectionPredicate(const CRingSelectionPredicate& rhs);

Provides support for copy construction of an object derived from CRingSelectionPredicate by copying the type/flag pairs from rhs.

CRingSelectionPredicate& operator=(const CRingSelectionPredicate& rhs);

Provides support for assignment in selection predicates, by assigning the type/flag set of rhs to those of the object.

const int operator==(const CRingSelectionPredicate& rhs);

Provides support for equality comparison of selection predicates by comparing the type/flag pairs of rhs to those of the object.

const int operator!=(const CRingSelectionPredicate& rhs);

Provides support for inequality comparisons of selection predicates by comparing for equality and returning the boolean inverse of the result.

virtual bool operator()(CRingBuffer& ring);

Provides a default predicate call for CRingBuffer::blockWhile. The default action is to block until an item is in the ring. when an item is in the ring, its type is retrieved and passed to selectThis. If that function returns true the item is skipped. If false is returned, and either the item type is not in the item list or is in the item list but with its flag false, then false is returned, ending the block and allowing the caller to retrieve the selected item. If the item is in the list an has a true flag, the item is skipped if it is not the most recently inserted item in the ring, otherwise blocking is terminated.

virtual = 0 bool selectThis(uint32_t type);

This is a pure virtual member that must be implemented by concrete classes. type is the item type of an item in the ring buffer. The function should return true to skip the item,and false if the item is of an acceptable type. See, however the description of operator() to see how that item type's flag can modify the interpretation of this return value.

void selectItem(CRingBuffer& ring);

This member function interacts with the ring buffer ring to block the caller, skipping items inserted in the ring until one that matches the predicate is available.

Normally, this is intended to be called from CRingItem::getFromRing.

Protected members

Protected member functions are utilities that area available to derived classes. Note that since the CRingSelectionPredicate class is an abstract base class, there can never be instances of it.

protected void addSelectionItem(uint32_t type, bool sample = false);

Adds an item type and sample flag to the set of type/flag pairs maintained by this base class. As the actual interpretation of this list is partially up to the selectThis method, this is not exposed to the public. Concrete class implementations are expected to provide an appropriately named member function that delegates to this.

protected SelectionMapIterator find(uint32_t type);

Locates type in the list of type/flag pairs. Returns a pointer like object SelectionMapIterator. This 'points' to a std::pair<uint32_t, ItemType>. If the item is not found, the iterator will compare as == to the value returned from end.

protected SelectionMapIterator end();

Returns the value that find returns if the item type searched for is not found.

protected uint32_t longswap(uint32_t input);

Swaps bytes in the longword input and returns the result.

protected void addSelectionItems(std::vector<ItemType> selections);

Calls addSelectionItem once for each item in selections.

Types and public data

While the class does not export any public data or data types, it does provide several protected data types that are important to know about if you are deriving a class from CRingSelectionPredicate. All of the type names are in the scope of CRingSelectionPredicate::.

ItemType

This is the structure that holds type/value pairs. It contains the fields s_sampled, which is the flag, and s_itemType, which is the item type.

While s_sampled is intended to convey that tiems of that s_itemType should be sampled, this is not required if the concrete class overrides operator()

This struct supports equality and inequality comparision.

SelectionMap

This is a typedef for std::map<uint32_t, ItemType>.

SelectionMapIterator

This is a typedef for SelectionMap::iterator.