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.

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.

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.


const Capability *	query (std::string capability) const
	Query a capability, if it exists, otherwise nullptr.

Capability *	query (std::string capability)


const Capability &	get (const std::string &capability) const
	Get a capability.

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.

Protected Attributes
RegistryType	_registry
	Registry storage.

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.

{
  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;
}

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

◆ 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]

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));
}

◆ get() [2/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.

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

Referenced by Moose::internal::Capabilities::isInstallationType(), and MooseApp::setupOptions().

◆ query() [1/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));
}

◆ query() [2/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.

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

Referenced by check(), and get().

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

135{ return _registry.size(); }

Friends And Related Symbol 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

Classes

Public Types

Public Member Functions

Static Public Attributes

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ RegistryType

Member Enumeration Documentation

◆ CheckState

Constructor & Destructor Documentation

◆ ~CapabilityRegistry()

Member Function Documentation

◆ add()

◆ check()

◆ get() [1/2]

◆ get() [2/2]

◆ query() [1/2]

◆ query() [2/2]

◆ size()

Friends And Related Symbol Documentation

◆ ::CapabilitiesTest

Member Data Documentation

◆ _registry

◆ augmented_capability_names