MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
TensorAccess.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "TensorSpec.hpp"
4
5namespace MayaFlux::Kakshya {
6
7class TensorAccess;
8
9/**
10 * @struct TensorGpuView
11 * @brief Pointer, byte count and element format for uploading a tensor.
12 */
14 const void* data {};
15 size_t bytes {};
16 std::optional<GpuDataFormat> format;
17};
18
19/**
20 * @brief Validate and borrow tensor memory.
21 * @param storage Memory the spec addresses, from its first byte.
22 * @param spec Layout to interpret the memory with.
23 * @param read_only Whether writers must treat the memory as immutable.
24 * @return Access view, or std::nullopt (with the reason logged) when the spec
25 * is inconsistent, addresses memory outside @p storage, or lives on a device
26 * the host cannot read.
27 */
28[[nodiscard]] MAYAFLUX_API std::optional<TensorAccess> as_tensor_access(
29 std::span<const std::byte> storage, const TensorSpec& spec, bool read_only = true);
30
31/**
32 * @class TensorAccess
33 * @brief Validated, non-owning view of tensor memory and its layout.
34 *
35 * Works over any host memory: a TensorData, a DataVariant store, a mapped
36 * file or an imported DLPack tensor. Nothing is converted or copied.
37 *
38 * Usage:
39 * @code
40 * auto access = tensor.access();
41 * auto values = access->as<float>();
42 * auto upload = access->gpu_view();
43 * @endcode
44 *
45 * @note The borrowed memory must outlive the view.
46 */
47class MAYAFLUX_API TensorAccess {
48public:
49 /** @brief Layout of the borrowed memory. */
50 [[nodiscard]] const TensorSpec& spec() const noexcept { return m_spec; }
51 /** @brief Whether writers must treat the memory as immutable. */
52 [[nodiscard]] bool read_only() const noexcept { return m_read_only; }
53 /** @brief The whole borrowed region. */
54 [[nodiscard]] std::span<const std::byte> storage() const noexcept { return m_storage; }
55 /** @brief Pointer to element zero, or nullptr for an empty tensor. */
56 [[nodiscard]] const std::byte* element_data() const noexcept;
57 /** @brief Number of elements. */
58 [[nodiscard]] uint64_t element_count() const noexcept;
59
60 /**
61 * @brief Bytes of the elements when they are dense in C order.
62 * @return The packed bytes, or an empty span for a strided layout.
63 */
64 [[nodiscard]] std::span<const std::byte> bytes() const noexcept;
65
66 /**
67 * @brief Elements as a typed span.
68 * @tparam T Element type that equals the tensor dtype exactly.
69 * @return Span over the elements, or empty on a dtype mismatch, a strided
70 * layout or a misaligned address.
71 */
72 template <TensorElement T>
73 [[nodiscard]] std::span<const T> as() const noexcept
74 {
75 if (!m_spec.dtype.is<T>())
76 return {};
77 const auto raw = bytes();
78 if (raw.empty() || reinterpret_cast<uintptr_t>(raw.data()) % alignof(T) != 0)
79 return {};
80 return { reinterpret_cast<const T*>(raw.data()), raw.size() / sizeof(T) };
81 }
82
83 /**
84 * @brief Upload description for a dense tensor.
85 * @return Pointer, bytes and format; data is null for a strided layout.
86 */
87 [[nodiscard]] TensorGpuView gpu_view() const noexcept;
88
89 /** @brief Dimension descriptors with sizes and strides from the spec. */
90 [[nodiscard]] std::vector<DataDimension> dimensions() const { return m_spec.dimensions(); }
91
92private:
93 friend MAYAFLUX_API std::optional<TensorAccess> as_tensor_access(
94 std::span<const std::byte>, const TensorSpec&, bool);
95
96 TensorAccess(std::span<const std::byte> storage, TensorSpec spec, bool read_only)
98 , m_spec(std::move(spec))
100 {
101 }
102
103 std::span<const std::byte> m_storage;
106};
107
108}
std::span< const T > as() const noexcept
Elements as a typed span.
bool read_only() const noexcept
Whether writers must treat the memory as immutable.
TensorAccess(std::span< const std::byte > storage, TensorSpec spec, bool read_only)
std::span< const std::byte > bytes() const noexcept
Bytes of the elements when they are dense in C order.
std::span< const std::byte > m_storage
const TensorSpec & spec() const noexcept
Layout of the borrowed memory.
std::span< const std::byte > storage() const noexcept
The whole borrowed region.
std::vector< DataDimension > dimensions() const
Dimension descriptors with sizes and strides from the spec.
Validated, non-owning view of tensor memory and its layout.
A C++ scalar or std::complex that maps to a TensorDType.
std::optional< TensorAccess > as_tensor_access(std::span< const std::byte > storage, const TensorSpec &spec, bool read_only)
Validate and borrow tensor memory.
Minimal dimension descriptor focusing on structure only.
Definition NDData.hpp:199
std::optional< GpuDataFormat > format
Pointer, byte count and element format for uploading a tensor.
Complete description of a tensor: type, shape, layout, meaning.