oneapi-src · bratpiorka · Feb 15, 2024 · Jan 30, 2024 · Jan 30, 2024
@@ -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}}
 

@@ -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

@@ -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)

@@ -8,9 +8,97 @@
 [![Nightly](https://github.com/oneapi-src/unified-memory-framework/actions/workflows/nightly.yml/badge.svg?branch=main)](https://github.com/oneapi-src/unified-memory-framework/actions/workflows/nightly.yml)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/oneapi-src/unified-memory-framework/badge)](https://securityscorecards.dev/viewer/?uri=github.com/oneapi-src/unified-memory-framework)
 
+## Introduction
+
 The Unified Memory Framework (UMF) is a library for constructing allocators and memory pools. It also contains broadly useful abstractions and utilities for memory management. UMF allows users to manage multiple memory pools characterized by different attributes, allowing certain allocation types to be isolated from others and allocated using different hardware resources as required.
 
-# Architecture: memory pools and providers
+## Usage
+
+For a quick introduction to UMF usage, see [Example usage](https://oneapi-src.github.io/unified-memory-framework/example-usage.html),
+which includes the code of the basic [example](https://github.com/oneapi-src/unified-memory-framework/blob/main/examples/basic/basic.c).
+
+## Build
+
+### Requirements
+
+Required packages:
+- C compiler
+- [CMake](https://cmake.org/) >= 3.14.0
+
+For development and contributions:
+- clang-format-15.0 (can be installed with `python -m pip install clang-format==15.0.7`)
+
+For building tests, multithreaded benchmarks and Disjoint Pool:
+- C++ compiler with C++17 support
+
+### Linux
+
+Executable and binaries will be in **build/bin**
+
+```bash
+$ mkdir build
+$ cd build
+$ cmake {path_to_source_dir}
+$ make
+```
+
+### Windows
+
+Generating Visual Studio Project. EXE and binaries will be in **build/bin/{build_config}**
+
+```bash
+$ mkdir build
+$ cd build
+$ cmake {path_to_source_dir} -G "Visual Studio 15 2017 Win64"
+```
+
+### Benchmark
+
+UMF comes with a single-threaded micro benchmark based on [ubench](https://github.com/sheredom/ubench.h).
+In order to build the benchmark, the `UMF_BUILD_BENCHMARKS` CMake configuration flag has to be turned `ON`.
+
+UMF also provides multithreaded benchmarks that can be enabled by setting both
+`UMF_BUILD_BENCHMARKS` and `UMF_BUILD_BENCHMARKS_MT` CMake
+configuration flags to `ON`. Multithreaded benchmarks require a C++ support.
+
+### Sanitizers
+
+List of sanitizers available on Linux:
+- AddressSanitizer
+- UndefinedBehaviorSanitizer
+- ThreadSanitizer
+   - Is mutually exclusive with other sanitizers.
+- MemorySanitizer
+   - Requires linking against MSan-instrumented libraries to prevent false positive reports. More information [here](https://github.com/google/sanitizers/wiki/MemorySanitizerLibcxxHowTo).
+
+List of sanitizers available on Windows:
+- AddressSanitizer
+
+Listed sanitizers can be enabled with appropriate [CMake options](#cmake-standard-options).
+
+### CMake standard options
+
+List of options provided by CMake:
+
+| Name | Description | Values | Default |
+| - | - | - | - |
+| UMF_BUILD_SHARED_LIBRARY | Build UMF as shared library | ON/OFF | OFF |
+| UMF_BUILD_OS_MEMORY_PROVIDER | Build OS memory provider | ON/OFF | ON |
+| UMF_BUILD_LIBUMF_POOL_DISJOINT | Build the libumf_pool_disjoint static library | ON/OFF | OFF |
+| UMF_BUILD_LIBUMF_POOL_JEMALLOC | Build the libumf_pool_jemalloc static library | ON/OFF | OFF |
+| 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 |
+| USE_ASAN | Enable AddressSanitizer checks | ON/OFF | OFF |
+| USE_UBSAN | Enable UndefinedBehaviorSanitizer checks | ON/OFF | OFF |
+| USE_TSAN | Enable ThreadSanitizer checks | ON/OFF | OFF |
+| USE_MSAN | Enable MemorySanitizer checks | ON/OFF | OFF |
+
+## Architecture: memory pools and providers
 
 A UMF memory pool is a combination of a pool allocator and a memory provider. A memory provider is responsible for coarse-grained memory allocations and management of memory pages, while the pool allocator controls memory pooling and handles fine-grained memory allocations.
 
@@ -20,13 +108,13 @@ UMF comes with predefined pool allocators (see include/pool) and providers (see
 
 More detailed documentation is available here: https://oneapi-src.github.io/unified-memory-framework/
 
-## Memory providers
+### Memory providers
 
-### OS memory provider (Linux-only yet)
+#### OS memory provider (Linux-only yet)
 
 A memory provider that provides memory from an operating system.
 
-#### Requirements
+##### Requirements
 
 1) Linux OS
 2) The `UMF_BUILD_OS_MEMORY_PROVIDER` option turned `ON` (by default)
@@ -35,103 +123,44 @@ A memory provider that provides memory from an operating system.
 4) Required packages for tests:
    - libnuma-dev
 
-## Memory pool managers
+### Memory pool managers
 
-### proxy_pool (part of libumf)
+#### proxy_pool (part of libumf)
 
 This memory pool is distributed as part of libumf. It forwards all requests to the underlying
 memory provider. Currently umfPoolRealloc, umfPoolCalloc and umfPoolMallocUsableSize functions
 are not supported by the proxy pool.
 
-### libumf_pool_disjoint
+#### libumf_pool_disjoint
 
 TODO: Add a description
 
-#### Requirements
+##### Requirements
 
 To enable this feature, the `UMF_BUILD_LIBUMF_POOL_DISJOINT` option needs to be turned `ON`.
 
-### libumf_pool_jemalloc (Linux-only)
+#### libumf_pool_jemalloc (Linux-only)
 
 libumf_pool_jemalloc is a [jemalloc](https://github.com/jemalloc/jemalloc)-based memory pool manager built as a separate static library.
 The `UMF_BUILD_LIBUMF_POOL_JEMALLOC` option has to be turned `ON` to build this library.
 
-#### Requirements
+##### Requirements
 
 1) The `UMF_BUILD_LIBUMF_POOL_JEMALLOC` option turned `ON`
 2) Required packages:
    - libjemalloc-dev
 
-### libumf_pool_scalable (Linux-only)
+#### libumf_pool_scalable (Linux-only)
 
 libumf_pool_scalable is a [oneTBB](https://github.com/oneapi-src/oneTBB)-based memory pool manager built as a separate static library.
 The `UMF_BUILD_LIBUMF_POOL_SCALABLE` option has to be turned `ON` to build this library.
 
-#### Requirements
+##### Requirements
 
 1) The `UMF_BUILD_LIBUMF_POOL_SCALABLE` option turned `ON`
 2) Required packages:
    - libtbb-dev (libraries: libtbbmalloc.so.2)
 
-## Building
-
-### Requirements
-
-Required packages:
-- C compiler
-- [CMake](https://cmake.org/) >= 3.14.0
-
-For development and contributions:
-- clang-format-15.0 (can be installed with `python -m pip install clang-format==15.0.7`)
-
-For building tests, multithreaded benchmarks and Disjoint Pool:
-- C++ compiler with C++17 support
-
-### Benchmark
-
-UMF comes with a single-threaded micro benchmark based on [ubench](https://github.com/sheredom/ubench.h).
-In order to build the benchmark, the `UMF_BUILD_BENCHMARKS` CMake configuration flag has to be turned `ON`.
-
-UMF also provides multithreaded benchmarks that can be enabled by setting both
-`UMF_BUILD_BENCHMARKS` and `UMF_BUILD_BENCHMARKS_MT` CMake
-configuration flags to `ON`. Multithreaded benchmarks require a C++ support.
-
-### Windows
-
-Generating Visual Studio Project. EXE and binaries will be in **build/bin/{build_config}**
-
-```bash
-$ mkdir build
-$ cd build
-$ cmake {path_to_source_dir} -G "Visual Studio 15 2017 Win64"
-```
-
-### Linux
-
-Executable and binaries will be in **build/bin**
-
-```bash
-$ mkdir build
-$ cd build
-$ cmake {path_to_source_dir}
-$ make
-```
-
-### Sanitizers
-
-List of sanitizers available on Linux:
-- AddressSanitizer
-- UndefinedBehaviorSanitizer
-- ThreadSanitizer
-   - Is mutually exclusive with other sanitizers.
-- MemorySanitizer
-   - Requires linking against MSan-instrumented libraries to prevent false positive reports. More information [here](https://github.com/google/sanitizers/wiki/MemorySanitizerLibcxxHowTo).
-
-List of sanitizers available on Windows:
-- AddressSanitizer
-
-Listed sanitizers can be enabled with appropriate [CMake options](#cmake-standard-options).
-
 ## Contributions
 
 All code has to be formatted using clang-format. To check the formatting do:
@@ -148,24 +177,3 @@ Additionally, to apply code formatting do:
 ```bash
 $ make clang-format-apply
 ```
-
-### CMake standard options
-
-List of options provided by CMake:
-
-| Name | Description | Values | Default |
-| - | - | - | - |
-| UMF_BUILD_SHARED_LIBRARY | Build UMF as shared library | ON/OFF | OFF |
-| UMF_BUILD_OS_MEMORY_PROVIDER | Build OS memory provider | ON/OFF | ON |
-| UMF_BUILD_LIBUMF_POOL_DISJOINT | Build the libumf_pool_disjoint static library | ON/OFF | OFF |
-| UMF_BUILD_LIBUMF_POOL_JEMALLOC | Build the libumf_pool_jemalloc static library | ON/OFF | OFF |
-| 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_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 |
-| USE_ASAN | Enable AddressSanitizer checks | ON/OFF | OFF |
-| USE_UBSAN | Enable UndefinedBehaviorSanitizer checks | ON/OFF | OFF |
-| USE_TSAN | Enable ThreadSanitizer checks | ON/OFF | OFF |
-| USE_MSAN | Enable MemorySanitizer checks | ON/OFF | OFF |
@@ -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()
@@ -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