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 <string>

namespace catalyst::transport {

enum class MemKind : std::uint8_t {
    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 data_path = "cpu_verbs";
};

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 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.
    virtual void *data_slot() = 0;
};

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

class CoprocessorSession : public TransportSession {
  public:
    virtual void set_coprocessor_fn(CoprocessorFn fn, void *ctx) = 0;
};

} // namespace catalyst::transport