return umf_result in (almost) all umf functions

Author: lplewa

examples/basic/basic.c

@@ -96,7 +96,12 @@ int main(void) {
     printf("%s %p\n", ptr, (void *)ptr);
 
     // Retrieve a memory pool from a pointer, available with memory tracking
-    umf_memory_pool_handle_t check_pool = umfPoolByPtr(ptr);
+    umf_memory_pool_handle_t check_pool;
+    res = umfPoolByPtr(ptr, &check_pool);
+    if (res != UMF_RESULT_SUCCESS) {
+        printf("Failed to retrieve a memory pool for the pointer!\n");
+        goto memory_pool_destroy;
+    }
     printf("Memory at %p has been allocated from the pool at %p\n", (void *)ptr,
            (void *)check_pool);
 

examples/custom_file_provider/custom_file_provider.c

@@ -201,18 +201,21 @@ static umf_result_t file_free(void *provider, void *ptr, size_t size) {
 }
 
 // Function to get the name of the file provider
-static const char *file_get_name(void *provider) {
+static umf_result_t file_get_name(void *provider, const char **name) {
     (void)provider; // Unused parameter
-    return "File Provider";
+    *name = "File Provider";
+    return UMF_RESULT_SUCCESS;
 }
 
 // Function to get the last native error of the file provider
 // This function is needed only if the provider returns UMF_RESULT_ERROR_MEMORY_PROVIDER_SPECIFIC
-static void file_get_last_native_error(void *provider, const char **ppMessage,
-                                       int32_t *pError) {
+static umf_result_t file_get_last_native_error(void *provider,
+                                               const char **ppMessage,
+                                               int32_t *pError) {
     (void)provider; // Unused parameter
     *ppMessage = "";
     *pError = 0;
+    return UMF_RESULT_SUCCESS;
 }
 
 // Function to get the recommended page size of the file provider
@@ -319,7 +322,12 @@ int main(void) {
     printf("%s %p\n", ptr, (void *)ptr);
 
     // Retrieve a memory pool from a pointer, available with memory tracking
-    umf_memory_pool_handle_t check_pool = umfPoolByPtr(ptr);
+    umf_memory_pool_handle_t check_pool;
+    res = umfPoolByPtr(ptr, &check_pool);
+    if (res != UMF_RESULT_SUCCESS) {
+        fprintf(stderr, "Failed to retrieve a memory pool for the pointer!\n");
+        goto memory_pool_destroy;
+    }
     printf("Memory at %p has been allocated from the pool at %p\n", (void *)ptr,
            (void *)check_pool);
 

include/umf.h

@@ -10,6 +10,7 @@
 #ifndef UMF_UNIFIED_MEMORY_FRAMEWORK_H
 #define UMF_UNIFIED_MEMORY_FRAMEWORK_H 1
 
+#include <umf/base.h>
 #include <umf/memory_pool.h>
 #include <umf/memory_provider.h>
 #include <umf/mempolicy.h>
@@ -23,17 +24,19 @@ extern "C" {
 /// @brief  Increment the usage reference counter and initialize the global state of libumf
 ///         if the usage reference counter was equal to 0.
 ///         It must be called just after dlopen() and it is not required in other scenarios.
-/// @return 0 on success or -1 on failure.
-int umfInit(void);
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+umf_result_t umfInit(void);
 
 ///
 /// @brief Decrement the usage reference counter and destroy the global state of libumf
 ///        if the usage reference counter is equal to 0.
 ///        It must be called just before dlclose() and it is not required in other scenarios.
-void umfTearDown(void);
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+umf_result_t umfTearDown(void);
 
 ///
 /// @brief Get the current version of the UMF headers defined by UMF_VERSION_CURRENT.
+/// @return The current version of the UMF headers.
 int umfGetCurrentVersion(void);
 
 #ifdef __cplusplus

include/umf/ipc.h

@@ -1,6 +1,6 @@
 /*
  *
- * Copyright (C) 2023-2024 Intel Corporation
+ * Copyright (C) 2023-2025 Intel Corporation
  *
  * Under the Apache License v2.0 with LLVM Exceptions. See LICENSE.TXT.
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
@@ -66,6 +66,7 @@ umf_result_t umfCloseIPCHandle(void *ptr);
 umf_result_t umfPoolGetIPCHandler(umf_memory_pool_handle_t hPool,
                                   umf_ipc_handler_handle_t *hIPCHandler);
 
+/// todo: IPC handler creation and destruction (IPC provider??)
 #ifdef __cplusplus
 }
 #endif

include/umf/memory_pool.h

@@ -10,6 +10,8 @@
 #ifndef UMF_MEMORY_POOL_H
 #define UMF_MEMORY_POOL_H 1
 
+#include <stddef.h>
+
 #include <umf/base.h>
 #include <umf/memory_pool_ops.h>
 #include <umf/memory_provider.h>
@@ -105,9 +107,11 @@ void *umfPoolRealloc(umf_memory_pool_handle_t hPool, void *ptr, size_t size);
 /// @brief Obtains size of block of memory allocated from the \p hPool for a given \p ptr
 /// @param hPool specified memory hPool
 /// @param ptr pointer to the allocated memory
-/// @return size of the memory block allocated from the \p hPool
+/// @param size [out] pointer to a variable that will receive the size of the memory block
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
 ///
-size_t umfPoolMallocUsableSize(umf_memory_pool_handle_t hPool, const void *ptr);
+umf_result_t umfPoolMallocUsableSize(umf_memory_pool_handle_t hPool,
+                                     const void *ptr, size_t *size);
 
 ///
 /// @brief Frees the memory space of the specified \p hPool pointed by \p ptr
@@ -152,14 +156,16 @@ umf_result_t umfPoolGetLastAllocationError(umf_memory_pool_handle_t hPool);
 /// @brief Retrieve memory pool associated with a given ptr. Only memory allocated
 ///        with the usage of a memory provider is being tracked.
 /// @param ptr pointer to memory belonging to a memory pool
-/// @return Handle to a memory pool that contains ptr or NULL if pointer does not belong to any UMF pool.
+/// @param pool [out] handle to the memory pool that contains ptr
+/// @return UMF_RESULT_SUCCESS on success
+///         UMF_RESULT_ERROR_INVALID_ARGUMENT if pool is NULL, or ptr do not belongs to any pool.
 ///
-umf_memory_pool_handle_t umfPoolByPtr(const void *ptr);
+umf_result_t umfPoolByPtr(const void *ptr, umf_memory_pool_handle_t *pool);
 
 ///
 /// @brief Retrieve memory provider associated with a given pool.
 /// @param hPool specified memory pool
-/// @param hProvider [out] memory providers handle.
+/// @param hProvider [out] memory providers handle
 /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
 ///         UMF_RESULT_ERROR_INVALID_ARGUMENT if hProvider is NULL
 ///
@@ -169,10 +175,10 @@ umf_result_t umfPoolGetMemoryProvider(umf_memory_pool_handle_t hPool,
 ///
 /// @brief Retrieve name of a given memory \p pool.
 /// @param pool handle to the memory pool
-/// @return pointer to a string containing the name of the \p pool
-///         or NULL if the pool doesn't support retrieving its name.
+/// @param name [out] pointer to a string containing the name of the \p pool
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
 ///
-const char *umfPoolGetName(umf_memory_pool_handle_t pool);
+umf_result_t umfPoolGetName(umf_memory_pool_handle_t pool, const char **name);
 
 ///
 /// @brief Set a custom tag on the memory pool that can be later retrieved using umfPoolGetTag.

include/umf/memory_pool_ops.h

@@ -93,9 +93,11 @@ typedef struct umf_memory_pool_ops_t {
     /// @brief Obtains size of block of memory allocated from the \p pool for a given \p ptr
     /// @param pool pointer to the memory pool
     /// @param ptr pointer to the allocated memory
-    /// @return size of the memory block allocated from the \p pool
+    /// @param size [out] size of the memory block allocated from the \p pool
+    /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
     ///
-    size_t (*malloc_usable_size)(void *pool, const void *ptr);
+    umf_result_t (*malloc_usable_size)(void *pool, const void *ptr,
+                                       size_t *size);
 
     ///
     /// @brief Frees the memory space of the specified \p pool pointed by \p ptr
@@ -105,7 +107,7 @@ typedef struct umf_memory_pool_ops_t {
     ///         Whether any status other than UMF_RESULT_SUCCESS can be returned
     ///         depends on the memory provider used by the \p pool.
     ///
-    umf_result_t (*free)(void *pool, void *);
+    umf_result_t (*free)(void *pool, void *ptr);
 
     ///
     /// @brief Retrieve \p umf_result_t representing the error of the last failed allocation
@@ -153,14 +155,15 @@ typedef struct umf_memory_pool_ops_t {
     ///
     /// @brief Retrieves the name of the memory pool
     /// @param pool valid pointer to the memory pool or NULL value
+    /// @param name [out] pointer to a constant character string that will be set to the pool's name
     /// \details
     /// * Implementations *must* return a literal null-terminated string.
     ///
     /// * Implementations *must* return default pool name when NULL is provided,
     ///   otherwise the pool's name is returned.
-    /// @return A constant character string representing the pool's name.
+    /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
     ///
-    const char *(*ext_get_name)(void *pool);
+    umf_result_t (*ext_get_name)(void *pool, const char **name);
 } umf_memory_pool_ops_t;
 
 #ifdef __cplusplus

include/umf/memory_provider.h

@@ -24,15 +24,15 @@ typedef enum umf_memory_visibility_t {
 } umf_memory_visibility_t;
 
 /// @brief Protection of the memory allocations
-typedef enum umf_mem_protection_flags_t {
+typedef enum umf_mem_protection_flag_t {
     UMF_PROTECTION_NONE = (1 << 0),  ///< Memory allocations can not be accessed
     UMF_PROTECTION_READ = (1 << 1),  ///< Memory allocations can be read.
     UMF_PROTECTION_WRITE = (1 << 2), ///< Memory allocations can be written.
     UMF_PROTECTION_EXEC = (1 << 3),  ///< Memory allocations can be executed.
     /// @cond
     UMF_PROTECTION_MAX // must be the last one
     /// @endcond
-} umf_mem_protection_flags_t;
+} umf_mem_protection_flag_t;
 
 /// @brief A struct containing memory provider specific set of functions
 typedef struct umf_memory_provider_t *umf_memory_provider_handle_t;
@@ -100,10 +100,11 @@ umf_result_t umfMemoryProviderFree(umf_memory_provider_handle_t hProvider,
 /// @param ppMessage [out] pointer to a string containing provider specific
 ///        result in string representation
 /// @param pError [out] pointer to an integer where the adapter specific error code will be stored
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
 ///
-void umfMemoryProviderGetLastNativeError(umf_memory_provider_handle_t hProvider,
-                                         const char **ppMessage,
-                                         int32_t *pError);
+umf_result_t
+umfMemoryProviderGetLastNativeError(umf_memory_provider_handle_t hProvider,
+                                    const char **ppMessage, int32_t *pError);
 
 ///
 /// @brief Retrieve recommended page size for a given allocation size.
@@ -217,9 +218,10 @@ umfMemoryProviderCloseIPCHandle(umf_memory_provider_handle_t hProvider,
 ///
 /// @brief Retrieve name of a given memory \p hProvider.
 /// @param hProvider handle to the memory provider
-/// @return pointer to a string containing the name of the \p hProvider
-///
-const char *umfMemoryProviderGetName(umf_memory_provider_handle_t hProvider);
+/// @param name [out] pointer to the provider name string
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure
+umf_result_t umfMemoryProviderGetName(umf_memory_provider_handle_t hProvider,
+                                      const char **name);
 
 ///
 /// @brief Retrieve handle to the last memory provider that returned status other
@@ -231,7 +233,8 @@ const char *umfMemoryProviderGetName(umf_memory_provider_handle_t hProvider);
 ///
 /// @return Handle to the memory provider
 ///
-umf_memory_provider_handle_t umfGetLastFailedMemoryProvider(void);
+umf_result_t
+umfGetLastFailedMemoryProvider(umf_memory_provider_handle_t *provider);
 
 ///
 /// @brief Splits a coarse grain allocation into 2 adjacent allocations that

include/umf/memory_provider_ops.h

@@ -90,9 +90,11 @@ typedef struct umf_memory_provider_ops_t {
     /// @param ppMessage [out] pointer to a string containing provider specific
     ///        result in string representation
     /// @param pError [out] pointer to an integer where the adapter specific error code will be stored
+    /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
     ///
-    void (*get_last_native_error)(void *provider, const char **ppMessage,
-                                  int32_t *pError);
+    umf_result_t (*get_last_native_error)(void *provider,
+                                          const char **ppMessage,
+                                          int32_t *pError);
 
     ///
     /// @brief Retrieve recommended page size for a given allocation size.
@@ -118,9 +120,10 @@ typedef struct umf_memory_provider_ops_t {
     ///
     /// @brief Retrieve name of a given memory \p provider.
     /// @param provider pointer to the memory provider
-    /// @return pointer to a string containing the name of the \p provider
+    /// @param name [out] pointer to a string containing the name of the \p provider
+    /// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
     ///
-    const char *(*get_name)(void *provider);
+    umf_result_t (*get_name)(void *provider, const char **name);
 
     ///
     /// Following functions, with ext prefix, are optional and memory provider implementation

include/umf/pools/pool_disjoint.h

@@ -29,9 +29,10 @@ typedef struct umf_disjoint_pool_params_t *umf_disjoint_pool_params_handle_t;
 
 /// @brief Create a pool limits struct.
 /// @param MaxSize specifies hard limit for memory allocated from a provider.
-/// @return handle to the created shared limits struct.
-umf_disjoint_pool_shared_limits_handle_t
-umfDisjointPoolSharedLimitsCreate(size_t MaxSize);
+/// @param hSharedLimits [out] handle to the newly created shared limits struct.
+/// @return UMF_RESULT_SUCCESS on success or appropriate error code on failure.
+umf_result_t umfDisjointPoolSharedLimitsCreate(
+    size_t MaxSize, umf_disjoint_pool_shared_limits_handle_t *hSharedLimits);
 
 /// @brief Destroy previously created pool limits struct.
 /// @param hSharedLimits handle to the shared limits struct.

src/libumf.c

@@ -33,21 +33,21 @@ static umf_ctl_node_t CTL_NODE(umf)[] = {CTL_CHILD(provider), CTL_CHILD(pool),
 
 void initialize_global_ctl(void) { CTL_REGISTER_MODULE(NULL, umf); }
 
-int umfInit(void) {
+umf_result_t umfInit(void) {
     if (utils_fetch_and_add_u64(&umfRefCount, 1) == 0) {
         utils_log_init();
-        TRACKER = umfMemoryTrackerCreate();
-        if (!TRACKER) {
+        umf_result_t umf_result = umfMemoryTrackerCreate(&TRACKER);
+        if (umf_result != UMF_RESULT_SUCCESS) {
             LOG_ERR("Failed to create memory tracker");
-            return -1;
+            return umf_result;
         }
 
         LOG_DEBUG("UMF tracker created");
 
-        umf_result_t umf_result = umfIpcCacheGlobalInit();
+        umf_result = umfIpcCacheGlobalInit();
         if (umf_result != UMF_RESULT_SUCCESS) {
             LOG_ERR("Failed to initialize IPC cache");
-            return -1;
+            return umf_result;
         }
 
         LOG_DEBUG("UMF IPC cache initialized");
@@ -58,10 +58,10 @@ int umfInit(void) {
         LOG_DEBUG("UMF library initialized");
     }
 
-    return 0;
+    return UMF_RESULT_SUCCESS;
 }
 
-void umfTearDown(void) {
+umf_result_t umfTearDown(void) {
     if (utils_fetch_and_sub_u64(&umfRefCount, 1) == 1) {
 #if !defined(_WIN32) && !defined(UMF_NO_HWLOC)
         umfMemspaceHostAllDestroy();
@@ -95,6 +95,7 @@ void umfTearDown(void) {
         fini_tbb_global_state();
         LOG_DEBUG("UMF library finalized");
     }
+    return UMF_RESULT_SUCCESS;
 }
 
 int umfGetCurrentVersion(void) { return UMF_VERSION_CURRENT; }