Moose::internal::CapabilityRegistry Class Reference

Registry of capabilities that checks capability requirements. More...

#include <CapabilityRegistry.h>

Inheritance diagram for Moose::internal::CapabilityRegistry:

Classes
struct	CheckOptions
	Options for check(). More...
struct	CheckResult
	Storage for the result from check(). More...

Public Types
enum	CheckState {   CERTAIN_FAIL = 0, POSSIBLE_FAIL = 1, UNKNOWN = 2, POSSIBLE_PASS = 3,   CERTAIN_PASS = 4, IGNORE = 5 }
	Return state for check. More...
using	RegistryType = std::map< std::string, Capability, std::less<> >
	Type for the registry. More...

Public Member Functions
	~CapabilityRegistry ()=default
Capability &	add (const std::string_view name, const Moose::Capability::Value &value, const std::string_view doc)
	Add a capability. More...
std::size_t	size () const
CheckResult	check (std::string requirements, const CapabilityRegistry::CheckOptions &options=CapabilityRegistry::CheckOptions()) const
	Checks if a set of requirements is satisified by the capabilities. More...
const Capability *	query (std::string capability) const
	Query a capability, if it exists, otherwise nullptr. More...
Capability *	query (std::string capability)
const Capability &	get (const std::string &capability) const
	Get a capability. More...
Capability &	get (const std::string &capability)

Static Public Attributes
static const std::set< std::string, std::less<> >	augmented_capability_names
	Capabilities that are reserved and can only be augmented. More...

Protected Attributes
RegistryType	_registry
	Registry storage. More...

Friends
class	::CapabilitiesTest

Detailed Description

Registry of capabilities that checks capability requirements.

This registry is used both within MOOSE (in framework/src/base/Capabilities.C) and within the python interface (in python/pycapabilities/_pycapabilities.C).

Definition at line 34 of file CapabilityRegistry.h.

Member Typedef Documentation

RegistryType

using Moose::internal::CapabilityRegistry::RegistryType = std::map<std::string, Capability, std::less<> >

Type for the registry.

Definition at line 43 of file CapabilityRegistry.h.

Member Enumeration Documentation

CheckState

enum Moose::internal::CapabilityRegistry::CheckState

Return state for check.

We use a plain enum because we rely on implicit conversion to int. Capability checks are run in the test harness using the JSON dump exported from the executable using --show-capabilities. This static check does not take dynamic loading into account, as capabilities that would be registered after initializing the dynamically loaded application will not exist with --show-capabilities.

A requested capability that is not registered at all is considered in a "possible" state, as we cannot guarantee that it does or not exist with a dynamic application. If no dynamic application loading is used, the possible states can be considered certain states.

When the test harness Tester specification "dynamic_capabilities" is set to True, it will run the test unless the result of the check is CERTAIN_FAIL. In this case, the runtime check in the executable will terminate if the result is either CERTAIN_FAIL or POSSIBLE_FAIL.

Enumerator
CERTAIN_FAIL
POSSIBLE_FAIL
UNKNOWN
POSSIBLE_PASS
CERTAIN_PASS
IGNORE

Definition at line 61 of file CapabilityRegistry.h.

  {
    CERTAIN_FAIL = 0,
    POSSIBLE_FAIL = 1,
    UNKNOWN = 2,
    POSSIBLE_PASS = 3,
    CERTAIN_PASS = 4,
    IGNORE = 5
  };

Constructor & Destructor Documentation

~CapabilityRegistry()

Moose::internal::CapabilityRegistry::~CapabilityRegistry ( )

default

Member Function Documentation

add()

Capability & Moose::internal::CapabilityRegistry::add	(	const std::string_view	name,
		const Moose::Capability::Value &	value,
		const std::string_view	doc
	)

Add a capability.

Parameters

registry	The registry
capability	The name of the capability
value	The value of the capability
doc	The documentation string

Returns

The capability

Definition at line 34 of file CapabilityRegistry.C.

Referenced by Registry::addDataFilePathCapability(), Moose::internal::Capabilities::augment(), AppFactory::registerAppCapability(), and Moose::internal::Capabilities::registerMooseCapabilities().

{
  auto it_pair = _registry.lower_bound(name);
  if (it_pair != _registry.end() && it_pair->first == name)
  {
    auto & capability = it_pair->second;
    if (capability.getValue() != value || capability.getDoc() != doc)
      throw CapabilityException("Capability '" + std::string(name) +
                                "' already exists and is not equal");
    return capability;
  }

  return _registry
      .emplace_hint(it_pair,
                    std::piecewise_construct,
                    std::forward_as_tuple(name),
                    std::forward_as_tuple(name, value, doc))
      ->second;
}

check()

CapabilityRegistry::CheckResult Moose::internal::CapabilityRegistry::check	(	std::string	requirements,
		const CapabilityRegistry::CheckOptions &	options = CapabilityRegistry::CheckOptions()
	)		const

Checks if a set of requirements is satisified by the capabilities.

Parameters

requirements	The requirement string
options	Options to apply to the check

This method is exposed to Python within pycapabilities.Capabilities.check in python/pycapabilities/_pycapabilities.C. This external method is used significantly by the TestHarness to check capabilities for individual test specs.

Additionally, this method is used by the MooseApp command line option "--required-capabilities ...".

Requirements can use comparison operators (>,<,>=,<=,=!,=), where the name of the capability must always be on the left hand side. Comparisons can be performed on strings "compiler!=GCC" (which are case insensitive), integer numbers "ad_size>=50", and version numbers "petsc>3.8.0". The state of a boolean valued capability can be tested by just specifying the capability name "chaco". This check can be inverted using the ! operator as "!chaco".

The logic operators & and | can be used to chain multiple checks as "thermochimica & thermochimica>1.0". Parenthesis can be used to build complex logic expressions.

Definition at line 86 of file CapabilityRegistry.C.

{
  using namespace peg;

  // unquote
  while (true)
  {
    const auto len = requirements.length();
    if (len >= 2 && ((requirements[0] == '\'' && requirements[len - 1] == '\'') ||
                     (requirements[0] == '"' && requirements[len - 1] == '"')))
      requirements = requirements.substr(1, len - 2);
    else
      break;
  }

  CheckResult result;
  result.state = CheckState::CERTAIN_FAIL;

  if (requirements.length() == 0)
  {
    result.state = CheckState::CERTAIN_PASS;
    return result;
  }

  static parser parser(R"(
    Expression    <-  _ Bool _ LogicOperator _ Expression / Bool _
    Bool          <-  Comparison / '!' Bool / '!' Identifier / Identifier / '(' _ Expression _ ')'
    Comparison    <-  Identifier _ Operator _ Version / Identifier _ Operator _ String
    String        <-  [a-zA-Z0-9_-]+
    Identifier    <-  [a-zA-Z][a-zA-Z0-9_]*
    Operator      <-  [<>=!]+
    LogicOperator <-  [&|]
    Version       <-  Number '.' Version  / Number
    Number        <-  [0-9]+
    ~_            <-  [ \t]*
  )");

  if (!static_cast<bool>(parser))
    throw CapabilityException("Capabilities parser build failure.");

  // Keep track of unknown capabilities in the event that
  // the check must be certain
  std::set<std::string> unknown_capabilities;
  const auto add_unknown_capability = [&unknown_capabilities](const auto & name)
  { unknown_capabilities.insert(MooseUtils::toLower(name)); };

  // Make sure that the capabilities to ignore are valid capabilities
  for (const auto & name : options.ignore_capabilities)
    if (!_registry.count(name))
      throw CapabilityException("Capability to ignore '" + name + "' is not known");

  parser["Number"] = [](const SemanticValues & vs) { return vs.token_to_number<int>(); };

  parser["Version"] = [](const SemanticValues & vs)
  {
    switch (vs.choice())
    {
      case 0: // Number '.' Version
      {
        std::vector<int> ret{std::any_cast<int>(vs[0])};
        const auto & vs1 = std::any_cast<std::vector<int>>(vs[1]);
        ret.insert(ret.end(), vs1.begin(), vs1.end());
        return ret;
      }

      case 1: // Number
        return std::vector<int>{std::any_cast<int>(vs[0])};
    }

    checkException(vs, "unknown number match.");
  };

  enum LogicOperator
  {
    OP_AND,
    OP_OR
  };

  parser["LogicOperator"] = [](const SemanticValues & vs)
  {
    const auto op = vs.token();
    if (op == "&")
      return OP_AND;
    if (op == "|")
      return OP_OR;
    checkException(vs, "unknown logic operator.");
  };

  enum Operator
  {
    OP_LESS_EQ,
    OP_GREATER_EQ,
    OP_LESS,
    OP_GREATER,
    OP_NOT_EQ,
    OP_EQ
  };

  parser["Operator"] = [](const SemanticValues & vs)
  {
    const auto op = vs.token();
    if (op == "<=")
      return OP_LESS_EQ;
    if (op == ">=")
      return OP_GREATER_EQ;
    if (op == "<")
      return OP_LESS;
    if (op == ">")
      return OP_GREATER;
    if (op == "!=")
      return OP_NOT_EQ;
    if (op == "=" || op == "==")
      return OP_EQ;
    checkException(vs, "unknown operator.");
  };

  parser["String"] = [](const SemanticValues & vs) { return vs.token_to_string(); };
  parser["Identifier"] = [](const SemanticValues & vs) { return vs.token_to_string(); };

  parser["Comparison"] =
      [this, &add_unknown_capability, &options, &result](const SemanticValues & vs)
  {
    const auto left = std::any_cast<std::string>(vs[0]);
    const auto op = std::any_cast<Operator>(vs[1]);

    // check existence
    const auto capability_ptr = query(left);
    if (!capability_ptr)
    {
      // return an unknown if the capability does not exist, this is important as it
      // stays unknown upon negation
      add_unknown_capability(left);
      return CheckState::UNKNOWN;
    }

    // capability is registered by the app
    const auto & capability = *capability_ptr;
    const auto & name = capability.getName();

    // register capability as seen
    result.capability_names.insert(name);

    // whether or not the capability is ignored
    const auto is_ignored = [&name, &options]() { return options.ignore_capabilities.count(name); };

    // explicitly false causes any comparison to fail unless ignored
    if (const auto bool_ptr = capability.queryBoolValue(); (bool_ptr && !(*bool_ptr)))
      return is_ignored() ? CheckState::IGNORE : CheckState::CERTAIN_FAIL;

    // comparator
    auto comp = [&is_ignored](const int i, const auto & a, const auto & b)
    {
      // early exit for ignored capabilities
      if (is_ignored())
        return CheckState::IGNORE;

      // do the comparison
      const auto do_comp = [&i, &a, &b]()
      {
        switch (i)
        {
          case OP_LESS_EQ:
            return a <= b;
          case OP_GREATER_EQ:
            return a >= b;
          case OP_LESS:
            return a < b;
          case OP_GREATER:
            return a > b;
          case OP_NOT_EQ:
            return a != b;
          case OP_EQ:
            return a == b;
        }
        return false;
      };
      return do_comp() ? CheckState::CERTAIN_PASS : CheckState::CERTAIN_FAIL;
    };

    // version comparison
    std::vector<int> app_value_version;

    switch (vs.choice())
    {
      case 0: // Identifier _ Operator _ Version
      {
        // int comparison
        const auto right = std::any_cast<std::vector<int>>(vs[2]);
        if (const auto int_ptr = capability.queryIntValue())
        {
          if (right.size() != 1)
            checkException(vs, "cannot be compared to a version.", capability);

          return comp(op, *int_ptr, right[0]);
        }

        const auto string_ptr = capability.queryStringValue();
        if (!string_ptr)
          checkException(vs,
                         "cannot be compared to a " +
                             std::string(right.size() == 1 ? "number" : "version number") + ".",
                         capability);

        if (!MooseUtils::tokenizeAndConvert(*string_ptr, app_value_version, "."))
          checkException(vs, "cannot be compared to a version.", capability);

        // compare versions
        return comp(op, app_value_version, right);
      }

      case 1: // Identifier _ Operator _ String
      {
        // here we would check for valid options and throw if not valid
        const auto right = MooseUtils::toLower(std::any_cast<std::string>(vs[2]));
        // the capability value has to be a string
        const auto string_ptr = capability.queryStringValue();
        if (!string_ptr)
          checkException(vs, "cannot be compared to a string.", capability);

        // If this capability has an enumeration, make sure a valid
        // choice is used
        if (!capability.hasEnumeration(right))
          checkException(vs,
                         "'" + right + "' invalid for capability '" + left +
                             "'; valid values: " + capability.enumerationToString());

        // Capability is a version
        if (MooseUtils::tokenizeAndConvert(*string_ptr, app_value_version, "."))
          checkException(vs, "cannot be compared to a string.", capability);

        return comp(op, *string_ptr, right);
      }
    }

    checkException(vs, "failed comparison.", capability);
  };

  parser["Bool"] = [this, &add_unknown_capability, &options, &result](const SemanticValues & vs)
  {
    switch (vs.choice())
    {
      case 0: // Comparison
      case 4: // '(' _ Expression _ ')'
        return std::any_cast<CheckState>(vs[0]);

      case 1: // '!' Bool
        switch (std::any_cast<CheckState>(vs[0]))
        {
          case CheckState::CERTAIN_FAIL:
            return CheckState::CERTAIN_PASS;
          case CheckState::CERTAIN_PASS:
            return CheckState::CERTAIN_FAIL;
          case CheckState::POSSIBLE_FAIL:
            return CheckState::POSSIBLE_PASS;
          case CheckState::POSSIBLE_PASS:
            return CheckState::POSSIBLE_FAIL;
          case CheckState::IGNORE:
            return CheckState::IGNORE;
          default:
            return CheckState::UNKNOWN;
        }

      case 2: // '!' Identifier
      case 3: // Identifier
      {
        const bool negated = vs.choice() == 2;
        const auto identifier = std::any_cast<std::string>(vs[0]);
        if (const auto capability_ptr = query(identifier))
        {
          const auto & capability = *capability_ptr;
          const auto & name = capability.getName();

          // explicit; cannot be a bool expression
          if (capability.getExplicit())
          {
            std::string message = "capability '" + name +
                                  "' requires a value and cannot be used in a boolean expression";
            if (capability.queryEnumeration())
              message += "; valid values: " + capability.enumerationToString();
            checkException(vs, message);
          }

          // mark as used
          result.capability_names.insert(name);
          // is ignored
          if (options.ignore_capabilities.count(name))
            return CheckState::IGNORE;

          // helper for negating a passing value if needed
          const auto bool_to_pass = [&negated](const bool val)
          { return (val ^ negated) ? CheckState::CERTAIN_FAIL : CheckState::CERTAIN_PASS; };
          // has a boolean value, so use it
          if (const auto bool_ptr = capability.queryBoolValue())
            return bool_to_pass(!*bool_ptr);
          // not ignored and doesn't have a boolean value
          return bool_to_pass(false);
        }

        add_unknown_capability(identifier);
        return negated ? CheckState::POSSIBLE_PASS : CheckState::POSSIBLE_FAIL;
      }

      default:
        throw CapabilityException("Unknown choice in Bool non-terminal");
    }
  };

  parser["Expression"] = [](const SemanticValues & vs)
  {
    switch (vs.choice())
    {
      case 0: // Bool _ LogicOperator _ Expression
      {
        const auto left = std::any_cast<CheckState>(vs[0]);
        const auto right = std::any_cast<CheckState>(vs[2]);
        const auto op = std::any_cast<LogicOperator>(vs[1]);

        switch (op)
        {
          case OP_AND:
            if (left == CheckState::IGNORE)
              return right;
            if (right == CheckState::IGNORE)
              return left;
            for (const auto state : {CheckState::CERTAIN_FAIL,
                                     CheckState::POSSIBLE_FAIL,
                                     CheckState::UNKNOWN,
                                     CheckState::POSSIBLE_PASS,
                                     CheckState::CERTAIN_PASS})
              if (left == state || right == state)
                return state;
            throw CapabilityException("Conjunction failure");

          case OP_OR:
            if (left == CheckState::IGNORE || right == CheckState::IGNORE)
              return CheckState::IGNORE;
            for (const auto state : {CheckState::CERTAIN_PASS,
                                     CheckState::POSSIBLE_PASS,
                                     CheckState::UNKNOWN,
                                     CheckState::POSSIBLE_FAIL,
                                     CheckState::CERTAIN_FAIL})
              if (left == state || right == state)
                return state;
            throw CapabilityException("Conjunction failure");

          default:
            throw CapabilityException("Unknown logic operator");
        }
      }

      case 1: // Bool
        return std::any_cast<CheckState>(vs[0]);

      default:
        throw CapabilityException("Unknown choice in Expression non-terminal");
    }
  };

  // (4) Parse
  parser.enable_packrat_parsing(); // Enable packrat parsing.

  if (!parser.parse(requirements, result.state))
    throw CapabilityException("Unable to parse requested capabilities '", requirements, "'.");

  // If certain and unknown capabilities were found, throw accordingly
  if (options.certain && unknown_capabilities.size())
    throw UnknownCapabilitiesException({unknown_capabilities.begin(), unknown_capabilities.end()});

  // Consider an ignored state to be a pass
  if (result.state == CheckState::IGNORE)
    result.state = CheckState::CERTAIN_PASS;

  return result;
}

get() [1/2]

const Capability & Moose::internal::CapabilityRegistry::get

(

const std::string &

capability

)

const

Get a capability.

Will convert the capability name to lowercase.

Definition at line 66 of file CapabilityRegistry.C.

Referenced by MooseApp::setupOptions().

{
  if (const auto capability_ptr = query(capability))
    return *capability_ptr;
  throw CapabilityException("Capability '" + capability + "' not registered");
}

get() [2/2]

Capability & Moose::internal::CapabilityRegistry::get ( const std::string &  capability )

inline

Definition at line 184 of file CapabilityRegistry.h.

{
  return const_cast<Capability &>(std::as_const(*this).get(capability));
}

query() [1/2]

const Capability * Moose::internal::CapabilityRegistry::query

(

std::string

capability

)

const

Query a capability, if it exists, otherwise nullptr.

Will convert the capability name to lowercase.

Definition at line 57 of file CapabilityRegistry.C.

Referenced by check(), and get().

{
  capability = MooseUtils::toLower(capability);
  if (const auto it = _registry.find(capability); it != _registry.end())
    return &it->second;
  return nullptr;
}

query() [2/2]

Capability * Moose::internal::CapabilityRegistry::query ( std::string  capability )

inline

Definition at line 176 of file CapabilityRegistry.h.

{
  return const_cast<Capability *>(std::as_const(*this).query(capability));
}

size()

std::size_t Moose::internal::CapabilityRegistry::size ( ) const

inline

Returns

The size of the registry (number of capabilities registered).

Definition at line 135 of file CapabilityRegistry.h.

{ return _registry.size(); }

Friends And Related Function Documentation

::CapabilitiesTest

friend class ::CapabilitiesTest

friend

Definition at line 167 of file CapabilityRegistry.h.

Member Data Documentation

_registry

RegistryType Moose::internal::CapabilityRegistry::_registry

protected

Registry storage.

Definition at line 171 of file CapabilityRegistry.h.

Referenced by add(), check(), Moose::internal::Capabilities::dump(), query(), and size().

augmented_capability_names

const std::set< std::string, std::less<> > Moose::internal::CapabilityRegistry::augmented_capability_names

static

Initial value:

{
    
    "hpc",
    "machine",
    "library_mode",
    
    "mpi_procs",
    "num_threads"}

Capabilities that are reserved and can only be augmented.

Definition at line 38 of file CapabilityRegistry.h.

---

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

• include/base/CapabilityRegistry.h
• src/base/CapabilityRegistry.C