Program Listing for File Transport.hpp

↰ Return to documentation for file (runtime/include/Transport.hpp)

// Copyright 2026 Xanadu Quantum Technologies Inc.

// 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.

#pragma once
#include <cstddef>
#include <cstdint>
#include <limits>
#include <stdexcept>
#include <string>

#include "TransportABI.h"

namespace catalyst::transport {

enum class MemKind : int {
    CpuRam,
    GpuHbm,
    Ddr,
    Other,
};

struct ConnectInfo {
    std::string peer;
    std::uint16_t oob_port;
};

struct MemRegion {
    void *addr = nullptr;
    std::uint64_t size = 0;
    std::uint32_t lkey = 0;
    std::uint32_t rkey = 0;
    MemKind kind = MemKind::CpuRam;
};

struct PeerRef {
    std::uint32_t rkey = 0;
    std::uint64_t remote_addr = 0;
    std::uint64_t size = 0;
};

struct ChannelDesc {
    std::string transport = "rdma";
};

class TransportSession {
  public:
    virtual ~TransportSession() = default;

    virtual int connect(const ConnectInfo &info) = 0;

    virtual MemRegion alloc_memory(std::size_t size, MemKind kind) = 0;

    virtual MemKind preferred_mem_kind() const { return MemKind::CpuRam; }

    virtual PeerRef exchange_keys(const MemRegion &local) = 0;

    virtual void establish_channel(const ChannelDesc &desc, const MemRegion &local,
                                   const PeerRef &peer) = 0;

    virtual void start() = 0;

    virtual int collect(void *const *replies, const std::uint64_t *replies_bytes,
                        std::size_t n) = 0;

    virtual void stop() = 0;

    virtual std::uint64_t last_rtt_ns() const { return 0; }
};

class ControllerSession : public TransportSession {
  public:
    // Build the work item in slot `work_item_idx` from in_bytes and out_bytes.
    virtual void commit_work_item(std::uint32_t work_item_idx, std::uint64_t in_bytes,
                                  std::uint64_t out_bytes) = 0;

    // Fire one round using work item `work_item_idx` and whatever payload is currently in
    // data_slot(). Pairs with a subsequent collect(). Returns 0 on success.
    virtual int kick(std::uint32_t work_item_idx) = 0;

    // Current round's outbound slot in the transport-owned ring. The slot's capacity is
    // backend-defined and not exposed here; prefer write_data_slot(), which enforces it.
    virtual void *data_slot() = 0;

    // Copy `bytes` of payload into the current round's outbound slot, ready for kick().
    // Throws if `bytes` exceeds what the round was committed to carry, so an oversized
    // payload will fail. `decoder_id` picks the coprocessor-side decoder for this round.
    virtual void write_data_slot(const void *src, std::uint64_t bytes,
                                 std::uint32_t decoder_id) = 0;

    // Current round's reply slot in the transport-owned reply ring.
    virtual void *reply_slot() { return nullptr; }

    // Whether the backend issues its own rounds (a hardware pacer) instead of one per kick().
    virtual bool self_paced() const { return false; }

    // Self-paced backends only: start the backend's rounds and wait until it has run them all.
    // Returns 0 once the run completes; the backend keeps its own record of the rounds.
    virtual int run_paced() { throw std::logic_error("this backend does not pace its own rounds"); }
};

using CoprocessorFn = CatalystCoprocessorFn;

inline constexpr std::size_t COPROCESSOR_FN_ERROR = std::numeric_limits<std::size_t>::max();

using CoprocessorFnInfo = CatalystCoprocessorFnInfo;

inline constexpr std::uint32_t COPROCESSOR_FN_ABI_VERSION = CATALYST_COPROCESSOR_FN_ABI_VERSION;

struct CoprocLaunchDesc {
    void *ring;                // recv request-slot ring base (device HBM or host RAM)
    std::uint32_t ring_slots;  // slot count of both rings; must be a power of two
    void *handoff;             // reply-slot ring base (engine -> session, e.g. gpu to cpu)
    void *stop;                // uint32_t teardown flag the engine polls
    std::uint64_t total;       // messages to process, or 0 = run until stopped
    void *stream;              // device queue to launch on (e.g. hipStream_t); null for host
    std::uint32_t frame_mode;  // layout of the frames in both rings
    std::uint32_t slot_stride; // bytes from one slot to the next, a power of two
};

using CoprocessorLauncherFn = int (*)(const CoprocLaunchDesc *desc, void *ctx);

enum class CoprocConvention : std::int32_t {
    PerMessage = 0, // CoprocessorFn: host, invoked once per received message
    LaunchOnce = 1, // CoprocessorLauncherFn: launches a persistent engine
};

class CoprocessorSession : public TransportSession {
  public:
    virtual void set_coprocessor_fn(CoprocessorFn /*fn*/, void * /*ctx*/) {
        throw std::logic_error(
            "transport: per-message coprocessor function not supported by this backend");
    }

    virtual void set_coprocessor_launcher(CoprocessorLauncherFn /*fn*/, void * /*ctx*/) {
        throw std::logic_error(
            "transport: launch-once coprocessor function not supported by this backend");
    }

    virtual CoprocConvention coprocessor_fn_convention() const {
        return CoprocConvention::PerMessage;
    }
};

} // namespace catalyst::transport