Radient: add reference-counted data blob API

- Support shared read and exclusive write access
- Notify clients when the last reader releases access
- Allow optional initial data copied during creation
- Add C/C++ interfaces, documentation, and concurrency tests

Author: TheMostDiligent

Radient/CMakeLists.txt

@@ -37,6 +37,7 @@ set(SOURCE
     src/Assets/RadientTextureAssetManager.cpp
     src/Assets/RadientTextureSource.cpp
     src/Assets/RadientVertexLayout.cpp
+    src/Core/RadientDataBlob.cpp
     src/Core/RadientBackendImpl.cpp
     src/Core/RadientEngineImpl.cpp
     src/Core/RadientViewImpl.cpp
@@ -145,6 +146,7 @@ set(INCLUDE
 
 set(INTERFACE
     interface/Radient.h
+    interface/RadientDataBlob.h
     interface/RadientAnimation.h
     interface/RadientAssetResolver.h
     interface/RadientAssets.h

Radient/docs/DataBlobs.md

@@ -0,0 +1,85 @@
+# Data blobs
+
+`IRadientDataBlob` owns a fixed-size allocation of CPU bytes. It is
+reference-counted and can be created without an engine or graphics device.
+Its public methods expose Radient types and status codes.
+
+Set `RadientDataBlobCreateInfo::pInitialData` to initialize the blob from `Size`
+readable bytes. Creation copies those bytes before returning, so the caller can
+immediately modify or release the source memory. A null pointer selects zero
+initialization; when `Size` is zero, the pointer is ignored. Initialization
+does not acquire access or invoke the recycling callback.
+
+```cpp
+const float Position[] = {1.f, 2.f, 3.f};
+RadientDataBlobCreateInfo CI;
+CI.Size = sizeof(Position);
+CI.pInitialData = Position;
+RefCntAutoPtr<IRadientDataBlob> Blob;
+if (CreateRadientDataBlob(CI, &Blob) != RADIENT_STATUS_OK)
+    return;
+```
+
+## Access
+
+`BeginRead` permits multiple simultaneous readers. `BeginWrite` permits a
+single writer when there are no readers or other writers. Conflicting attempts
+return `RADIENT_STATUS_INVALID_OPERATION` without waiting for active access to
+finish. A successful acquisition is paired with exactly one corresponding
+`EndRead` or `EndWrite`. Null output parameters return
+`RADIENT_STATUS_INVALID_ARGUMENT`; other acquisition failures clear the output
+pointer and leave access state unchanged.
+
+Pointers are used only within their access scope. Clients hold a strong blob
+reference until that scope ends; acquiring access does not retain the object.
+Access can be handed between threads with caller-provided synchronization.
+Writes completed before `EndWrite` are visible to subsequent successful access.
+The allocation never moves or resizes. Empty blobs are valid and return null
+pointers even on successful acquisition, so callers check the status.
+
+```cpp
+RadientDataBlobCreateInfo CI;
+CI.Size = sizeof(float) * 3;
+RefCntAutoPtr<IRadientDataBlob> Blob;
+if (CreateRadientDataBlob(CI, &Blob) != RADIENT_STATUS_OK)
+    return;
+
+void* WriteData = nullptr;
+if (Blob->BeginWrite(&WriteData) == RADIENT_STATUS_OK)
+{
+    const float Position[] = {1.f, 2.f, 3.f};
+    std::memcpy(WriteData, Position, sizeof(Position));
+    Blob->EndWrite();
+}
+
+const void* ReadData = nullptr;
+if (Blob->BeginRead(&ReadData) == RADIENT_STATUS_OK)
+{
+    // Consume ReadData while retaining Blob.
+    Blob->EndRead();
+}
+```
+
+## Recycling notification
+
+Set `RadientDataBlobCreateInfo::OnLastReaderReleased` and `pUserData` to register
+a callback. Registration is copied at creation and remains fixed. The callback
+runs once for each reader-count transition from one to zero, including for
+empty blobs. Construction, writes, failed operations, and destruction do not
+trigger it. The context is not owned by the blob and stays valid for its lifetime.
+
+The callback runs synchronously on the thread performing the final `EndRead`,
+outside the internal access lock. The blob stays alive throughout the callback,
+even if the callback releases the caller's reference. A pool keeping the blob
+afterward acquires a separate strong reference. Clients can queue notifications
+onto their own thread and retain the blob while queued.
+
+Notification does not reserve access. Another reader or writer may already be
+active, so recycling still starts with a successful `BeginWrite`. Callbacks can
+call blob methods. New read cycles can produce nested callbacks or concurrent
+callbacks on different threads; callback state accounts for both. A callback
+exception is caught and makes `EndRead` return `RADIENT_STATUS_FAILED`, with
+the read access already released.
+
+C callers use `Diligent_CreateRadientDataBlob` with a pointer to the creation
+descriptor and the `IRadientDataBlob_*` access macros.

Radient/interface/Radient.h

@@ -31,6 +31,7 @@
 
 #include "RadientMath.h"
 #include "RadientTypes.h"
+#include "RadientDataBlob.h"
 #include "RadientVertexLayout.h"
 #include "RadientAssets.h"
 #include "RadientMorphTargets.h"

Radient/interface/RadientDataBlob.h

@@ -0,0 +1,190 @@
+/*
+ *  Copyright 2026 Diligent Graphics LLC
+ *
+ *  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.
+ *
+ *  In no event and under no legal theory, whether in tort (including negligence),
+ *  contract, or otherwise, unless required by applicable law (such as deliberate
+ *  and grossly negligent acts) or agreed to in writing, shall any Contributor be
+ *  liable for any damages, including any direct, indirect, special, incidental,
+ *  or consequential damages of any character arising as a result of this License or
+ *  out of the use or inability to use the software (including but not limited to damages
+ *  for loss of goodwill, work stoppage, computer failure or malfunction, or any and
+ *  all other commercial damages or losses), even if such Contributor has been advised
+ *  of the possibility of such damages.
+ */
+
+#pragma once
+
+/// \file
+/// Defines reference-counted CPU data storage with shared read and exclusive write access.
+
+#include "RadientTypes.h"
+#include "../../../DiligentCore/Primitives/interface/Object.h"
+
+DILIGENT_BEGIN_NAMESPACE(Diligent)
+
+typedef struct IRadientDataBlob IRadientDataBlob;
+
+/// Notification that a blob's reader count has changed from one to zero.
+///
+/// \param [in] pBlob     - Blob whose final reader released access. The blob stays
+///                        alive throughout the callback. Retaining it after the
+///                        callback requires acquiring a separate strong reference.
+/// \param [in] pUserData - The value supplied in RadientDataBlobCreateInfo::pUserData.
+///
+/// Called synchronously by EndRead on the thread releasing the final reader,
+/// outside the internal access lock. The callback can call blob methods and
+/// acquire its own read or write access. This notification does not reserve
+/// write access: another thread may already have acquired access when it runs.
+/// New read cycles can cause callbacks to overlap across threads or nest on the
+/// same thread, so callback code and its user data account for this concurrency.
+/// If a C++ callback throws, EndRead catches the exception and returns
+/// RADIENT_STATUS_FAILED; the read access has already been released.
+typedef void (*RadientDataBlobReadReleaseCallbackType)(IRadientDataBlob* pBlob, void* pUserData);
+
+/// Creation parameters for a fixed-size CPU data blob.
+/// The size, callback, and user-data pointer are copied during creation.
+/// Optional initial bytes are copied before CreateRadientDataBlob returns.
+struct RadientDataBlobCreateInfo
+{
+    /// Storage size in bytes. The allocation keeps this size for the blob's
+    /// lifetime. Initial contents come from pInitialData when provided, otherwise
+    /// the allocation is zero-filled. Zero creates a valid empty blob, whose
+    /// successful BeginRead and BeginWrite calls return null data pointers.
+    /// Sizes beyond the implementation's addressable allocation range are
+    /// rejected with RADIENT_STATUS_INVALID_ARGUMENT. The default is zero.
+    Uint64 Size DEFAULT_INITIALIZER(0);
+
+    /// Optional pointer to at least Size readable bytes used to initialize the
+    /// allocation. CreateRadientDataBlob copies these bytes before returning;
+    /// the pointer is not retained, and the caller can then modify or release
+    /// the source memory. Initialization does not acquire an access scope or
+    /// invoke OnLastReaderReleased. Ignored when Size is zero. The default is
+    /// nullptr, which initializes the allocation to zero.
+    const void* pInitialData DEFAULT_INITIALIZER(nullptr);
+
+    /// Optional callback invoked once for each reader-count transition from one
+    /// to zero. Creation, EndWrite, failed access attempts, and destruction do
+    /// not invoke it. Registration remains fixed for the blob's lifetime.
+    /// The default is nullptr, which disables notifications.
+    RadientDataBlobReadReleaseCallbackType OnLastReaderReleased DEFAULT_INITIALIZER(nullptr);
+
+    /// Opaque callback context, passed unchanged to OnLastReaderReleased.
+    /// The blob stores the pointer without copying or owning the pointed-to data.
+    /// When a callback is registered, this context remains valid throughout the
+    /// blob's lifetime, including callback execution. May be null; defaults to
+    /// nullptr. Ignored when OnLastReaderReleased is null.
+    void* pUserData DEFAULT_INITIALIZER(nullptr);
+};
+typedef struct RadientDataBlobCreateInfo RadientDataBlobCreateInfo;
+
+// {8A49B839-9F71-45AF-B8C0-058E75274F7B}
+static DILIGENT_CONSTEXPR INTERFACE_ID IID_RadientDataBlob =
+    {0x8a49b839, 0x9f71, 0x45af, {0xb8, 0xc0, 0x05, 0x8e, 0x75, 0x27, 0x4f, 0x7b}};
+
+#define DILIGENT_INTERFACE_NAME IRadientDataBlob
+#include "../../../DiligentCore/Primitives/interface/DefineInterfaceHelperMacros.h"
+
+#define IRadientDataBlobInclusiveMethods \
+    IObjectInclusiveMethods;             \
+    IRadientDataBlobMethods RadientDataBlob
+
+// clang-format off
+
+/// Reference-counted CPU bytes with concurrent readers or one exclusive writer.
+///
+/// All methods are thread-safe. Access acquisition returns an error on conflict
+/// without waiting for active readers or a writer to finish. Successful Begin
+/// calls are paired with exactly one corresponding End call. Access scopes are
+/// not tied to a thread; a caller can hand a scope to another thread using its
+/// own synchronization. Ending another caller's scope is invalid usage.
+///
+/// Data pointers are usable only within their corresponding access scope. A
+/// caller retains a strong object reference until it finishes accessing the
+/// bytes and ends the scope; BeginRead and BeginWrite do not retain the blob.
+/// Read access does not permit modifying the bytes. Writes completed before
+/// EndWrite are visible to subsequent successful BeginRead and BeginWrite calls.
+/// Access methods synchronize scopes; they do not make stale pointer use safe.
+DILIGENT_BEGIN_INTERFACE(IRadientDataBlob, IObject)
+{
+    /// Returns the immutable allocation size in bytes, including during active
+    /// read or write access. Does not acquire access or invoke the callback.
+    VIRTUAL Uint64 METHOD(GetSize)(THIS) CONST PURE;
+
+    /// Acquires one shared read scope and returns the first byte through ppData.
+    /// Additional readers are allowed. Returns RADIENT_STATUS_INVALID_OPERATION
+    /// while a writer is active or if the reader counter cannot be incremented.
+    /// A null ppData returns RADIENT_STATUS_INVALID_ARGUMENT. On any failure,
+    /// a non-null ppData is set to nullptr and access state is unchanged.
+    /// Returns RADIENT_STATUS_OK on success, including for an empty blob.
+    VIRTUAL RADIENT_STATUS METHOD(BeginRead)(THIS_
+                                             const void** ppData) PURE;
+
+    /// Releases one read scope after the caller has finished reading its bytes.
+    /// Returns RADIENT_STATUS_INVALID_OPERATION without changing state when
+    /// there are no readers. Otherwise returns RADIENT_STATUS_OK, invoking
+    /// OnLastReaderReleased if this releases the final reader. The callback
+    /// completes before EndRead returns. A callback exception produces
+    /// RADIENT_STATUS_FAILED with the read scope already released.
+    VIRTUAL RADIENT_STATUS METHOD(EndRead)(THIS) PURE;
+
+    /// Acquires exclusive write access and returns the first byte through ppData.
+    /// Returns RADIENT_STATUS_INVALID_OPERATION while any reader or writer is
+    /// active, including a second BeginWrite from the current writer. A null
+    /// ppData returns RADIENT_STATUS_INVALID_ARGUMENT. On any failure, a non-null
+    /// ppData is set to nullptr and access state is unchanged. Returns
+    /// RADIENT_STATUS_OK on success, including for an empty blob.
+    VIRTUAL RADIENT_STATUS METHOD(BeginWrite)(THIS_
+                                              void** ppData) PURE;
+
+    /// Releases exclusive access after the caller has finished writing its bytes.
+    /// Returns RADIENT_STATUS_OK when a writer was active, making those writes
+    /// visible to subsequent access scopes. Otherwise returns
+    /// RADIENT_STATUS_INVALID_OPERATION without changing state. Does not invoke
+    /// OnLastReaderReleased.
+    VIRTUAL RADIENT_STATUS METHOD(EndWrite)(THIS) PURE;
+};
+DILIGENT_END_INTERFACE
+
+#include "../../../DiligentCore/Primitives/interface/UndefInterfaceHelperMacros.h"
+
+#if DILIGENT_C_INTERFACE
+#    define IRadientDataBlob_GetSize(This)          CALL_IFACE_METHOD(RadientDataBlob, GetSize,    This)
+#    define IRadientDataBlob_BeginRead(This, ...)   CALL_IFACE_METHOD(RadientDataBlob, BeginRead,  This, __VA_ARGS__)
+#    define IRadientDataBlob_EndRead(This)          CALL_IFACE_METHOD(RadientDataBlob, EndRead,    This)
+#    define IRadientDataBlob_BeginWrite(This, ...)  CALL_IFACE_METHOD(RadientDataBlob, BeginWrite, This, __VA_ARGS__)
+#    define IRadientDataBlob_EndWrite(This)         CALL_IFACE_METHOD(RadientDataBlob, EndWrite,   This)
+#endif
+
+// clang-format on
+
+#include "../../../DiligentCore/Primitives/interface/DefineGlobalFuncHelperMacros.h"
+
+/// Creates a CPU data blob without requiring a Radient engine or graphics device.
+///
+/// \param [in]  CreateInfo - Size, optional initial data, and last-reader notification.
+/// \param [out] ppBlob     - Receives an owning reference on success. Must be
+///                          non-null and point to a null interface pointer.
+///
+/// Returns RADIENT_STATUS_OK on success, RADIENT_STATUS_INVALID_ARGUMENT for a
+/// null output pointer or an unsupported allocation size, or RADIENT_STATUS_FAILED
+/// if allocation fails. On failure, a non-null ppBlob is set to nullptr.
+/// C callers use Diligent_CreateRadientDataBlob and pass a CreateInfo pointer;
+/// a null CreateInfo pointer returns RADIENT_STATUS_INVALID_ARGUMENT.
+RADIENT_STATUS DILIGENT_GLOBAL_FUNCTION(CreateRadientDataBlob)(const RadientDataBlobCreateInfo REF CreateInfo,
+                                                               IRadientDataBlob**                  ppBlob);
+
+#include "../../../DiligentCore/Primitives/interface/UndefGlobalFuncHelperMacros.h"
+
+DILIGENT_END_NAMESPACE // namespace Diligent