lci.hpp

Go to the documentation of this file.

// Copyright (c) 2025 The LCI Project Authors
// SPDX-License-Identifier: NCSA
 
#ifndef LCI_API_LCI_HPP
#define LCI_API_LCI_HPP
 
#include <memory>
#include <stdexcept>
#include <vector>
#include <string>
#include <cstring>
#include <cstdint>
#include <functional>
 
#include "lci_config.hpp"









namespace lci
{
extern const char* DEFAULT_NAME;
 
enum class attr_backend_t {
  none,
  ibv,
  ofi,
  ucx,
};
 
enum attr_net_lock_mode_t {
  LCI_NET_TRYLOCK_SEND = 1,
  LCI_NET_TRYLOCK_RECV = 1 << 1,
  LCI_NET_TRYLOCK_POLL = 1 << 2,
  LCI_NET_LOCK_MR = 1 << 3,
  LCI_NET_LOCK_ALL = LCI_NET_TRYLOCK_SEND | LCI_NET_TRYLOCK_RECV |
                     LCI_NET_TRYLOCK_POLL | LCI_NET_LOCK_MR,
  LCI_NET_TRYLOCK_MAX = 1 << 4,
};
 
// mimic std::optional as we don't want to force c++17 for now
template <typename T>
struct option_t {
  option_t() : m_value(), m_is_set(false) {}
  option_t(T value_) : m_value(value_), m_is_set(true) {}
  option_t(T value_, bool is_set_)
      : m_value(value_), m_is_set(is_set_) {}  // set default value
  T get_value_or(T default_value) const
  {
    return m_is_set ? m_value : default_value;
  }
  bool get_set_value(T* value) const
  {
    if (m_is_set) {
      *value = this->m_value;
      return true;
    }
    return false;
  }
  T get_value() const { return m_value; }
  bool is_set() const { return m_is_set; }
  operator T() const { return m_value; }
  T m_value;
  bool m_is_set;
};
}  // namespace lci
 
#include "lci_binding_pre.hpp"
 
namespace lci
{
class peer_failure_error : public std::runtime_error
{
 public:
  peer_failure_error(int failed_rank, const std::string& message)
      : std::runtime_error(message), failed_rank_(failed_rank)
  {
  }

  int failed_rank() const noexcept { return failed_rank_; }
 
 private:
  int failed_rank_;
};

enum class errorcode_t {
  done_min,     
  done,         
  done_backlog, 
  done_max,     
  posted_min,   
  posted, 
  posted_backlog, 
  posted_max,     
  retry_min,      
  retry, 
  retry_init, 
  retry_lock, 
  retry_nopacket, 
  retry_nomem,   
  retry_backlog, 
  retry_max,     
  fatal, 
};

const char* get_errorcode_str(errorcode_t errorcode);

struct error_t {
  errorcode_t errorcode;
  error_t() : errorcode(errorcode_t::retry_init) {}
  error_t(errorcode_t errorcode_) : errorcode(errorcode_) {}
  void reset_retry() { errorcode = errorcode_t::retry; }
  bool is_done() const
  {
    return errorcode > errorcode_t::done_min &&
           errorcode < errorcode_t::done_max;
  }

  bool is_posted() const
  {
    return errorcode > errorcode_t::posted_min &&
           errorcode < errorcode_t::posted_max;
  }

  bool is_retry() const
  {
    return errorcode > errorcode_t::retry_min &&
           errorcode < errorcode_t::retry_max;
  }

  const char* get_str() const { return lci::get_errorcode_str(errorcode); }
};

enum class net_opcode_t {
  SEND,         
  RECV,         
  WRITE,        
  REMOTE_WRITE, 
  READ,         
  ERROR,        
};

const char* get_net_opcode_str(net_opcode_t opcode);

enum class broadcast_algorithm_t {
  none,   
  direct, 
  tree,   
  ring,   
};

const char* get_broadcast_algorithm_str(broadcast_algorithm_t algorithm);

enum class reduce_scatter_algorithm_t {
  none,   
  direct, 
  tree,   
  ring,   
};

const char* get_reduce_scatter_algorithm_str(broadcast_algorithm_t algorithm);

enum class allreduce_algorithm_t {
  none,   
  direct, 
  tree,   
  ring,   
};

const char* get_allreduce_algorithm_str(broadcast_algorithm_t algorithm);

using net_imm_data_t = uint32_t;

struct net_status_t {
  net_opcode_t opcode;
  int rank;
  void* user_context;
  size_t length;
  net_imm_data_t imm_data;
};

const mr_t MR_HOST = mr_t();

const mr_t MR_DEVICE = mr_t(reinterpret_cast<void*>(0x1));

const mr_t MR_UNKNOWN = mr_t(reinterpret_cast<void*>(0x2));
 
inline bool mr_t::is_empty() const
{
  return reinterpret_cast<uintptr_t>(p_impl) < 3;
}

struct rmr_t {
  uintptr_t base;
  uintptr_t mr_base;
  uint64_t opaque_rkey;
  rmr_t() : base(0), mr_base(0), opaque_rkey(0) {}
  bool is_empty() const
  {
    return base == 0 && mr_base == 0 && opaque_rkey == 0;
  }
};

const rmr_t RMR_NULL = rmr_t();

using tag_t = uint64_t;

enum class direction_t {
  OUT, 
  IN,  
};

using rcomp_t = uint32_t;

const int ANY_SOURCE = -1;

const tag_t ANY_TAG = static_cast<tag_t>(-1);

enum class matching_entry_type_t : unsigned {
  send = 0, 
  recv = 1, 
};

enum class matching_policy_t : unsigned {
  none = 0,      
  rank_only = 1, 
  tag_only = 2,  
  rank_tag = 3,  
  max = 4,       
};

using matching_entry_key_t = uint64_t;
using matching_entry_val_t = void*;

enum class comp_semantic_t {
  memory,  
  network, 
};

struct allocator_base_t {
  virtual void* allocate(size_t size) = 0;
  virtual void deallocate(void* ptr) = 0;
  virtual ~allocator_base_t() = default;
};
 
struct allocator_default_t : public allocator_base_t {
  void* allocate(size_t size) { return malloc(size); }
  void deallocate(void* ptr) { free(ptr); }
};
extern allocator_default_t g_allocator_default;

struct status_t {
  error_t error = errorcode_t::retry_init;
  int rank = -1;
  void* buffer = nullptr;
  size_t size = 0;
  tag_t tag = 0;
  void* user_context = nullptr;
  status_t() = default;
  status_t(errorcode_t error_) : error(error_) {}
  explicit status_t(void* user_context_)
      : error(errorcode_t::done), user_context(user_context_)
  {
  }
  void set_done() { error = errorcode_t::done; }
  void set_posted() { error = errorcode_t::posted; }
  void set_retry() { error = errorcode_t::retry; }
  bool is_done() const { return error.is_done(); }
  bool is_posted() const { return error.is_posted(); }
  bool is_retry() const { return error.is_retry(); }
  error_t get_error() const { return error; }
  int get_rank() const { return rank; }
  void* get_buffer() const { return buffer; }
  size_t get_size() const { return size; }
  tag_t get_tag() const { return tag; }
  void* get_user_context() const { return user_context; }
};

const comp_t COMP_NULL = comp_t(reinterpret_cast<comp_impl_t*>(0x0));

const comp_t COMP_NULL_EXPECT_DONE =
    comp_t(reinterpret_cast<comp_impl_t*>(0x0));

const comp_t COMP_NULL_RETRY = comp_t(reinterpret_cast<comp_impl_t*>(0x1));

const comp_t COMP_NULL_EXPECT_DONE_OR_RETRY =
    comp_t(reinterpret_cast<comp_impl_t*>(0x1));
 
inline bool comp_t::is_empty() const
{
  return reinterpret_cast<uintptr_t>(p_impl) <= 1;
}

class comp_impl_t
{
 public:
  using attr_t = comp_attr_t;
  comp_impl_t()
  {
    attr.comp_type = attr_comp_type_t::custom;
    attr.zero_copy_am = false;
    attr.name = DEFAULT_NAME;
    attr.user_context = nullptr;
  }
  comp_impl_t(const attr_t& attr_) : attr(attr_) {}
  virtual ~comp_impl_t() = default;
  virtual void signal(status_t) = 0;
  comp_attr_t attr;
};

using comp_handler_t = void (*)(status_t status);

using reduce_op_t = void (*)(const void* left, const void* right, void* dst,
                             size_t n);
using graph_node_t = void*;

const graph_node_t GRAPH_START = reinterpret_cast<graph_node_t>(0x1);
const graph_node_t GRAPH_END = reinterpret_cast<graph_node_t>(0x2);

using graph_node_run_cb_t = status_t (*)(void* value);

const graph_node_run_cb_t GRAPH_NODE_DUMMY_CB = nullptr;

using graph_node_free_cb_t = void (*)(void* value);

using graph_edge_run_cb_t = void (*)(status_t status, void* src_value,
                                     void* dst_value);
 
}  // namespace lci
 
#include "lci_binding_post.hpp"
 
namespace lci
{
void global_initialize();
void global_finalize();
int get_rank_me();
int get_rank_n();
global_attr_t get_g_default_attr();
void set_g_default_attr(const global_attr_t& attr);
 
/***********************************************************************
 * Overloading graph_add_node for functor
 **********************************************************************/
#if __cplusplus >= 201703L
template <typename T>
status_t graph_execute_op_fn(void* value)
{
  auto op = static_cast<T*>(value);
  using result_t = std::invoke_result_t<T>;
 
  if constexpr (std::is_same_v<result_t, status_t>) {
    status_t result = (*op)();
    return result;
  } else if constexpr (std::is_same_v<result_t, errorcode_t>) {
    errorcode_t result = (*op)();
    return result;
  } else {
    (*op)();
    return errorcode_t::done;
  }
}
#else
// Specialization for status_t return type
template <typename T>
typename std::enable_if<
    std::is_same<typename std::result_of<T()>::type, status_t>::value,
    status_t>::type
graph_execute_op_fn(void* value)
{
  auto op = static_cast<T*>(value);
  status_t result = (*op)();
  return result;
}
 
// Specialization for errorcode_t return type
template <typename T>
typename std::enable_if<
    std::is_same<typename std::result_of<T()>::type, errorcode_t>::value,
    status_t>::type
graph_execute_op_fn(void* value)
{
  auto op = static_cast<T*>(value);
  errorcode_t result = (*op)();
  return result;
}
 
// Specialization for all other return types
template <typename T>
typename std::enable_if<
    !std::is_same<typename std::result_of<T()>::type, status_t>::value &&
        !std::is_same<typename std::result_of<T()>::type, errorcode_t>::value,
    status_t>::type
graph_execute_op_fn(void* value)
{
  auto op = static_cast<T*>(value);
  (*op)();
  return errorcode_t::done;
}
#endif
 
template <typename T>
void graph_free_op_fn(void* value)
{
  auto op = static_cast<T*>(value);
  delete op;
}

template <typename T>
graph_node_t graph_add_node_op(comp_t graph, const T& op)
{
  graph_node_run_cb_t wrapper = graph_execute_op_fn<T>;
  T* fn = new T(op);
  graph_node_free_cb_t free_cb = graph_free_op_fn<T>;
  auto ret = graph_add_node_x(graph, wrapper)
                 .value(reinterpret_cast<void*>(fn))
                 .free_cb(free_cb)();
  fn->user_context(ret);
  return ret;
}
 
}  // namespace lci
 
#endif  // LCI_API_LCI_HPP