Merge pull request #680 from ldorau/Add_file_memory_provider

Add file memory provider

CMakeLists.txt

@@ -421,6 +421,7 @@ if(NOT UMF_DISABLE_HWLOC)
     add_optional_symbol(umfOsMemoryProviderOps)
     if(LINUX)
         add_optional_symbol(umfDevDaxMemoryProviderOps)
+        add_optional_symbol(umfFileMemoryProviderOps)
     endif()
 endif()
 

README.md

@@ -188,6 +188,21 @@ with the `disable_provider_free` parameter set to true.
 1) Linux OS
 2) A character device file /dev/daxX.Y created in the OS.
 
+#### File memory provider (Linux only yet)
+
+A memory provider that provides memory by mapping a regular, extendable file.
+
+The file memory provider does not support the free operation
+(`umfMemoryProviderFree()` always returns `UMF_RESULT_ERROR_NOT_SUPPORTED`),
+so it should be used with a pool manager that will take over
+the managing of the provided memory - for example the jemalloc pool
+with the `disable_provider_free` parameter set to true.
+
+##### Requirements
+
+1) Linux OS
+2) A length of a path of a file to be mapped can be `PATH_MAX` (4096) characters at most.
+
 ### Memory pool managers
 
 #### Proxy pool (part of libumf)

include/umf/providers/provider_file_memory.h

@@ -0,0 +1,57 @@
+/*
+ * Copyright (C) 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_FILE_MEMORY_PROVIDER_H
+#define UMF_FILE_MEMORY_PROVIDER_H
+
+#include <umf/providers/provider_os_memory.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// @cond
+#define UMF_FILE_RESULTS_START_FROM 3000
+/// @endcond
+
+/// @brief Memory provider settings struct
+typedef struct umf_file_memory_provider_params_t {
+    /// a path to the file (of maximum length PATH_MAX characters)
+    const char *path;
+    /// combination of 'umf_mem_protection_flags_t' flags
+    unsigned protection;
+    /// memory visibility mode
+    umf_memory_visibility_t visibility;
+} umf_file_memory_provider_params_t;
+
+/// @brief File Memory Provider operation results
+typedef enum umf_file_memory_provider_native_error {
+    UMF_FILE_RESULT_SUCCESS = UMF_FILE_RESULTS_START_FROM, ///< Success
+    UMF_FILE_RESULT_ERROR_ALLOC_FAILED,       ///< Memory allocation failed
+    UMF_FILE_RESULT_ERROR_FREE_FAILED,        ///< Memory deallocation failed
+    UMF_FILE_RESULT_ERROR_PURGE_FORCE_FAILED, ///< Force purging failed
+} umf_file_memory_provider_native_error_t;
+
+umf_memory_provider_ops_t *umfFileMemoryProviderOps(void);
+
+/// @brief Create default params for the file memory provider
+static inline umf_file_memory_provider_params_t
+umfFileMemoryProviderParamsDefault(const char *path) {
+    umf_file_memory_provider_params_t params = {
+        path,                                       /* a path to the file */
+        UMF_PROTECTION_READ | UMF_PROTECTION_WRITE, /* protection */
+        UMF_MEM_MAP_PRIVATE,                        /* visibility mode */
+    };
+
+    return params;
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* UMF_FILE_MEMORY_PROVIDER_H */

scripts/docs_config/api.rst

@@ -104,6 +104,14 @@ A memory provider that provides memory from a device DAX (a character device fil
 .. doxygenfile:: provider_devdax_memory.h
     :sections: define enum typedef func var
 
+File Memory Provider
+------------------------------------------
+
+A memory provider that provides memory by mapping a regular, extendable file.
+
+.. doxygenfile:: provider_file_memory.h
+    :sections: define enum typedef func var
+
 Memspace
 ==========================================
 

src/CMakeLists.txt

@@ -102,6 +102,7 @@ set(UMF_SOURCES_WINDOWS libumf_windows.c)
 
 set(UMF_SOURCES_COMMON_LINUX_MACOSX
     provider/provider_devdax_memory.c
+    provider/provider_file_memory.c
     provider/provider_os_memory.c
     provider/provider_os_memory_posix.c
     memtargets/memtarget_numa.c