feat(bmi-protocols)!: v0.2 of the protocols lib using expected semantics for error handling

Author: hellkite500

include/utilities/bmi/mass_balance.hpp

@@ -15,17 +15,23 @@ See the License for the specific language governing permissions and
 limitations under the License.
 ------------------------------------------------------------------------
 
+Version 0.2
+Conform to updated protocol interface
+Removed integration and error exceptions in favor of ProtocolError
+
 Version 0.1
 Interface of the BMI mass balance protocol
 */
 #pragma once
 
+
 #include <string>
 #include <exception>
-#include "protocol.hpp"
+#include <protocol.hpp>
+#include <nonstd/expected.hpp>
 
 namespace models{ namespace bmi{ namespace protocols{
-
+    using nonstd::expected;
     /** Mass balance variable names **/
     constexpr const char* const INPUT_MASS_NAME = "ngen::mass_in";
     constexpr const char* const OUTPUT_MASS_NAME = "ngen::mass_out";
@@ -40,7 +46,7 @@ namespace models{ namespace bmi{ namespace protocols{
     constexpr const char* const FATAL_KEY = "fatal";
     constexpr const char* const CHECK_KEY = "check";
     constexpr const char* const FREQUENCY_KEY = "frequency";
-
+    
     class NgenMassBalance : public NgenBmiProtocol {
         /** @brief Mass Balance protocol
          * 
@@ -58,9 +64,18 @@ namespace models{ namespace bmi{ namespace protocols{
          * @param model A shared pointer to a Bmi_Adapter object which should be
          * initialized before being passed to this constructor.
          */
-        NgenMassBalance(std::shared_ptr<models::bmi::Bmi_Adapter> model=nullptr) :
-          NgenBmiProtocol(model), check(false), is_fatal(false), 
-          tolerance(1.0E-16), frequency(1){}
+        NgenMassBalance(const ModelPtr& model, const Properties& properties);
+
+        /**
+         * @brief Construct a new, default Ngen Mass Balance object
+         * 
+         * By default, the protocol is considered unsupported and won't be checked
+         */
+        NgenMassBalance();
+
+        virtual ~NgenMassBalance() override;
+
+      private:
 
         /**
          * @brief Run the mass balance protocol
@@ -76,17 +91,14 @@ namespace models{ namespace bmi{ namespace protocols{
          * throws: MassBalanceError if the mass balance is not within the configured
          *         acceptable tolerance and the protocol is configured to be fatal.
          */
-        void run(const Context& ctx) const override;
-
-        virtual ~NgenMassBalance() override {};
+        auto run(const ModelPtr& model, const Context& ctx) const -> expected<void, ProtocolError> override;
 
-      private:
         /**
          * @brief Check if the mass balance protocol is supported by the model
          * 
          * throws: MassBalanceIntegrationError if the mass balance protocol is not supported
          */
-        void check_support() override;
+        [[nodiscard]] auto check_support(const ModelPtr& model) -> expected<void, ProtocolError> override;
 
         /**
          * @brief Check the model for support and initialize the mass balance protocol from the given properties.
@@ -107,78 +119,15 @@ namespace models{ namespace bmi{ namespace protocols{
          *                      fatal: bool, default false. Whether to treat mass balance errors as fatal.
          *                   Otherwise, mass balance checking will be disabled (check will be false)
          */
-        void initialize(const geojson::PropertyMap& properties) override;
+        auto initialize(const ModelPtr& model, const Properties& properties) -> expected<void, ProtocolError> override;
 
+    private:
         // Configurable options/values
         bool check;
         bool is_fatal;
         double tolerance;
         // How often (in time steps) to check mass balance
         int frequency; 
-
-        /**
-         * @brief Friend class for checking/managing support and initialization
-         * 
-         * This allows the NgenBmiProtocols container class to access private members,
-         * particularly the check_support() and initialize() methods.
-         * 
-         */
-        friend class NgenBmiProtocols;
-
-    };
-
-    class MassBalanceIntegration : public std::exception {
-        /**
-         * @brief Exception thrown when there is an error in mass balance integration
-         * 
-         * This indicates that the BMI model isn't capable of supporting the mass balance protocol.
-         */
-
-    public:
-
-        MassBalanceIntegration(char const *const message) noexcept : MassBalanceIntegration(std::string(message)) {}
-
-        MassBalanceIntegration(std::string message) noexcept : std::exception(), what_message(std::move(message)) {}
-
-        MassBalanceIntegration(MassBalanceIntegration &exception) noexcept : MassBalanceIntegration(exception.what_message) {}
-
-        MassBalanceIntegration(MassBalanceIntegration &&exception) noexcept
-        : MassBalanceIntegration(std::move(exception.what_message)) {}
-
-        char const *what() const noexcept override {
-            return what_message.c_str();
-        }
-
-    private:
-
-        std::string what_message;
-    };
-
-    class MassBalanceError : public std::exception {
-        /**
-         * @brief Exception thrown when a mass balance error occurs
-         * 
-         * This indicates that a mass balance error has occurred within the model.
-         */
-
-    public:
-
-        MassBalanceError(char const *const message) noexcept : MassBalanceError(std::string(message)) {}
-
-        MassBalanceError(std::string message) noexcept : std::exception(), what_message(std::move(message)) {}
-
-        MassBalanceError(MassBalanceError &exception) noexcept : MassBalanceError(exception.what_message) {}
-
-        MassBalanceError(MassBalanceError &&exception) noexcept
-        : MassBalanceError(std::move(exception.what_message)) {}
-
-        char const *what() const noexcept override {
-            return what_message.c_str();
-        }
-
-    private:
-
-        std::string what_message;
     };
 
 }}}

include/utilities/bmi/protocol.hpp

@@ -15,6 +15,12 @@ See the License for the specific language governing permissions and
 limitations under the License.
 ------------------------------------------------------------------------
 
+Version 0.2
+Enumerate protocol error types and add ProtocolError exception class
+Implement error handling via expected<T, ProtocolError> and error_or_warning
+Removed model member and required model reference in run(), check_support(), and initialize()
+Minor refactoring and style changes
+
 Version 0.1
 Virtual interface for BMI protocols
 */
@@ -23,9 +29,53 @@ Virtual interface for BMI protocols
 
 #include "Bmi_Adapter.hpp"
 #include "JSONProperty.hpp"
-
+#include <nonstd/expected.hpp>
 
 namespace models{ namespace bmi{ namespace protocols{
+using nonstd::expected;
+using nonstd::make_unexpected;
+
+enum class Error{
+    UNITIALIZED_MODEL,
+    UNSUPPORTED_PROTOCOL,
+    INTEGRATION_ERROR,
+    PROTOCOL_ERROR,
+    PROTOCOL_WARNING
+};
+
+class ProtocolError: public std::exception {
+  public:
+    ProtocolError () = delete;
+    ProtocolError(Error err, const std::string& message="") : err(std::move(err)), message(std::move(message)) {}
+    ProtocolError(const ProtocolError& other) = default;
+    ProtocolError(ProtocolError&& other) noexcept = default;
+    ProtocolError& operator=(const ProtocolError& other) = default;
+    ProtocolError& operator=(ProtocolError&& other) noexcept = default;
+    ~ProtocolError() = default;
+
+    auto to_string() const -> std::string {
+        switch (err) {
+            case Error::UNITIALIZED_MODEL: return "Error(Uninitialized Model)::" + message;
+            case Error::UNSUPPORTED_PROTOCOL: return "Warning(Unsupported Protocol)::" + message;
+            case Error::INTEGRATION_ERROR: return "Error(Integration)::" + message;
+            case Error::PROTOCOL_ERROR: return "Error(Protocol)::" + message;
+            case Error::PROTOCOL_WARNING: return "Warning(Protocol)::" + message;
+            default: return "Unknown Error: " + message;
+        }
+    }
+
+  auto error_code() const -> const Error&  { return err; }
+  auto get_message() const -> const std::string&  { return message; }
+
+  char const *what() const noexcept override {
+      message = to_string();
+      return message.c_str();
+  }
+
+  private:
+    Error err;
+    mutable std::string message;
+};
 
 struct Context{
     const int current_time_step;
@@ -34,55 +84,125 @@ struct Context{
     const std::string& id;
 };
 
+using ModelPtr = std::shared_ptr<models::bmi::Bmi_Adapter>;
+using Properties = geojson::PropertyMap;
+
 class NgenBmiProtocol{
   /**
    * @brief Abstract interface for a generic BMI protocol
    * 
    */
 
   public:
+
     /**
-     * @brief Run the BMI protocol
+     * @brief Construct a new Ngen Bmi Protocol object
+     * 
+     * By default, the protocol is considered unsupported.
+     * Subclasses are responsible for implementing the check_support() method,
+     * and ensuring that is_supported is properly set based on the protocol's
+     * requirements.
      * 
      */
-    virtual void run(const Context& ctx) const = 0;
+    NgenBmiProtocol() : is_supported(false) {}
 
     virtual ~NgenBmiProtocol() = default;
 
-  private:
+  protected:
     /**
-     * @brief Check if the BMI protocol is supported by the model
+     * @brief Handle a ProtocolError by either throwing it or logging it as a warning
+     * 
+     * @param err The ProtocolError to handle
+     * @return expected<void, ProtocolError> Returns an empty expected if the error was logged as a warning,
+     *         otherwise throws the ProtocolError.
      * 
+     * @throws ProtocolError if the error is of type PROTOCOL_ERROR
      */
-    virtual void check_support() = 0;
+    static auto error_or_warning(const ProtocolError& err) -> expected<void, ProtocolError> {
+        // Log warnings, but throw errors
+        switch(err.error_code()){
+            case Error::PROTOCOL_ERROR:
+                throw err;
+                break;
+            case Error::INTEGRATION_ERROR:
+            case Error::UNITIALIZED_MODEL:
+            case Error::UNSUPPORTED_PROTOCOL:
+            case Error::PROTOCOL_WARNING:
+                std::cerr << err.to_string() << std::endl;
+                return make_unexpected<ProtocolError>( ProtocolError(std::move(err) ) );
+            default:
+                throw err;
+        }
+        assert (false && "Unreachable code reached in error_or_warning");
+    }
+
     /**
-     * @brief Initialize the BMI protocol from a set of key/value properties
+     * @brief Run the BMI protocol against the given model
      * 
-     * @param properties 
+     * Execute the logic of the protocol with the provided context and model.
+     * It is the caller's responsibility to ensure that the model provided is
+     * consistent with the model provided to the object's initialize() and
+     * check_support() methods, hence the protected nature of this function.
+     * 
+     * @param ctx Contextual information for the protocol run
+     * @param model A shared pointer to a Bmi_Adapter object which should be
+     * initialized before being passed to this method.
+     * 
+     * @return expected<void, ProtocolError> May contain a ProtocolError if
+     *         the protocol fails for any reason.  Errors of ProtocolError::PROTOCOL_WARNING
+     *         severity should be logged as warnings, but not cause the simulation to fail.
      */
-    virtual void initialize(const geojson::PropertyMap& properties) = 0;
+    [[nodiscard]] virtual auto run(const ModelPtr& model, const Context& ctx) const -> expected<void, ProtocolError> = 0;
 
-  protected:
-    
     /**
-     * @brief Constructor for subclasses to create NgenBmiProtocol objects
+     * @brief Check if the BMI protocol is supported by the model
+     * 
+     * It is the caller's responsibility to ensure that the model provided is
+     * consistent with the model provided to the object's initialize() and
+     * run() methods, hence the protected nature of this function.
      * 
      * @param model A shared pointer to a Bmi_Adapter object which should be
-     * initialized before being passed to this constructor.
+     * initialized before being passed to this method.
+     * 
+     * @return expected<void, ProtocolError> May contain a ProtocolError if
+     *         the protocol is not supported by the model.
      */
-    NgenBmiProtocol(std::shared_ptr<models::bmi::Bmi_Adapter> model): model(model){}
+    [[nodiscard]] virtual expected<void, ProtocolError> check_support(const ModelPtr& model) = 0;
 
     /**
-     * @brief The Bmi_Adapter object used by the protocol
+     * @brief Initialize the BMI protocol from a set of key/value properties
      * 
+     * It is the caller's responsibility to ensure that the model provided is
+     * consistent with the model provided to the object's run() and
+     * check_support() methods, hence the protected nature of this function.
+     * 
+     * @param properties key/value pairs for initializing the protocol
+     * @param model A shared pointer to a Bmi_Adapter object which should be
+     * initialized before being passed to this method.
+     * 
+     * @return expected<void, ProtocolError> May contain a ProtocolError if
+     *         initialization fails for any reason, since the protocol must
+     *         be effectively "optional", failed initialization results in
+     *         the protocol being disabled for the duration of the simulation.
      */
-    std::shared_ptr<models::bmi::Bmi_Adapter> model;
+    virtual auto initialize(const ModelPtr& model, const Properties& properties) -> expected<void, ProtocolError> = 0;
 
     /**
      * @brief Whether the protocol is supported by the model
      * 
      */
     bool is_supported = false;
+
+    /**
+     * @brief Friend class for managing one or more protocols
+     * 
+     * This allows the NgenBmiProtocols container class to access the protected `run()`
+     * method. This allows the container to ensure consistent application of the
+     * protocol with a particular bmi model instance throughout the lifecycle of a given
+     * protocol.
+     * 
+     */
+    friend class NgenBmiProtocols;
 }; 
 
 }}}