From 8addf46763eb3b5b4e3eb58b4dda19f2e76bcaa0 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Wed, 17 Dec 2025 09:38:24 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`pr1212`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @YiXR. * https://github.com/XucSh/Mooncake/pull/4#issuecomment-3664502889 The following files were modified: * `mooncake-store/include/tiered_cache/cache_tier.h` * `mooncake-store/include/tiered_cache/copier_registry.h` * `mooncake-store/include/tiered_cache/data_copier.h` * `mooncake-store/include/tiered_cache/tiered_backend.h` * `mooncake-store/src/tiered_cache/copier_registry.cpp` * `mooncake-store/src/tiered_cache/data_copier.cpp` * `mooncake-store/src/tiered_cache/tiered_backend.cpp` --- .../include/tiered_cache/cache_tier.h | 69 +++++++- .../include/tiered_cache/copier_registry.h | 76 ++++++++- .../include/tiered_cache/data_copier.h | 56 +++++++ .../include/tiered_cache/tiered_backend.h | 148 ++++++++++++++++++ .../src/tiered_cache/copier_registry.cpp | 45 ++++++ .../src/tiered_cache/data_copier.cpp | 61 +++++++- .../src/tiered_cache/tiered_backend.cpp | 135 ++++++++++++++++ 7 files changed, 584 insertions(+), 6 deletions(-) diff --git a/mooncake-store/include/tiered_cache/cache_tier.h b/mooncake-store/include/tiered_cache/cache_tier.h index d0bbd0da5..b2b764a40 100644 --- a/mooncake-store/include/tiered_cache/cache_tier.h +++ b/mooncake-store/include/tiered_cache/cache_tier.h @@ -7,6 +7,73 @@ #include "transfer_engine.h" +/** + * @enum MemoryType + * @brief Physical storage medium type used by a cache tier. + */ + +/** + * @brief Convert a MemoryType value to its string representation. + * @param type The MemoryType value to convert. + * @returns The string name of `type` ("DRAM", "NVME", or "UNKNOWN"). + */ + +/** + * @struct DataSource + * @brief Describes a source or reservation for data transfer operations. + * + * Fields: + * - `ptr`: pointer value (in-memory address) or file descriptor identifying the source. + * - `offset`: byte offset within the source (for files/SSD ranges). + * - `size`: size in bytes. + * - `type`: physical memory type of the source. + */ + +/** + * @class CacheTier + * @brief Abstract interface representing a single cache tier (for example DRAM or NVMe). + */ + +/** + * @brief Initialize the cache tier with its parent backend and transfer engine. + * @returns `true` if initialization succeeds, `false` otherwise. + */ + +/** + * @brief Reserve free space of the given size without performing any data copy. + * @param data Output parameter that will be populated with allocation details (ptr/offset/size/type). + * @returns `true` if the allocation succeeds, `false` otherwise. + */ + +/** + * @brief Release or roll back a previously allocated reservation described by `data`. + * @returns `true` if the free/rollback succeeds, `false` otherwise. + */ + +/** + * @brief Retrieve the identifier for this tier. + * @returns The tier identifier. + */ + +/** + * @brief Retrieve the total capacity of the tier in bytes. + * @returns The tier capacity in bytes. + */ + +/** + * @brief Retrieve the current used bytes within the tier. + * @returns The tier usage in bytes. + */ + +/** + * @brief Retrieve the MemoryType of this tier. + * @returns The tier's MemoryType. + */ + +/** + * @brief Retrieve metadata tags associated with this tier. + * @returns A reference to the vector of tag strings. + */ namespace mooncake { struct DataSource; @@ -85,4 +152,4 @@ class CacheTier { TieredBackend* backend_ = nullptr; }; -} // namespace mooncake +} // namespace mooncake \ No newline at end of file diff --git a/mooncake-store/include/tiered_cache/copier_registry.h b/mooncake-store/include/tiered_cache/copier_registry.h index 80c518ae7..e5f7148bc 100644 --- a/mooncake-store/include/tiered_cache/copier_registry.h +++ b/mooncake-store/include/tiered_cache/copier_registry.h @@ -27,10 +27,59 @@ struct DirectPathRegistration { }; /** - * @brief A singleton registry for data copier functions. + * Singleton registry that collects data copier functions for different memory + * types and optional optimized direct copy paths. * - * Modules can register their copy functions here during static initialization. - * The DataCopierBuilder will then use this registry to construct a DataCopier. + * Modules register copy functions (typically via static initialization) + * and DataCopierBuilder queries this registry to assemble a DataCopier. + */ + +/** + * Access the global CopierRegistry instance. + * + * @returns Reference to the global CopierRegistry instance. + */ + +/** + * Register the to-DRAM and from-DRAM copy functions for a memory type. + * + * @param type Memory type being registered. + * @param to_dram Copy function that copies data from `type` to DRAM. + * @param from_dram Copy function that copies data from DRAM to `type`. + */ + +/** + * Register an optimized direct copy function for copying between two memory + * types. + * + * @param src Source memory type. + * @param dest Destination memory type. + * @param func Copy function that copies from `src` to `dest`. + */ + +/** + * Retrieve all registered memory type entries. + * + * @returns Reference to the vector of MemoryTypeRegistration entries. + */ + +/** + * Retrieve all registered direct path entries. + * + * @returns Reference to the vector of DirectPathRegistration entries. + */ + +/** + * Helper that registers a memory type's to/from DRAM copy functions during + * static initialization when instantiated as a static object. + */ + +/** + * Construct a CopierRegistrar and register the provided copy functions. + * + * @param type Memory type to register. + * @param to_dram Copy function that copies data from `type` to DRAM. + * @param from_dram Copy function that copies data from DRAM to `type`. */ class CopierRegistry { public: @@ -51,7 +100,26 @@ class CopierRegistry { void RegisterDirectPath(MemoryType src, MemoryType dest, CopyFunction func); // These methods are used by the DataCopierBuilder to collect all - // registrations. + /** + * Retrieve registered memory-type copy registrations. + * + * @returns A reference to the vector of MemoryTypeRegistration entries stored + * in the registry. + */ +/** + * Retrieve registered direct-copy path registrations. + * + * @returns A reference to the vector of DirectPathRegistration entries stored + * in the registry. + */ +/** + * Register a memory type's to/from DRAM copy functions at static + * initialization time. + * + * @param type The MemoryType being registered. + * @param to_dram Copy function used to transfer data from the memory type to DRAM. + * @param from_dram Copy function used to transfer data from DRAM to the memory type. + */ const std::vector& GetMemoryTypeRegistrations() const; const std::vector& GetDirectPathRegistrations() diff --git a/mooncake-store/include/tiered_cache/data_copier.h b/mooncake-store/include/tiered_cache/data_copier.h index cd843ec09..caf1797d6 100644 --- a/mooncake-store/include/tiered_cache/data_copier.h +++ b/mooncake-store/include/tiered_cache/data_copier.h @@ -8,6 +8,62 @@ #include #include +/** + * @brief Builder that constructs a validated DataCopier instance. + * + * Ensures that all MemoryType entries have required copy paths registered + * (copies to and from DRAM) before producing an immutable DataCopier. + */ + +/** + * @brief Constructs a builder initialized from the global CopierRegistry. + * + * Copies all current registrations from the global registry into the + * builder's internal copy matrix. + */ + +/** + * @brief Registers an explicit direct copy path between two memory types. + * + * The provided function will be preferred over a DRAM fallback for the + * given src_type -> dest_type pair. Can be used to add optimized or + * non-registered paths (e.g., for testing). + * @return Reference to this builder for chaining. + */ + +/** + * @brief Builds and returns a validated, immutable DataCopier. + * + * Verifies that required copy paths exist for every MemoryType before + * constructing the DataCopier. + * @return A unique_ptr to the constructed DataCopier. + * @throws std::logic_error If a required to/from DRAM copy function is missing. + */ + +/** + * @brief Utility that copies data between memory types, with DRAM fallback. + * + * Performs copies using registered direct paths when available; otherwise + * falls back to a two-step copy via a temporary DRAM buffer. + */ + +/** + * @brief Copies data from src to dst. + * + * Attempts a direct copy for src.memory_type -> dst.memory_type; if no direct + * copier is registered, performs a two-step copy via DRAM. + * @param src Data source descriptor. + * @param dst Data destination descriptor. + * @return `true` if the copy succeeds, `false` otherwise. + */ + +/** + * @brief Locates a registered copy function for the specified memory types. + * + * @param src_type Source memory type. + * @param dest_type Destination memory type. + * @return The registered CopyFunction if found, or an empty std::function otherwise. + */ namespace mooncake { using CopyFunction = diff --git a/mooncake-store/include/tiered_cache/tiered_backend.h b/mooncake-store/include/tiered_cache/tiered_backend.h index a43a1f20c..41a265fac 100644 --- a/mooncake-store/include/tiered_cache/tiered_backend.h +++ b/mooncake-store/include/tiered_cache/tiered_backend.h @@ -12,6 +12,154 @@ #include "tiered_cache/cache_tier.h" #include "tiered_cache/data_copier.h" +/** + * @struct TieredLocation + * @brief Identifies the physical storage location of a segment within a tier. + * + * Contains the tier identifier and the data source descriptor for that location. + */ + +/** + * @struct TierView + * @brief Snapshot of a tier's current status for topology reporting. + * + * Includes tier id, memory type, capacity, usage, free space, priority, and + * associated metadata tags. + */ + +/** + * @struct AllocationEntry + * @brief Control block that represents an active allocation. + * + * When the last reference to this entry is destroyed, the destructor invokes + * the backend to release the associated physical resource. + */ + +/** + * @typedef AllocationHandle + * @brief Reference-counted handle to an AllocationEntry. + */ + +/** + * @brief Callback invoked after a data copy to synchronize metadata. + * + * @param key The metadata key associated with the copied data. + * @param new_loc The new tiered location created by the copy. + * @return `true` if metadata synchronization succeeded, `false` otherwise. + */ + +/** + * @class TieredBackend + * @brief Manages storage placement, access, and lifecycle across multiple tiers. + * + * Provides allocation, write, commit, retrieval, deletion, and cross-tier copy + * operations, while exposing tier introspection and an internal release hook + * used by allocation control blocks. + */ + +/** + * @brief Initialize the backend with configuration and a transfer engine. + * + * @param root JSON configuration root. + * @param engine Transfer engine used for cross-tier data movement. + * @return `true` on successful initialization, `false` otherwise. + */ + +/** + * @brief Reserve storage space and return a handle representing the allocation. + * + * If the returned handle is destroyed without being committed, the reserved + * space is automatically freed. + * + * @param size Number of bytes to allocate. + * @param preferred_tier Optional preferred tier id for placement. + * @return An AllocationHandle that represents the reserved location, or an + * empty handle on failure. + */ + +/** + * @brief Write data from the provided source into the allocated location. + * + * @param source Descriptor of the data to write. + * @param handle Handle that identifies the target allocation. + * @return `true` if the write completes successfully, `false` otherwise. + */ + +/** + * @brief Register an allocation under a metadata key to make it discoverable. + * + * If a replica for the same key already exists on the same tier, it is + * replaced. Multiple replicas across different tiers are supported. + * + * @param key Metadata key to register (e.g., segment id). + * @param handle AllocationHandle representing the data to register. + * @return `true` on successful registration, `false` otherwise. + */ + +/** + * @brief Retrieve an allocation handle for a metadata key. + * + * When `tier_id` is specified, returns the replica on that tier if present. + * When `tier_id` is not specified, returns a replica from the highest-priority + * available tier. + * + * @param key Metadata key to look up. + * @param tier_id Optional tier id to prefer. + * @return AllocationHandle for the located replica, or an empty handle if not found. + */ + +/** + * @brief Remove replicas for a metadata key from the local index. + * + * When `tier_id` is specified, removes only the replica on that tier. When not + * specified, removes all replicas and the key's entry. + * + * @param key Metadata key to remove. + * @param tier_id Optional tier id specifying which replica to remove. + * @return `true` on successful deletion (or if the specified replica did not exist), + * `false` on failure. + */ + +/** + * @brief Create a new replica of a key's data on a destination tier. + * + * Adds a new replica on `dest_tier_id`; it does not remove the original + * replica. After the data copy completes, the provided sync callback is + * invoked to update metadata accordingly. + * + * @param key Metadata key for the data being copied. + * @param source Descriptor of the data source to copy from. + * @param dest_tier_id Destination tier id where the copy will be placed. + * @param sync_cb Callback invoked after the copy to synchronize metadata. + * @return `true` if the copy and subsequent synchronization succeeded, `false` otherwise. + */ + +/** + * @brief Return a snapshot list of current tier views. + * + * @return A vector of TierView describing each configured tier's state. + */ + +/** + * @brief Retrieve a pointer to the CacheTier instance for a given tier id. + * + * @param tier_id Identifier of the tier to retrieve. + * @return Pointer to the CacheTier, or `nullptr` if the tier id is unknown. + */ + +/** + * @brief Access the DataCopier component used for cross-tier transfers. + * + * @return Reference to the backend's DataCopier instance. + */ + +/** + * @brief Internal API used by AllocationEntry destructor to release a location. + * + * Releases the physical resources associated with `loc`. + * + * @param loc The tiered location to free. + */ namespace mooncake { class TieredBackend; // Forward declaration diff --git a/mooncake-store/src/tiered_cache/copier_registry.cpp b/mooncake-store/src/tiered_cache/copier_registry.cpp index d6554bdfd..bcbe3c2c7 100644 --- a/mooncake-store/src/tiered_cache/copier_registry.cpp +++ b/mooncake-store/src/tiered_cache/copier_registry.cpp @@ -4,32 +4,77 @@ namespace mooncake { +/** + * @brief Provides access to the global CopierRegistry singleton. + * + * @return CopierRegistry& Reference to the shared CopierRegistry instance. + */ CopierRegistry& CopierRegistry::GetInstance() { static CopierRegistry instance; return instance; } +/** + * @brief Registers a memory type and its associated copy callbacks with the registry. + * + * Adds an entry for `type` that associates a copy-to-DRAM callback and a copy-from-DRAM callback + * so callers can look up copy functions for that memory type. + * + * @param type The memory type being registered. + * @param to_dram Callback invoked to copy data from this memory type to DRAM. + * @param from_dram Callback invoked to copy data from DRAM to this memory type. + */ void CopierRegistry::RegisterMemoryType(MemoryType type, CopyFunction to_dram, CopyFunction from_dram) { memory_type_regs_.push_back( {type, std::move(to_dram), std::move(from_dram)}); } +/** + * @brief Registers a direct copy path between two memory types. + * + * Adds a direct-path registration so copies can be performed directly from `src` + * to `dest` using the provided callback. + * + * @param src Source memory type for the direct copy path. + * @param dest Destination memory type for the direct copy path. + * @param func Copy callback used to perform the direct copy; ownership of `func` + * is transferred (moved) into the registry. + */ void CopierRegistry::RegisterDirectPath(MemoryType src, MemoryType dest, CopyFunction func) { direct_path_regs_.push_back({src, dest, std::move(func)}); } +/** + * @brief Get all registered memory type transfer registrations. + * + * @return const std::vector& A const reference to the vector of `MemoryTypeRegistration` entries that have been registered. + */ const std::vector& CopierRegistry::GetMemoryTypeRegistrations() const { return memory_type_regs_; } +/** + * @brief Provides access to the registered direct copy paths between memory types. + * + * @return const std::vector& The collection of DirectPathRegistration entries representing direct copy callbacks for specific source→destination memory type pairs. + */ const std::vector& CopierRegistry::GetDirectPathRegistrations() const { return direct_path_regs_; } +/** + * @brief Registers a memory type and its to/from-DRAM copy callbacks with the global CopierRegistry. + * + * Constructing this registrar performs registration (suitable for static initialization). + * + * @param type The memory type being registered. + * @param to_dram Callback used to copy data from the memory type to DRAM. + * @param from_dram Callback used to copy data from DRAM to the memory type. + */ CopierRegistrar::CopierRegistrar(MemoryType type, CopyFunction to_dram, CopyFunction from_dram) { // When a static CopierRegistrar object is created, it registers the memory diff --git a/mooncake-store/src/tiered_cache/data_copier.cpp b/mooncake-store/src/tiered_cache/data_copier.cpp index 36fde3f14..ce8abdbd5 100644 --- a/mooncake-store/src/tiered_cache/data_copier.cpp +++ b/mooncake-store/src/tiered_cache/data_copier.cpp @@ -6,6 +6,13 @@ namespace mooncake { +/** + * @brief Initializes the builder's copy matrix from the global CopierRegistry. + * + * Populates the internal copy_matrix_ by registering, for each memory-type registration, + * the type->DRAM and DRAM->type copy functions, and by registering each direct-path + * (src_type -> dest_type) copy function from the registry. + */ DataCopierBuilder::DataCopierBuilder() { // Process all registrations from the global registry. const auto& registry = CopierRegistry::GetInstance(); @@ -19,6 +26,17 @@ DataCopierBuilder::DataCopierBuilder() { } } +/** + * @brief Registers a direct copy function for a specific source→destination memory-type pair. + * + * Associates `func` with the (src_type, dest_type) pair so that direct copies between those + * memory types will use the provided function. + * + * @param src_type Source memory type. + * @param dest_type Destination memory type. + * @param func Copy function to invoke for copies from `src_type` to `dest_type`. + * @return DataCopierBuilder& Reference to this DataCopierBuilder. + */ DataCopierBuilder& DataCopierBuilder::AddDirectPath(MemoryType src_type, MemoryType dest_type, CopyFunction func) { @@ -26,6 +44,19 @@ DataCopierBuilder& DataCopierBuilder::AddDirectPath(MemoryType src_type, return *this; } +/** + * @brief Builds a configured DataCopier after validating required copy paths. + * + * Validates that for every registered memory type other than DRAM there exists + * both a copy function from that type to DRAM and from DRAM to that type. + * If validation succeeds, constructs and returns a DataCopier configured with + * the builder's copy matrix. + * + * @return std::unique_ptr Unique pointer owning the configured DataCopier. + * + * @throws std::logic_error If any non-DRAM memory type is missing a required + * copy function to or from DRAM; the exception message identifies the missing pair. + */ std::unique_ptr DataCopierBuilder::Build() const { const auto& registry = CopierRegistry::GetInstance(); for (const auto& reg : registry.GetMemoryTypeRegistrations()) { @@ -50,16 +81,44 @@ std::unique_ptr DataCopierBuilder::Build() const { return std::unique_ptr(new DataCopier(copy_matrix_)); } -DataCopier::DataCopier( +/** + * @brief Constructs a DataCopier with a predefined copy-function matrix. + * + * Initializes the DataCopier by taking ownership of a map that associates + * (source memory type, destination memory type) pairs to their corresponding + * copy functions. + * + * @param copy_matrix Map from (MemoryType, MemoryType) pairs to CopyFunction; + * ownership of the map is transferred to the DataCopier. + */ + DataCopier::DataCopier( std::map, CopyFunction> copy_matrix) : copy_matrix_(std::move(copy_matrix)) {} +/** + * @brief Locate the registered copy function for a source-destination memory-type pair. + * + * @param src_type Source memory type. + * @param dest_type Destination memory type. + * @return CopyFunction The registered copy function for (src_type, dest_type) if one exists, `nullptr` otherwise. + */ CopyFunction DataCopier::FindCopier(MemoryType src_type, MemoryType dest_type) const { auto it = copy_matrix_.find({src_type, dest_type}); return (it != copy_matrix_.end()) ? it->second : nullptr; } +/** + * @brief Copies data from a source DataSource to a destination DataSource using registered copiers. + * + * Attempts a direct registered copier for (src.type -> dest.type). If no direct copier exists and + * both source and destination are non-DRAM, attempts a two-step fallback via DRAM (src -> DRAM -> dest). + * + * @param src Source DataSource containing pointer, offset, size, and memory type. + * @param dest Destination DataSource containing pointer, offset, size, and memory type. + * @return true if the copy completed successfully; false if allocation fails, a copy step fails, + * or no suitable copy path is registered. + */ bool DataCopier::Copy(const DataSource& src, const DataSource& dest) const { MemoryType dest_type = dest.type; // Try to find a direct copy function. diff --git a/mooncake-store/src/tiered_cache/tiered_backend.cpp b/mooncake-store/src/tiered_cache/tiered_backend.cpp index 9c53dad4d..ec6ffb94e 100644 --- a/mooncake-store/src/tiered_cache/tiered_backend.cpp +++ b/mooncake-store/src/tiered_cache/tiered_backend.cpp @@ -8,6 +8,13 @@ namespace mooncake { +/** + * @brief Destructor that releases the allocation's backing resource. + * + * If this entry has an associated backend, invokes backend->FreeInternal(loc) + * to free the physical resource when the allocation's lifetime ends (reference + * count drops to zero). + */ AllocationEntry::~AllocationEntry() { if (backend) { // When ref count drops to 0, call back to backend to free physical @@ -16,8 +23,26 @@ AllocationEntry::~AllocationEntry() { } } +/** + * @brief Constructs a TieredBackend with default-initialized internal state. + * + * Initializes the backend object with its members set to their default values. + */ TieredBackend::TieredBackend() = default; +/** + * @brief Initializes the backend by constructing the DataCopier and loading tier metadata from JSON. + * + * Parses the provided JSON `root` for a "tiers" array and records per-tier metadata (id, priority, tags). + * Also constructs the internal DataCopier instance. Actual instantiation of CacheTier objects is + * left to the tier creation logic (placeholder in this implementation). + * + * @param root JSON object containing a "tiers" member: each entry must include an `id` and `priority`, + * and may include an optional `tags` array of strings. + * @param engine TransferEngine pointer intended for use when initializing concrete tier instances. + * @return true if initialization completed successfully and tier metadata was loaded; `false` if the + * JSON is missing the required "tiers" member or DataCopier construction failed. + */ bool TieredBackend::Init(Json::Value root, TransferEngine* engine) { // Initialize DataCopier try { @@ -60,6 +85,14 @@ bool TieredBackend::Init(Json::Value root, TransferEngine* engine) { return true; } +/** + * @brief Get tier IDs ordered by priority. + * + * Returns the list of configured tier identifiers sorted by priority with higher-priority + * tiers appearing earlier in the vector. + * + * @return std::vector Vector of tier IDs ordered by descending priority (highest priority first). If two tiers have the same priority, their relative order is unspecified. + */ std::vector TieredBackend::GetSortedTiers() const { std::vector ids; for (const auto& [id, _] : tiers_) ids.push_back(id); @@ -71,6 +104,18 @@ std::vector TieredBackend::GetSortedTiers() const { return ids; } +/** + * Attempts to allocate storage for a buffer of the given size, preferring the optional + * preferred_tier and falling back to other tiers ordered by priority. + * + * If allocation succeeds, populates `out_loc->tier_id` and `out_loc->data` with the + * allocated location for the chosen tier. + * + * @param size Number of bytes to allocate. + * @param preferred_tier Optional tier id to try first. + * @param out_loc Output pointer that will be populated with the chosen tier and data on success. + * @return true if allocation succeeded and `out_loc` was populated, false otherwise. + */ bool TieredBackend::AllocateInternalRaw(size_t size, std::optional preferred_tier, TieredLocation* out_loc) { @@ -101,6 +146,11 @@ bool TieredBackend::AllocateInternalRaw(size_t size, return false; } +/** + * @brief Frees the storage referenced by a TieredLocation from its associated tier if that tier exists. + * + * @param loc Location that specifies the target tier (`tier_id`) and the tier-local allocation (`data`) to free. + */ void TieredBackend::FreeInternal(const TieredLocation& loc) { auto it = tiers_.find(loc.tier_id); if (it != tiers_.end()) { @@ -108,6 +158,18 @@ void TieredBackend::FreeInternal(const TieredLocation& loc) { } } +/** + * @brief Allocates storage from the tiered backend and returns a handle to it. + * + * Attempts to allocate `size` bytes, preferring `preferred_tier` when provided; + * falls back to automatic tier selection if the preferred tier cannot satisfy the request. + * + * @param size Number of bytes to allocate. + * @param preferred_tier Optional id of the tier to prefer for the allocation. + * @return AllocationHandle Shared handle to the allocated location (reference count = 1) on success, `nullptr` on failure. + * + * @note If the returned handle is destroyed without being committed, the underlying allocation is freed. + */ AllocationHandle TieredBackend::Allocate( size_t size, std::optional preferred_tier) { TieredLocation loc; @@ -120,6 +182,13 @@ AllocationHandle TieredBackend::Allocate( return nullptr; } +/** + * @brief Writes the provided data source into the allocation specified by the handle. + * + * @param source Data to write into the allocation. + * @param handle Target allocation handle whose location determines the destination tier; must not be null. + * @return true if the data was successfully copied into the allocation; false if `handle` is null, the target tier is missing, or the copy operation fails. + */ bool TieredBackend::Write(const DataSource& source, AllocationHandle handle) { if (!handle) return false; auto it = tiers_.find(handle->loc.tier_id); @@ -128,6 +197,17 @@ bool TieredBackend::Write(const DataSource& source, AllocationHandle handle) { return data_copier_->Copy(source, handle->loc.data); } +/** + * @brief Store or update a replica for a metadata key using the provided allocation handle. + * + * Associates the given handle's tier with the metadata key: if a replica for the same + * tier exists it is replaced; otherwise a new replica is appended and replicas are + * ordered by tier priority (higher priority first). + * + * @param key Metadata key to commit the replica under. + * @param handle Allocation handle containing the tier and location to commit. If null, no action is taken. + * @return bool `true` if the replica was committed or updated, `false` if `handle` is null. + */ bool TieredBackend::Commit(const std::string& key, AllocationHandle handle) { if (!handle) return false; @@ -183,6 +263,15 @@ bool TieredBackend::Commit(const std::string& key, AllocationHandle handle) { return true; } +/** + * @brief Retrieve the allocation handle for a metadata key, optionally constrained to a specific tier. + * + * Searches the metadata index for the given key and returns the corresponding replica's AllocationHandle. + * + * @param key Metadata key to look up. + * @param tier_id Optional tier identifier to select a replica from that tier. + * @return AllocationHandle The handle for the found replica, or `nullptr` if the key or requested replica is not present. If `tier_id` is provided, returns the replica from that tier or `nullptr` if none exists; if not provided, returns the highest-priority replica for the key or `nullptr` if there are no replicas. + */ AllocationHandle TieredBackend::Get(const std::string& key, std::optional tier_id) { std::shared_ptr entry = nullptr; @@ -215,6 +304,18 @@ AllocationHandle TieredBackend::Get(const std::string& key, return entry->replicas.begin()->second; } +/** + * @brief Remove one or all replicas for a metadata key. + * + * If `tier_id` is provided, removes only the replica stored in that tier. + * If `tier_id` is not provided, removes all replicas and erases the key. + * + * @param key Metadata key whose replica(s) should be removed. + * @param tier_id Optional tier identifier specifying a single replica to delete. + * @return true If a replica was removed (when `tier_id` is provided) or if the key existed and was deleted (when `tier_id` is not provided); `false` if no matching replica/key was found. + * + * @note Resource handles for removed replicas are released after locks are dropped so actual freeing of underlying storage occurs outside of held locks. + */ bool TieredBackend::Delete(const std::string& key, std::optional tier_id) { // Hold references locally to ensure destruction happens OUTSIDE the @@ -312,6 +413,19 @@ bool TieredBackend::Delete(const std::string& key, return true; } +/** + * @brief Copies data into a destination tier and registers it as a replica for a key. + * + * Allocates space in the specified destination tier, writes the provided data into that allocation, + * optionally synchronizes the new location with an external master via the provided callback, + * and on success adds the allocation as a replica for the given key. + * + * @param key Metadata key under which the new replica will be committed. + * @param source Source data and size to copy; `source.size` must be greater than zero. + * @param dest_tier_id Tier identifier where the data should be allocated and written. + * @param sync_cb Optional callback invoked as `sync_cb(key, loc)` to synchronize the new location with a master; if provided, the operation aborts when the callback returns `false`. + * @return true if the data was copied, optionally synchronized, and committed as a replica; `false` on any failure (allocation, write, sync callback failure, or commit). + */ bool TieredBackend::CopyData(const std::string& key, const DataSource& source, uint64_t dest_tier_id, MetadataSyncCallback sync_cb) { @@ -336,6 +450,13 @@ bool TieredBackend::CopyData(const std::string& key, const DataSource& source, return Commit(key, dest_handle); } +/** + * @brief Builds a snapshot of each configured tier's metrics and metadata. + * + * @return std::vector A vector of TierView objects, one per configured tier. + * Each TierView contains the tier id, memory type, total capacity, used bytes, + * available bytes (capacity minus used), priority, and associated tags. + */ std::vector TieredBackend::GetTierViews() const { std::vector views; for (const auto& [id, tier] : tiers_) { @@ -348,11 +469,25 @@ std::vector TieredBackend::GetTierViews() const { return views; } +/** + * Retrieve the cache tier associated with the given tier identifier. + * + * The returned pointer is owned by the TieredBackend and remains valid while + * this backend instance exists and the tier is not removed. + * + * @param tier_id Identifier of the tier to look up. + * @return const CacheTier* Pointer to the CacheTier if found, `nullptr` otherwise. + */ const CacheTier* TieredBackend::GetTier(uint64_t tier_id) const { auto it = tiers_.find(tier_id); return (it != tiers_.end()) ? it->second.get() : nullptr; } +/** + * @brief Gets the configured DataCopier used for data transfers. + * + * @return const DataCopier& Reference to the backend's DataCopier instance. + */ const DataCopier& TieredBackend::GetDataCopier() const { return *data_copier_; } } // namespace mooncake \ No newline at end of file