MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
TensorDLPack.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "Tensor.hpp"
4
5struct DLManagedTensor;
6struct DLManagedTensorVersioned;
7
8namespace MayaFlux::Kakshya {
9
10/**
11 * @brief Hand a tensor to another library through DLPack without copying.
12 * @param tensor Tensor to share; the export keeps it alive until the consumer
13 * calls the returned tensor's deleter.
14 * @return Versioned DLPack tensor flagged read-only, or nullptr when the
15 * tensor is null or invalid. The consumer owns the result and must call its
16 * deleter exactly once.
17 */
18[[nodiscard]] MAYAFLUX_API DLManagedTensorVersioned* export_dlpack(
19 std::shared_ptr<const TensorData> tensor);
20
21/**
22 * @class TensorImport
23 * @brief Owns a DLPack tensor received from another library.
24 *
25 * Takes the producer's tensor, validates it, and exposes it as a TensorAccess
26 * without copying. The producer's deleter runs when this object is destroyed
27 * or when the tensor is rejected.
28 *
29 * Usage:
30 * @code
31 * auto imported = TensorImport::take(managed);
32 * auto view = imported->access();
33 * auto owned = imported->copy();
34 * @endcode
35 *
36 * @note The data is borrowed from the producer. Its extent is derived from the
37 * shape, strides and offset, which cannot be checked against the producer's
38 * allocation.
39 */
40class MAYAFLUX_API TensorImport {
41public:
42 TensorImport(TensorImport&& other) noexcept;
43 TensorImport& operator=(TensorImport&& other) noexcept;
44 TensorImport(const TensorImport&) = delete;
47
48 /**
49 * @brief Take ownership of a versioned DLPack tensor.
50 * @param managed Tensor from a producer. Always consumed: its deleter is
51 * called on rejection as the protocol requires.
52 * @return Import, or std::nullopt for a null pointer, a different major
53 * version, a device the host cannot read or an unusable layout.
54 */
55 [[nodiscard]] static std::optional<TensorImport> take(DLManagedTensorVersioned* managed);
56
57 /** @brief Take ownership of a legacy, unversioned DLPack tensor. */
58 [[nodiscard]] static std::optional<TensorImport> take(DLManagedTensor* managed);
59
60 /** @brief Layout described by the producer. */
61 [[nodiscard]] const TensorSpec& spec() const noexcept { return m_spec; }
62 /** @brief Whether the producer marked the tensor read-only. */
63 [[nodiscard]] bool read_only() const noexcept { return m_read_only; }
64 /** @brief Borrow the producer's memory. */
65 [[nodiscard]] std::optional<TensorAccess> access() const;
66 /** @brief Dense owning copy, independent of the producer. */
67 [[nodiscard]] std::optional<TensorData> copy() const;
68
69private:
70 TensorImport(TensorSpec spec, const std::byte* data, size_t size, bool read_only,
71 std::function<void()> release) noexcept;
72
74 const std::byte* m_data {};
75 size_t m_size {};
76 bool m_read_only {};
77 std::function<void()> m_release;
78};
79
80}
TensorImport & operator=(TensorImport &&other) noexcept
const TensorSpec & spec() const noexcept
Layout described by the producer.
TensorImport(const TensorImport &)=delete
std::function< void()> m_release
static std::optional< TensorImport > take(DLManagedTensorVersioned *managed)
Take ownership of a versioned DLPack tensor.
TensorImport(TensorImport &&other) noexcept
TensorImport & operator=(const TensorImport &)=delete
bool read_only() const noexcept
Whether the producer marked the tensor read-only.
Owns a DLPack tensor received from another library.
DLManagedTensorVersioned * export_dlpack(std::shared_ptr< const TensorData > tensor)
Hand a tensor to another library through DLPack without copying.
Complete description of a tensor: type, shape, layout, meaning.