Add Coarse provider

Add Coarse provider - a memory provider that should be used
as a "cache" for pre-allocated buffer or with an additional
upstream provider (e.g. OS Memory Provider).

Developed-by: Rafał Rudnicki <[email protected]>
Co-developed-by: Lukasz Dorau <[email protected]>

Signed-off-by: Lukasz Dorau <[email protected]>

Author: ldorau

include/umf/providers/provider_coarse.h

@@ -0,0 +1,76 @@
+/*
+ * Copyright (C) 2023-2024 Intel Corporation
+ *
+ * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+*/
+
+#ifndef UMF_COARSE_PROVIDER_H
+#define UMF_COARSE_PROVIDER_H
+
+#include <stdbool.h>
+#include <umf/memory_provider.h>
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+/// @brief Coarse Memory Provider settings struct.
+typedef struct coarse_memory_provider_params_t {
+    /// Handle to the upstream memory provider, could be NULL.
+    umf_memory_provider_handle_t upstream_memory_provider;
+
+    /// When set, the init buffer would be pre-allocated (with
+    /// `init_buffer_size` bytes) during creation time. The memory used to
+    /// pre-allocate it would be taken either from the `init_buffer` or from
+    /// the `upstream_memory_provider`, so either one of them has to be set.
+    bool immediate_init;
+
+    /// Init buffer used to pre-allocate memory at the creation time, could be
+    /// NULL.
+    void *init_buffer;
+
+    /// Size of the pre-allocated buffer. If the `init_buffer` is set, the
+    /// `init_buffer_size` should be the size of this buffer.
+    size_t init_buffer_size;
+
+    /// Enable extra tracing (TODO - move to CTL)
+    bool trace;
+
+    /// If this flag is set, the Coarse Provider wouldn't ask the upstream
+    /// memory provider to free the memory during destruction.
+    bool WA_do_not_free_upstream;
+} coarse_memory_provider_params_t;
+
+/// @brief Coarse Memory Provider stats (TODO move to CTL)
+typedef struct coarse_memory_provider_stats_t {
+    /// Total allocation size.
+    size_t alloc_size;
+
+    /// Size of used memory.
+    size_t used_size;
+
+    /// Number of memory blocks allocated from the upstream provider.
+    size_t upstream_blocks_num;
+
+    /// Total number of allocated memory blocks.
+    size_t blocks_num;
+
+    /// Number of free memory blocks.
+    size_t free_blocks_num;
+} coarse_memory_provider_stats_t;
+
+umf_memory_provider_ops_t *umfCoarseMemoryProviderOps(void);
+
+// TODO use CTL
+coarse_memory_provider_stats_t
+umfCoarseMemoryProviderGetStats(umf_memory_provider_handle_t provider);
+
+umf_memory_provider_handle_t umfCoarseMemoryProviderGetUpstreamProvider(
+    umf_memory_provider_handle_t provider);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // UMF_coarse_PROVIDER_H

scripts/docs_config/api.rst

@@ -80,6 +80,15 @@ and operate on the provider.
 .. doxygenfile:: memory_provider.h
     :sections: define enum typedef func var
 
+Coarse Provider
+------------------------------------------
+
+A memory provider that should be used as a "cache" for pre-allocated buffer
+or with additional upstream provider (e.g. OS Memory Provider).
+
+.. doxygenfile:: provider_coarse.h
+    :sections: define enum typedef func var
+
 OS Memory Provider
 ------------------------------------------
 

src/CMakeLists.txt

@@ -82,6 +82,7 @@ set(UMF_SOURCES
     memtarget.c
     mempolicy.c
     memspace.c
+    provider/provider_coarse.c
     provider/provider_tracking.c
     critnib/critnib.c
     ravl/ravl.c
@@ -230,6 +231,7 @@ target_include_directories(
     umf
     PUBLIC $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
+           $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/ravl>
            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/critnib>
            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/provider>
            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/memspaces>

src/libumf.def.in

@@ -14,6 +14,9 @@ EXPORTS
     umfTearDown
     umfGetCurrentVersion
     umfCloseIPCHandle
+    umfCoarseMemoryProviderGetStats
+    umfCoarseMemoryProviderGetUpstreamProvider
+    umfCoarseMemoryProviderOps
     umfFree
     umfGetIPCHandle
     umfGetLastFailedMemoryProvider

src/libumf.map.in

@@ -8,6 +8,9 @@ UMF_1.0 {
         umfTearDown;
         umfGetCurrentVersion;
         umfCloseIPCHandle;
+        umfCoarseMemoryProviderGetStats;
+        umfCoarseMemoryProviderGetUpstreamProvider;
+        umfCoarseMemoryProviderOps;
         umfFree;
         umfGetIPCHandle;
         umfGetLastFailedMemoryProvider;