Merge pull request #715 from ldorau/new_coarse_provider

Add Coarse provider

Author: bratpiorka

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;