Add Coarse provider

Add Coarse provider - a memory provider that can manage a memory
(i.e. handle the alloc() and free() ops) of a given pre-allocated
buffer or of an additional upstream provider (e.g. OS Memory Provider
or providers that do not support the free() operation,
like the file memory provider and the DevDax memory provider).

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

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

README.md

@@ -135,6 +135,13 @@ More detailed documentation is available here: https://oneapi-src.github.io/unif
 
 ### Memory providers
 
+#### Coarse Provider
+
+A memory provider that can provide memory from:
+1) a given pre-allocated buffer (the fixed-size memory provider option) or
+2) from an additional upstream provider (e.g. provider that does not support the free() operation
+   like the File memory provider or the DevDax memory provider - see below).
+
 #### OS memory provider
 
 A memory provider that provides memory from an operating system.

include/umf/providers/provider_coarse.h

@@ -0,0 +1,102 @@
+/*
+ * 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>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// @brief Coarse Memory Provider allocation strategy
+typedef enum coarse_memory_provider_strategy_t {
+    /// Always allocate a free block of the (size + alignment) size
+    /// and cut out the properly aligned part leaving two remaining parts.
+    /// It is the fastest strategy but causes memory fragmentation
+    /// when alignment is greater than 0.
+    /// It is the best strategy when alignment always equals 0.
+    UMF_COARSE_MEMORY_STRATEGY_FASTEST = 0,
+
+    /// Check if the first free block of the 'size' size has the correct alignment.
+    /// If not, use the `UMF_COARSE_MEMORY_STRATEGY_FASTEST` strategy.
+    UMF_COARSE_MEMORY_STRATEGY_FASTEST_BUT_ONE,
+
+    /// Look through all free blocks of the 'size' size
+    /// and choose the first one with the correct alignment.
+    /// If none of them had the correct alignment,
+    /// use the `UMF_COARSE_MEMORY_STRATEGY_FASTEST` strategy.
+    UMF_COARSE_MEMORY_STRATEGY_CHECK_ALL_SIZE,
+
+    /// The maximum value (it has to be the last one).
+    UMF_COARSE_MEMORY_STRATEGY_MAX
+} coarse_memory_provider_strategy_t;
+
+/// @brief Coarse Memory Provider settings struct.
+typedef struct coarse_memory_provider_params_t {
+    /// Handle to the upstream memory provider.
+    /// It has to be NULL if init_buffer is set
+    /// (exactly one of them has to be non-NULL).
+    umf_memory_provider_handle_t upstream_memory_provider;
+
+    /// Memory allocation strategy.
+    /// See coarse_memory_provider_strategy_t for details.
+    coarse_memory_provider_strategy_t allocation_strategy;
+
+    /// A pre-allocated buffer that will be the only memory that
+    /// the coarse provider can provide (the fixed-size memory provider option).
+    /// If it is non-NULL, `init_buffer_size ` has to contain its size.
+    /// It has to be NULL if upstream_memory_provider is set
+    /// (exactly one of them has to be non-NULL).
+    void *init_buffer;
+
+    /// Size of the initial buffer:
+    /// 1) `init_buffer` if it is non-NULL xor
+    /// 2) that will be allocated from the upstream_memory_provider
+    ///    (if it is non-NULL) in the `.initialize` operation.
+    size_t init_buffer_size;
+
+    /// When it is true and the upstream_memory_provider is given,
+    /// the init buffer (of `init_buffer_size` bytes) would be pre-allocated
+    /// during creation time using the `upstream_memory_provider`.
+    /// If upstream_memory_provider is not given,
+    /// the init_buffer is always used instead
+    /// (regardless of the value of this parameter).
+    bool immediate_init_from_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 num_upstream_blocks;
+
+    /// Total number of allocated memory blocks.
+    size_t num_all_blocks;
+
+    /// Number of free memory blocks.
+    size_t num_free_blocks;
+} 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);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // UMF_COARSE_PROVIDER_H

scripts/docs_config/api.rst

@@ -80,6 +80,17 @@ and operate on the provider.
 .. doxygenfile:: memory_provider.h
     :sections: define enum typedef func var
 
+Coarse Provider
+------------------------------------------
+
+A memory provider that can provide memory from:
+1) a given pre-allocated buffer (the fixed-size memory provider option) or
+2) from an additional upstream provider (e.g. provider that does not support the free() operation
+   like the File memory provider or the DevDax memory provider - see below).
+
+.. doxygenfile:: provider_coarse.h
+    :sections: define enum typedef func var
+
 OS Memory Provider
 ------------------------------------------
 

src/CMakeLists.txt

@@ -110,6 +110,7 @@ set(UMF_SOURCES
     memtarget.c
     mempolicy.c
     memspace.c
+    provider/provider_coarse.c
     provider/provider_tracking.c
     critnib/critnib.c
     ravl/ravl.c
@@ -266,6 +267,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,8 @@ EXPORTS
     umfTearDown
     umfGetCurrentVersion
     umfCloseIPCHandle
+    umfCoarseMemoryProviderGetStats
+    umfCoarseMemoryProviderOps
     umfFree
     umfGetIPCHandle
     umfGetLastFailedMemoryProvider

src/libumf.map.in

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