framework::StorageControl Class Reference

Class which encapsulates storage control functionality, used by the Process class. More...

#include <StorageControl.h>

Public Types
enum class	Hint {   NoOpinion = 0 , Undefined = -1 , ShouldKeep = 1 , MustKeep = 10 ,   ShouldDrop = 2 , MustDrop = 20 }
	Hints that can be provided by processors to the storage controller. More...

Public Member Functions
void	setDefaultKeep (bool keep)
	Set the default state.
void	resetEventState ()
	Reset the event-by-event state.
void	addHint (const std::string &processor_name, Hint hint, const std::string &purposeString)
	Add a storage hint for a given processor.
void	addRule (const std::string &processor_pat, const std::string &purpose_pat)
	Add a listening rule.
bool	keepEvent (bool event_completed) const
	Determine if the current event should be kept, based on the defined rules.

Private Attributes
bool	defaultIsKeep_ {true}
	Default state for storage control.
std::vector< Hint >	hints_
	Collection of hints from the event processors.
std::vector< std::pair< std::regex, std::regex > >	rules_
	Collection of rules allowing certain processors or purposes to be considered ("listened to") during the storage decision.

Detailed Description

Class which encapsulates storage control functionality, used by the Process class.

Any EventProcessor can provide a hint as to whether a given event should be kept or dropped. The hint is cached in the StorageControl object until the end of the event. At that point, the process queries the StorageControl to determine if the event should be stored in the output file.

Definition at line 27 of file StorageControl.h.

Member Enumeration Documentation

Hint

enum class framework::StorageControl::Hint

strong

Hints that can be provided by processors to the storage controller.

Integer values of the hints are currently not used for anything, although one could imagine a "weighting" system being implemented where different Hints are weighted based on how "strong" the hint is.

Definition at line 36 of file StorageControl.h.

                  {
    NoOpinion = 0,
    Undefined = -1,
    ShouldKeep = 1,
    MustKeep = 10,
    ShouldDrop = 2,
    MustDrop = 20
  };  // enum Hint

Member Function Documentation

addHint()

void framework::StorageControl::addHint	(	const std::string &	processor_name,
		Hint	hint,
		const std::string &	purposeString
	)

Add a storage hint for a given processor.

This is the function eventually called when a processor uses EventProcessor::setStorageHint during processing. When a hint is added, we check it against our configured listening rules. If the hint does not match any of our listening rules, then we simply ignore it by not adding it to our internal cache that will be used later when deciding to keep the event.

Parameters

processor_name	Name of the event processor
controlhint	The storage control hint to apply for the given event
purposeString	A purpose string which can be used in the skim control configuration

Definition at line 9 of file StorageControl.cxx.

                                                             {
  for (const auto& [processor_rule, purpose_rule] : rules_) {
    if (std::regex_match(processor_name, processor_rule) and
        std::regex_match(purposeString, purpose_rule)) {
      // cache hints that matched a rule for later tallying
      hints_.push_back(hint);
      // leave after first match to avoid double-counting
      break;
    }
  }
}

References hints_, and rules_.

Referenced by framework::EventProcessor::setStorageHint().

addRule()

void framework::StorageControl::addRule	(	const std::string &	processor_pat,
		const std::string &	purpose_pat
	)

Add a listening rule.

These listening rules are regex patterns to decide if a specific hint should be counted when deciding if an event should be kept.

Parameters

processor_pattern	Regex pattern to compare with event processor
purpose_pattern	Regex pattern to compare with the purpose string

Note

Rules that don't specify a processor pattern are ignored.

Definition at line 22 of file StorageControl.cxx.

                                                           {
  if (processor_pat.empty()) return;
 
  try {
    rules_.emplace_back(
        std::piecewise_construct,
        std::forward_as_tuple(processor_pat,
                              std::regex::extended | std::regex::nosubs),
        std::forward_as_tuple(purpose_pat.empty() ? ".*" : purpose_pat,
                              std::regex::extended | std::regex::nosubs));
  } catch (const std::regex_error& e) {
    // re-throw the regex error with our error
    std::string msg{
        "Invalid regex configured for the storage control listening rules: "};
    msg += e.what();
    EXCEPTION_RAISE("ConfigureError", msg);
  }
}

References rules_.

Referenced by framework::Process::Process().

keepEvent()

bool framework::StorageControl::keepEvent

(

bool

event_completed

)

const

Determine if the current event should be kept, based on the defined rules.

Separating the 'must' keywords into their own tier helps give them greater importance that reflects their name. In order, the decision follows the criteria below only using hints that match one of the listening rules configured for the process.

1. If any hint is mustDrop, drop the event.
2. If any hint is mustKeep (without any mustDrop), keep the event.
3. Simple majority decision of votes made for keep and drop.
4. The default decision is made in the event of a tie (or no votes).

Parameters

[in]

event_completed

did we complete processing of the current event?

Returns

true if we should store the current event into the output file

Note

If event_completed is false, we don't listen to anything and decide not to keep the event.

loop over the hints provided by processors we are listening to.

mustDrop is highest priority, if it exists the event is dropped

mustKeep is second highest, if it exists when mustDrop does not, the event is kept

If we don't have any 'must' hints, we tally votes and follow the choice made by a simple majority.

If there is a tie in the vote (including the case where there were no votes), then we use the default decision.

Definition at line 45 of file StorageControl.cxx.

                                                         {
  if (not event_completed) return false;
 
  int votesKeep(0), votesDrop(0);
  bool mustDrop{false}, mustKeep{false};
  for (auto hint : hints_) {
    switch (hint) {
      case Hint::MustDrop:
        mustDrop = true;
        break;
      case Hint::MustKeep:
        mustKeep = true;
        break;
      case Hint::ShouldDrop:
        votesDrop++;
        break;
      case Hint::ShouldKeep:
        votesKeep++;
        break;
      case Hint::Undefined:
      case Hint::NoOpinion:
        break;
      default:
        // how did I get here?
        EXCEPTION_RAISE(
            "SupaBad",
            "This error comes from StorageControl and should never happen. "
            "A storage hint should always be one of the members of the "
            "StorageControlHint enum.");
    }
  }
 
  if (mustDrop) return false;
 
  if (mustKeep) return true;
 
  if (votesKeep > votesDrop) return true;
  if (votesDrop > votesKeep) return false;
 
  return defaultIsKeep_;
}

References defaultIsKeep_, and hints_.

Referenced by framework::Process::run().

resetEventState()

void framework::StorageControl::resetEventState

(

)

Reset the event-by-event state.

Definition at line 7 of file StorageControl.cxx.

{ hints_.clear(); }

References hints_.

Referenced by framework::Process::run().

setDefaultKeep()

void framework::StorageControl::setDefaultKeep ( bool  keep )

inline

Set the default state.

Definition at line 47 of file StorageControl.h.

{ defaultIsKeep_ = keep; }

References defaultIsKeep_.

Referenced by framework::Process::Process().

Member Data Documentation

defaultIsKeep_

bool framework::StorageControl::defaultIsKeep_ {true}

private

Default state for storage control.

Definition at line 106 of file StorageControl.h.

{true};

Referenced by keepEvent(), and setDefaultKeep().

hints_

std::vector<Hint> framework::StorageControl::hints_

private

Collection of hints from the event processors.

These are only the hints that are from processors matching one of the listening rules.

Definition at line 114 of file StorageControl.h.

Referenced by addHint(), keepEvent(), and resetEventState().

rules_

std::vector<std::pair<std::regex, std::regex> > framework::StorageControl::rules_

private

Collection of rules allowing certain processors or purposes to be considered ("listened to") during the storage decision.

Each rule has two entries:

1. a processor regex to match hints coming from processors named a certain way
2. a purpose regex to match hints from all processors with a specific purpose

Definition at line 127 of file StorageControl.h.

Referenced by addHint(), and addRule().

---

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

• Framework/include/Framework/StorageControl.h
• Framework/src/Framework/StorageControl.cxx