serialization.hpp

/*
Author: Nels Frazier
Copyright (C) 2025 Lynker
------------------------------------------------------------------------
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
 
    http://www.apache.org/licenses/LICENSE-2.0
 
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
------------------------------------------------------------------------
Version 0.2
Interface of the save-side ngen BMI state serialization protocol. Pairs
with NgenDeserializationProtocol (restore, see deserialization.hpp) and
shares the on-disk SerializationRecord format (see serialization_record.hpp).
Record identity per run() call is taken from Context::id.
*/
#pragma once
 
#include "utilities/serialization/record_backend.hpp"
#include <memory>
#include <nonstd/expected.hpp>
#include <protocol.hpp>
 
namespace models {
namespace bmi {
namespace protocols {
using nonstd::expected;
 
constexpr const char* const SERIALIZATION_CREATE_NAME = "ngen::serialization_create";
constexpr const char* const SERIALIZATION_FREE_NAME   = "ngen::serialization_free";
constexpr const char* const SERIALIZATION_SIZE_NAME   = "ngen::serialization_size";
constexpr const char* const SERIALIZATION_STATE_NAME  = "ngen::serialization_state";
 
constexpr const char* const SERIALIZATION_CONFIGURATION_KEY = "serialization";
constexpr const char* const SERIALIZATION_PATH_KEY = "path";
constexpr const char* const SERIALIZATION_SAVE_KEY = "save";
constexpr const char* const SERIALIZATION_CHECK_KEY     = "check";
constexpr const char* const SERIALIZATION_FATAL_KEY     = "fatal";
constexpr const char* const SERIALIZATION_FREQUENCY_KEY = "frequency";
 
struct ReservedVar {
    const char* name;
    const char* unit;
};
 
constexpr ReservedVar RESERVED_VARS[] = {
    {SERIALIZATION_CREATE_NAME, "ngen::trigger"},
    {SERIALIZATION_FREE_NAME,   "ngen::trigger"},
    {SERIALIZATION_SIZE_NAME,   "bytes"        },
    {SERIALIZATION_STATE_NAME,  "ngen::opaque" },
};
 
class NgenSerializationProtocol : public NgenBmiProtocol {
  public:
    NgenSerializationProtocol(const ModelPtr& model, const Properties& properties);
    NgenSerializationProtocol();
    virtual ~NgenSerializationProtocol() override;
 
  private:
    auto run(const ModelPtr& model, const Context& ctx) const
        -> expected<void, ProtocolError> override;
 
    nsel_NODISCARD auto check_support(const ModelPtr& model)
        -> expected<void, ProtocolError> override;
 
    auto initialize(const ModelPtr& model, const Properties& properties)
        -> expected<void, ProtocolError> override;
 
    bool is_supported() const override final;
 
  private:
    int frequency;
    bool supported = false;
    bool check;
    bool is_fatal;
 
    // Storage backend, acquired in initialize() via a
    // `RecordBackend`-typed factory. `nullptr` means save is
    // disabled / unconfigured.
    std::shared_ptr<::ngen::serialization::RecordBackend> backend_;
};
 
} // namespace protocols
} // namespace bmi
} // namespace models