Add a basic example

Add an example with allocating memory with the usage of OS Memory Provider
and Scalable Pool.

Author: PatKamin

CMakeLists.txt

@@ -108,6 +108,7 @@ install(
     EXPORT ${PROJECT_NAME}-targets)
 
 add_subdirectory(src)
+add_subdirectory(examples)
 
 if(UMF_BUILD_TESTS)
     add_subdirectory(test)

examples/CMakeLists.txt

@@ -0,0 +1,13 @@
+# 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
+
+if(UMF_BUILD_OS_MEMORY_PROVIDER AND UMF_BUILD_LIBUMF_POOL_SCALABLE)
+    add_umf_executable(NAME basic 
+                       SRCS basic/basic.c
+                       LIBS umf
+                            scalable_pool
+                            pthread)
+    target_include_directories(basic PRIVATE
+        ${UMF_CMAKE_SOURCE_DIR}/include)
+endif()

examples/README.md

@@ -0,0 +1,12 @@
+# Examples
+
+This directory contains examples of UMF usage. Each example has a brief description below.
+
+## Basic
+
+This example covers the basics of UMF API. It walks you through a memory provider
+and pool allocator creation. OS memory provider and Scalable Pool are used for this purpose.
+
+### Required CMake configuration flags
+* UMF_BUILD_OS_MEMORY_PROVIDER=ON
+* UMF_BUILD_LIBUMF_POOL_SCALABLE=ON

examples/basic/basic.c

@@ -0,0 +1,113 @@
+/*
+ *
+ * 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
+ *
+ */
+
+#include "umf/pools/pool_scalable.h"
+#include "umf/providers/provider_os_memory.h"
+
+#include <stdio.h>
+#include <string.h>
+
+int main(void) {
+    // A result object for storing UMF API result status
+    umf_result_t res;
+
+    // Create a memory provider
+    umf_memory_provider_ops_t *provider_ops = umfOsMemoryProviderOps();
+    umf_os_memory_provider_params_t params = umfOsMemoryProviderParamsDefault();
+    umf_memory_provider_handle_t provider;
+
+    res = umfMemoryProviderCreate(provider_ops, &params, &provider);
+    if (res != UMF_RESULT_SUCCESS) {
+        printf("Failed to create provider!");
+        return -1;
+    }
+    printf("OS Memory Provider created at %p\n", (void *)provider);
+
+    // Allocate memory from memory provider
+    size_t alloc_size = 5000;
+    size_t alignment = 0;
+    void *ptr_provider = NULL;
+
+    res = umfMemoryProviderGetRecommendedPageSize(provider, alloc_size,
+                                                  &alignment);
+    if (res != UMF_RESULT_SUCCESS || alignment == 0) {
+        printf("Failed to get recommended page size!");
+        goto memory_provider_destroy;
+    }
+    printf("Recommended page size is %zu bytes\n", alignment);
+
+    res =
+        umfMemoryProviderAlloc(provider, alloc_size, alignment, &ptr_provider);
+    if (res != UMF_RESULT_SUCCESS) {
+        printf("Failed to allocate memory from the provider!");
+        goto memory_provider_destroy;
+    }
+    printf("Allocated memory at %p\n", ptr_provider);
+
+    // Free allocated memory
+    res = umfMemoryProviderFree(provider, ptr_provider, alloc_size);
+    if (res != UMF_RESULT_SUCCESS) {
+        printf("Failed to free memory to the provider!");
+        goto memory_provider_destroy;
+    }
+    printf("Freed memory at %p\n", ptr_provider);
+
+    // Create a memory pool
+    umf_memory_pool_ops_t *pool_ops = umfScalablePoolOps();
+    umf_pool_create_flags_t flags = 0;
+    void *pool_params = NULL;
+    umf_memory_pool_handle_t pool;
+
+    res = umfPoolCreate(pool_ops, provider, pool_params, flags, &pool);
+    if (res != UMF_RESULT_SUCCESS) {
+        printf("\nFailed to create pool!");
+        goto memory_provider_destroy;
+    }
+    printf("\nScalable Memory Pool created at %p\n", (void *)pool);
+
+    // Allocate some memory
+    size_t num = 1;
+    alloc_size = 128;
+
+    char *ptr = umfPoolCalloc(pool, num, alloc_size);
+    if (!ptr) {
+        printf("Failed to allocate memory!");
+        goto memory_pool_destroy;
+    }
+
+    strcpy(ptr, "Allocated memory at");
+    printf("%s %p\n", ptr, (void *)ptr);
+
+    // Retrieve a memory pool from a pointer, available with memory tracking
+    // RFC: Remove this? With memory tracker disabled, NULL returned may be misleading
+    umf_memory_pool_handle_t check_pool = umfPoolByPtr(ptr);
+    printf("Memory at %p has been allocated from pool at %p\n", (void *)ptr,
+           (void *)check_pool);
+
+    // Retrieve a memory provider from a pool
+    umf_memory_provider_handle_t check_provider;
+    res = umfPoolGetMemoryProvider(pool, &check_provider);
+    if (res != UMF_RESULT_SUCCESS) {
+        printf("Failed to retrieve a memory provider for pool!");
+        goto memory_pool_destroy;
+    }
+    printf("Pool at %p has been allocated from provider at %p\n", (void *)pool,
+           (void *)check_provider);
+
+    umfPoolFree(pool, ptr);
+    umfPoolDestroy(pool);
+    umfMemoryProviderDestroy(provider);
+    return 0;
+
+memory_pool_destroy:
+    umfPoolDestroy(pool);
+memory_provider_destroy:
+    umfMemoryProviderDestroy(provider);
+    return -1;
+}

scripts/docs_config/example-usage.rst

@@ -0,0 +1,73 @@
+.. highlight:: c
+    :linenothreshold: 10
+
+==============================================================================
+Example usage
+==============================================================================
+
+This section will walk you through a basic usage of memory provider
+and pool allocator. OS Memory Provider and Scalable Pool will be used for this purpose.
+
+There are also other memory pools available in the UMF. See `README`_ for
+more information.
+
+You can find the full example code in the `examples/basic/basic.c`_ file
+in the UMF repository.
+
+TODO: Update the link to upstream
+
+Memory provider usage
+------------------------------------------------------------------------------
+
+TODO: Add links wherever possible
+
+First, let's create a memory provider object for coarse-grained allocations.
+You have to include the ``provider_os_memory.h`` header with
+the OS Memory Provider API::
+
+    #include "umf/providers/provider_os_memory.h"
+
+Get a pointer to the OS Memory Provider operations struct and default parameters::
+
+    umf_memory_provider_ops_t *provider_ops = umfOsMemoryProviderOps();
+    umf_os_memory_provider_params_t params = umfOsMemoryProviderParamsDefault();
+
+The handle to created memory ``provider`` object is returned as the last argument
+of ``umfMemoryProviderCreate()``::
+
+    umf_memory_provider_handle_t provider;
+    umfMemoryProviderCreate(provider_ops, &params, &provider);
+
+TODO: Describe more operations used in the example file.
+
+Memory pool usage
+------------------------------------------------------------------------------
+
+Having created a memory ``provider``, you can create a Scalable Memory ``pool``
+to be used for fine-grained allocations. You have to include
+the ``pool_scalable.h`` header with the Scalable Memory Pool API::
+
+    #include "umf/pools/pool_scalable.h"
+
+Use the default set of operations for the Scalable Memory Pool,
+by retrieving an address of the default ops struct with ``umfScalablePoolOps()``::
+  
+    umf_memory_pool_ops_t *pool_ops = umfScalablePoolOps();
+
+Here we don't make use of additional flags. See `documentation` for available flags::
+
+    umf_pool_create_flags_t flags = 0;
+
+Argument `pool_params` is not used by the Scalable Pool::
+
+    void *pool_params = NULL;
+    
+The `pool` is retrieved as the last argument of the `umfPoolCreate` function::
+
+    umf_memory_pool_handle_t pool;
+    umfPoolCreate(pool_ops, provider, pool_params, flags, &pool);
+
+TODO: Describe more operations used in the example file.
+
+.. _examples/basic/basic.c: https://github.com/patkamin/unified-memory-framework/blob/main/examples/basic/basic.c
+.. _README: https://github.com/patkamin/unified-memory-framework/blob/main/README.md

scripts/docs_config/index.rst

@@ -8,5 +8,6 @@ Intel Unified Memory Framework documentation
    :maxdepth: 3
 
    introduction.rst
+   example-usage.rst
    api.rst
    glossary.rst

third_party/requirements.txt

@@ -2,6 +2,7 @@
 # Formatting the source code
 clang-format==15.0.7
 # Generating HTML documentation
+pygments==2.5.2
 sphinxcontrib_applehelp==1.0.4
 sphinxcontrib_devhelp==1.0.2
 sphinxcontrib_htmlhelp==2.0.1