deserialization.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 BMI state restore protocol. Pairs with
`NgenSerializationProtocol` (save); shares the `Record` value type
defined in `include/utilities/serialization/record.hpp`.
 
Storage is delegated to a `RecordBackend` acquired at `initialize()`
time, optionally scoped by a caller-provided `id_subset` so that a
run restoring only a known subset of features can give the backend
a chance to build a smaller index.
 
Each `run()` opens a short-lived `Reader` for the current
`ctx.id` and asks the configured match mode (`latest`, by step, or
by timestamp) for the corresponding record.
*/
#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 DESERIALIZATION_RESTORE_KEY = "restore";
constexpr const char* const DESERIALIZATION_STEP_KEY = "step";
constexpr const char* const DESERIALIZATION_STEP_LATEST = "latest";
constexpr const char* const DESERIALIZATION_TIMESTAMP_KEY = "timestamp";
constexpr const char* const DESERIALIZATION_ID_SUBSET_KEY = "id_subset";
 
class NgenDeserializationProtocol : public NgenBmiProtocol {
  public:
    NgenDeserializationProtocol(const ModelPtr& model, const Properties& properties);
    NgenDeserializationProtocol();
    virtual ~NgenDeserializationProtocol() 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:
    // Match mode. When `by_timestamp` is true,
    // `target_simulation_timestamp` is the sole matching criterion.
    // Otherwise `step_latest` (if true) finds the highest step for
    // the id, else `target_step` must match exactly.
    bool by_timestamp                   = false;
    int64_t target_simulation_timestamp = 0;
    bool step_latest                    = true;
    int target_step                     = 0;
    // Optional set of ids the caller wants indexed, parsed from
    // config in initialize() into an
    // `any_of(primary_prefix(...))` predicate. Registered with the
    // backend as this caller's contribution to the index scope —
    // records whose id fails this predicate are not indexed.
    //
    // This is the *backend-level* scope. The *per-Reader* scope
    // used inside `run()` is a tighter `exact_id(ctx.id)`
    // predicate constructed per-call so each Reader returns
    // exactly the one feature's record.
    //
    // Empty / default-constructed means "no filter".
    ::ngen::serialization::IdPredicate id_scope;
    bool supported = false;
    bool check;
    bool is_fatal;
 
    // Storage backend, acquired in initialize() via a
    // `RecordBackend`-typed factory.
    std::shared_ptr<::ngen::serialization::RecordBackend> backend_;
};
 
} // namespace protocols
} // namespace bmi
} // namespace models