tpl_ca_async_engine.H

Go to the documentation of this file.

/*
                          Aleph_w
 
  Data structures & Algorithms
  version 2.0.0b
  https://github.com/lrleon/Aleph-w
 
  This file is part of Aleph-w library
 
  Copyright (c) 2002-2026 Leandro Rabindranath Leon
 
  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal
  in the Software without restriction, including without limitation the rights
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:
 
  The above copyright notice and this permission notice shall be included in all
  copies or substantial portions of the Software.
 
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
*/
 
#ifndef TPL_CA_ASYNC_ENGINE_H
#define TPL_CA_ASYNC_ENGINE_H
 
#include <cstddef>
#include <functional>
#include <type_traits>
#include <utility>
 
#include <ah-errors.H>
 
#include <ca-traits.H>
#include <tpl_ca_concepts.H>
#include <tpl_ca_neighborhood.H>
#include <tpl_ca_update_scheme.H>
 
namespace Aleph {
namespace CA {
 
namespace ca_async_engine_detail {
 
template <typename Scheme, typename Engine, typename Rule>
concept HasApplyWithOrigin
  = requires(const Scheme &s, Engine &e, Rule &r, ca_index_t o) { s.apply_with_origin(e, r, o); };
 
}  // namespace ca_async_engine_detail
 
template <std::size_t Rank>
class Null_Neighborhood
{
public:
  static constexpr std::size_t rank_v = Rank;
  static constexpr std::size_t size_v = 0;
  static constexpr std::size_t radius_v = 0;
  using coord_type = Coord_Vec<Rank>;
 
  [[nodiscard]] static constexpr std::size_t radius() noexcept
  {
    return 0;
  }
 
  [[nodiscard]] static constexpr std::size_t size() noexcept
  {
    return 0;
  }
 
  template <typename F>
  static constexpr void for_each_offset(const coord_type &, F &&) noexcept
  {}
};
 
template <typename Lattice, typename Rule, typename Neighborhood, typename Update_Scheme = Synchronous_Update<RowMajor>>
class Async_Engine
{
  static_assert(LatticeLike<Lattice>, "Async_Engine requires a LatticeLike lattice");
  static_assert(NeighborhoodLike<Neighborhood>,
                "Async_Engine requires a NeighborhoodLike neighborhood (use Null_Neighborhood for "
                "block rules)");
  static_assert(Neighborhood::rank_v == Lattice::rank, "Neighborhood rank must match lattice rank");
 
public:
  using lattice_type = Lattice;
  using rule_type = Rule;
  using neighborhood_type = Neighborhood;
  using scheme_type = Update_Scheme;
 
  using state_type = typename Lattice::state_type;
  using coord_type = typename Lattice::coord_type;
  using extents_type = typename Lattice::extents_type;
 
  static constexpr std::size_t rank = Lattice::rank;
 
  using hook_type = std::function<void(std::size_t, const Lattice &)>;
 
private:
  Lattice cur_;
  Lattice nxt_;  // empty for in-place schemes
  Rule rule_;
  Neighborhood nh_;
  Update_Scheme scheme_;
  hook_type pre_hook_;
  hook_type post_hook_;
  std::size_t step_count_ = 0;
 
public:
  Async_Engine(Lattice initial, Rule r, Neighborhood n, Update_Scheme s = {})
    : cur_(std::move(initial)), rule_(std::move(r)), nh_(std::move(n)), scheme_(std::move(s))
  {
    if constexpr (Update_Scheme::requires_double_buffer)
      nxt_ = Lattice(cur_.extents());
  }
 
  Async_Engine(Lattice initial, Rule r, Update_Scheme s = {})
    requires std::default_initializable<Neighborhood>
    : Async_Engine(std::move(initial), std::move(r), Neighborhood{}, std::move(s))
  {}
 
  [[nodiscard]] const Lattice &frame() const noexcept
  {
    return cur_;
  }
 
  [[nodiscard]] std::size_t steps_run() const noexcept
  {
    return step_count_;
  }
 
  [[nodiscard]] const extents_type &extents() const noexcept
  {
    return cur_.extents();
  }
 
  [[nodiscard]] const Neighborhood &neighborhood() const noexcept
  {
    return nh_;
  }
 
  [[nodiscard]] Lattice &current_buffer() noexcept
  {
    return cur_;
  }
 
  [[nodiscard]] const Lattice &current_buffer() const noexcept
  {
    return cur_;
  }
 
  [[nodiscard]] Lattice &write_lattice() noexcept
  {
    return cur_;
  }
 
  void set_step_count(const std::size_t s) noexcept
  {
    step_count_ = s;
  }
 
  [[nodiscard]] Lattice &next_buffer() noexcept
  {
    return nxt_;
  }
 
  [[nodiscard]] Rule &rule() noexcept
  {
    return rule_;
  }
 
  [[nodiscard]] const Rule &rule() const noexcept
  {
    return rule_;
  }
 
  [[nodiscard]] const Update_Scheme &scheme() const noexcept
  {
    return scheme_;
  }
 
  [[nodiscard]] std::size_t step_count() const noexcept
  {
    return step_count_;
  }
 
  void swap_buffers() noexcept(noexcept(cur_.swap(nxt_)))
  {
    cur_.swap(nxt_);
  }
 
  template <typename F>
  void on_pre_step(F &&f)
  {
    pre_hook_ = std::forward<F>(f);
  }
 
  template <typename F>
  void on_post_step(F &&f)
  {
    post_hook_ = std::forward<F>(f);
  }
 
  void step()
  {
    if constexpr (HasRefreshHalo<Lattice>)
      cur_.refresh_halo();
 
    if (pre_hook_)
      pre_hook_(step_count_, cur_);
 
    scheme_.apply(*this, rule_);
    ++step_count_;
 
    if (post_hook_)
      post_hook_(step_count_, cur_);
  }
 
  void step_back()
    requires ca_async_engine_detail::HasApplyWithOrigin<Update_Scheme, Async_Engine, Rule>
  {
    ah_out_of_range_error_if(step_count_ == 0) << "Async_Engine::step_back: no step to reverse";
 
    --step_count_;
    if constexpr (HasRefreshHalo<Lattice>)
      cur_.refresh_halo();
 
    if (pre_hook_)
      pre_hook_(step_count_, cur_);
 
    scheme_.apply_with_origin(*this, rule_, Update_Scheme::origin_for_step(step_count_));
 
    if (post_hook_)
      post_hook_(step_count_, cur_);
  }
 
  void run(const std::size_t steps)
  {
    for (std::size_t i = 0; i < steps; ++i)
      step();
  }
 
  void run_back(const std::size_t steps)
    requires ca_async_engine_detail::HasApplyWithOrigin<Update_Scheme, Async_Engine, Rule>
  {
    for (std::size_t i = 0; i < steps; ++i)
      step_back();
  }
};
 
}  // namespace CA
}  // namespace Aleph
 
#endif  // TPL_CA_ASYNC_ENGINE_H