Add a basic example

Add an example with allocating memory with the usage of OS memory provider
and Scalable pool.

Author: PatKamin

.github/workflows/basic.yml

@@ -55,6 +55,7 @@ jobs:
         -DUSE_ASAN=${{matrix.sanitizers.asan}}
         -DUSE_UBSAN=${{matrix.sanitizers.ubsan}}
         -DUSE_TSAN=${{matrix.sanitizers.tsan}}
+        -DUMF_BUILD_EXAMPLES=ON
 
     - name: Build UMF
       run: |
@@ -63,14 +64,18 @@ jobs:
     - name: Run tests
       working-directory: ${{github.workspace}}/build
       run: |
-        ctest --output-on-failure
+        ctest --output-on-failure --test-dir test
 
     - name: Test make install
+      # Run only when the example is built
+      if: matrix.os_provider == 'ON' && matrix.pool_tracking == 'ON'
       working-directory: ${{env.BUILD_DIR}}
       run: ${{github.workspace}}/test/test_make_install.sh \
             ${{github.workspace}} ${{env.BUILD_DIR}} ${{env.INSTL_DIR}} ${{matrix.build_type}} ${{matrix.shared_library}}
 
     - name: Test make uninstall
+      # Run only when the example is built
+      if: matrix.os_provider == 'ON' && matrix.pool_tracking == 'ON'
       working-directory: ${{env.BUILD_DIR}}
       run: ${{github.workspace}}/test/test_make_uninstall.sh ${{github.workspace}} ${{env.BUILD_DIR}} ${{env.INSTL_DIR}}
 
@@ -194,11 +199,17 @@ jobs:
           ctest --output-on-failure
 
       - name: Test make install
+        # Run only when the example is built
+        # TODO: Modify installation test to accept output varying with build options
+        if: matrix.os_provider == 'ON' && matrix.pool_tracking == 'ON'
         working-directory: ${{env.BUILD_DIR}}
         run: ${{github.workspace}}/test/test_make_install.sh \
               ${{github.workspace}} ${{env.BUILD_DIR}} ${{env.INSTL_DIR}} ${{matrix.build_type}} ${{matrix.shared_library}}
 
       - name: Test make uninstall
+        # Run only when the example is built
+        # TODO: Modify installation test to accept output varying with build options
+        if: matrix.os_provider == 'ON' && matrix.pool_tracking == 'ON'
         working-directory: ${{env.BUILD_DIR}}
         run: ${{github.workspace}}/test/test_make_uninstall.sh ${{github.workspace}} ${{env.BUILD_DIR}} ${{env.INSTL_DIR}}
 

.github/workflows/pr_push.yml

@@ -49,11 +49,17 @@ jobs:
             -DUMF_BUILD_LIBUMF_POOL_DISJOINT=${{matrix.disjoint}}
             -DUMF_BUILD_LIBUMF_POOL_JEMALLOC=${{matrix.jemalloc}}
             -DUMF_BUILD_TESTS=OFF
+            -DUMF_BUILD_EXAMPLES=ON
 
         - name: Build
           run: >
             cmake --build ${{github.workspace}}/build --config Release -j ${{matrix.nproc}}
 
+        - name: Run examples
+          working-directory: ${{github.workspace}}/build
+          run: |
+            ctest --output-on-failure --test-dir examples
+
     CodeStyle:
       name: Coding style
       runs-on: ubuntu-latest

CMakeLists.txt

@@ -14,6 +14,7 @@ option(UMF_BUILD_LIBUMF_POOL_SCALABLE "Build the libumf_pool_scalable static lib
 option(UMF_BUILD_TESTS "Build UMF tests" ON)
 option(UMF_BUILD_BENCHMARKS "Build UMF benchmarks" OFF)
 option(UMF_BUILD_BENCHMARKS_MT "Build UMF multithreaded benchmarks" OFF)
+option(UMF_BUILD_EXAMPLES "Build UMF examples" ON)
 option(UMF_ENABLE_POOL_TRACKING "Build UMF with pool tracking" ON)
 option(UMF_DEVELOPER_MODE "Enable developer checks, treats warnings as errors" OFF)
 option(UMF_FORMAT_CODE_STYLE "Format UMF code with clang-format" OFF)
@@ -123,6 +124,10 @@ if(UMF_BUILD_BENCHMARKS)
     endif()
 endif()
 
+if(UMF_BUILD_EXAMPLES)
+    add_subdirectory(examples)
+endif()
+
 # Check if clang-format (in correct version) is available for code formatting.
 if(UMF_FORMAT_CODE_STYLE)
     find_program(CLANG_FORMAT NAMES clang-format-15 clang-format-15.0 clang-format)

README.md

@@ -89,6 +89,7 @@ List of options provided by CMake:
 | UMF_BUILD_LIBUMF_POOL_SCALABLE | Build the libumf_pool_scalable static library | ON/OFF | OFF |
 | UMF_BUILD_TESTS | Build UMF tests | ON/OFF | ON |
 | UMF_BUILD_BENCHMARKS | Build UMF benchmarks | ON/OFF | OFF |
+| UMF_BUILD_EXAMPLES | Build UMF examples | ON/OFF | ON |
 | UMF_ENABLE_POOL_TRACKING | Build UMF with pool tracking | ON/OFF | ON |
 | UMF_DEVELOPER_MODE | Treat warnings as errors and enables additional checks | ON/OFF | OFF |
 | UMF_FORMAT_CODE_STYLE | Add clang-format-check and clang-format-apply targets to make | ON/OFF | OFF |

examples/CMakeLists.txt

@@ -0,0 +1,29 @@
+# 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
+        AND UMF_ENABLE_POOL_TRACKING)
+   set(EXAMPLE_NAME umf_example_basic)
+   add_umf_executable(NAME ${EXAMPLE_NAME}
+                      SRCS basic/basic.c
+                      LIBS umf
+                           scalable_pool)
+    target_include_directories(${EXAMPLE_NAME} PRIVATE
+        ${UMF_CMAKE_SOURCE_DIR}/include)
+
+    add_test(NAME ${EXAMPLE_NAME}
+             COMMAND ${EXAMPLE_NAME}
+             WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
+
+    set_tests_properties(${EXAMPLE_NAME} PROPERTIES LABELS "example")
+
+    install(FILES basic/basic.c
+            DESTINATION "${CMAKE_INSTALL_DOCDIR}/examples")
+
+else()
+    message(STATUS "Basic example requires UMF_BUILD_OS_MEMORY_PROVIDER,
+                    UMF_BUILD_LIBUMF_POOL_SCALABLE and UMF_ENABLE_POOL_TRACKING
+                    to be turned ON - skipping")
+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 basic usage of a memory provider and a pool allocator. 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
+* UMF_ENABLE_POOL_TRACKING=ON

examples/basic/basic.c

@@ -0,0 +1,119 @@
+/*
+ *
+ * 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 an OS memory provider. It is used for allocating memory from
+    // NUMA nodes visible to the operating system.
+    // Allocations are made with mmap. The default values of params result
+    // in an mmap call like this:
+    // mmap(NULL, size, PROT_READ | PROT_WRITE, MAP_ANONYMOUS | MAP_PRIVATE, -1, 0)
+    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 a memory 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 =
+        umfMemoryProviderAlloc(provider, alloc_size, alignment, &ptr_provider);
+    if (res != UMF_RESULT_SUCCESS) {
+        printf("Failed to allocate memory from the memory provider!");
+        goto memory_provider_destroy;
+    }
+
+    // Write to the allocated memory
+    memset(ptr_provider, '\0', alloc_size);
+    strcpy(ptr_provider, "Allocated memory at");
+    printf("%s %p with the memory provider at %p\n", (char *)ptr_provider,
+           (void *)ptr_provider, (void *)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();
+    void *pool_params = NULL;
+    umf_pool_create_flags_t flags = 0;
+    umf_memory_pool_handle_t pool;
+
+    res = umfPoolCreate(pool_ops, provider, pool_params, flags, &pool);
+    if (res != UMF_RESULT_SUCCESS) {
+        printf("\nFailed to create a pool!");
+        goto memory_provider_destroy;
+    }
+    printf("\nScalable memory pool created at %p\n", (void *)pool);
+
+    // Allocate some memory in the pool
+    size_t num = 1;
+    alloc_size = 128;
+
+    char *ptr = umfPoolCalloc(pool, num, alloc_size);
+    if (!ptr) {
+        printf("Failed to allocate memory in the pool!");
+        goto memory_pool_destroy;
+    }
+
+    // Write a string to allocated memory
+    strcpy(ptr, "Allocated memory at");
+    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);
+    printf("Memory at %p has been allocated from the 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 the pool!");
+        goto memory_pool_destroy;
+    }
+    printf("Pool at %p has been allocated from the provider at %p\n",
+           (void *)pool, (void *)check_provider);
+
+    // Clean up.
+    // To free a pointer using the umfFree(ptr) function, ensure that memory tracking is enabled
+    // by setting the UMF_ENABLE_POOL_TRACKING option in the CMake configuration.
+    // If the memory tracking is disabled, you can call a different function:
+    // umfPoolFree(pool, ptr);
+    umfFree(ptr);
+    umfPoolDestroy(pool);
+    umfMemoryProviderDestroy(provider);
+    return 0;
+
+memory_pool_destroy:
+    umfPoolDestroy(pool);
+memory_provider_destroy:
+    umfMemoryProviderDestroy(provider);
+    return -1;
+}

scripts/docs_config/conf.py

@@ -22,7 +22,7 @@
 author = "Intel"
 
 # The full version, including alpha/beta/rc tags
-release = "0.9"
+release = "0.1.0"
 
 
 # -- General configuration ---------------------------------------------------
@@ -37,6 +37,7 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+primary_domain = "c"
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -52,3 +53,4 @@
 breathe_default_project = project
 breathe_show_include = False
 breathe_default_members = ("members", "undoc-members")
+breathe_domain_by_extension = {"h": "c"}

scripts/docs_config/example-usage.rst

@@ -0,0 +1,118 @@
+.. highlight:: c
+    :linenothreshold: 10
+
+==============================================================================
+Example usage
+==============================================================================
+
+This section will walk you through a basic usage
+of :ref:`memory provider <glossary-memory-provider>`
+and :ref:`pool allocator <glossary-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.
+
+There are some API functions that are supported only when the UMF is built
+with the memory tracking enabled (UMF_ENABLE_POOL_TRACKING=ON). These functions
+are explicitly described in this tutorial as requiring memory tracking.
+
+You can find the full example code in the `examples/basic/basic.c`_ file
+in the UMF repository.
+
+Memory provider usage
+------------------------------------------------------------------------------
+
+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
+a copy of 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 :any:`umfMemoryProviderCreate`::
+
+    umf_memory_provider_handle_t provider;
+    umfMemoryProviderCreate(provider_ops, &params, &provider);
+
+With this handle we can allocate a chunk of memory, call :any:`umfMemoryProviderAlloc`::
+
+    size_t alloc_size = 5000;
+    size_t alignment = 0;
+    void *ptr_provider = NULL;
+    umfMemoryProviderAlloc(provider, alloc_size, alignment, &ptr_provider);
+
+To free the memory allocated with a ``provider``, you have to pass the allocated
+size as the last parameter of :any:`umfMemoryProviderFree`::
+
+    umfMemoryProviderFree(provider, ptr_provider, alloc_size);
+
+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::
+  
+    umf_memory_pool_ops_t *pool_ops = umfScalablePoolOps();
+
+Argument ``pool_params`` is not used by the Scalable Pool, set it to ``NULL``::
+
+    void *pool_params = NULL;
+
+Here we don't make use of additional ``flags``.
+See the :any:`documentation <umf_pool_create_flags_t>` for available flags::
+
+    umf_pool_create_flags_t flags = 0;
+    
+The ``pool`` handle is retrieved as the last argument of
+the :any:`umfPoolCreate` function::
+
+    umf_memory_pool_handle_t pool;
+    umfPoolCreate(pool_ops, provider, pool_params, flags, &pool);
+
+The ``pool`` has been created, we can allocate some memory now
+with ie. :any:`umfPoolCalloc`::
+
+    size_t num = 1;
+    alloc_size = 128;
+    char *ptr = umfPoolCalloc(pool, num, alloc_size);
+
+With the memory tracking enabled, we can retrieve the pool handle used
+for allocating memory::
+
+    umf_memory_pool_handle_t check_pool = umfPoolByPtr(ptr);
+
+For any pool, you can retrieve the memory provider's handle
+that was used to create the ``pool`` with :any:`umfPoolGetMemoryProvider`::
+
+    umf_memory_provider_handle_t check_provider;
+    umfPoolGetMemoryProvider(pool, &check_provider);
+
+Freeing memory is as easy as can be::
+
+    umfFree(ptr);
+    umfPoolDestroy(pool);
+    umfMemoryProviderDestroy(provider);
+
+.. note::
+    To free a pointer using the :any:`umfFree` function, ensure that memory tracking is enabled
+    by setting the UMF_ENABLE_POOL_TRACKING option in the CMake configuration.
+    If the memory tracking is disabled, you should call a different function:
+    :any:`umfPoolFree`.
+
+.. _examples/basic/basic.c: https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/basic/basic.c
+.. _README: https://github.com/oneapi-src/unified-memory-framework/blob/main/README.md#memory-pool-managers
+.. _provider_os_memory.h: https://github.com/oneapi-src/unified-memory-framework/blob/main/include/umf/providers/provider_os_memory.h
+.. _pool_scalable.h: https://github.com/oneapi-src/unified-memory-framework/blob/main/include/umf/pools/pool_scalable.h