Catalyst

Development

Examples

API

  1. Docs
  2. Program Listing for File Transport.hpp

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 <stdexcept>
#include <string>

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; }
};

using CoprocessorFn = std::size_t (*)(const void *in, std::size_t in_len, void *out,
                                      std::size_t out_cap, void *ctx);

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
};

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