Merge pull request #506 from ldorau/Replace_an_anonymous_file_with_a_shared_memory_object

Add support for a named POSIX shared memory to OS memory provider

Author: bratpiorka

CMakeLists.txt

@@ -479,9 +479,10 @@ install(
           examples/basic/utils_level_zero.h
           examples/basic/basic.c
           examples/basic/ipc_level_zero.c
-          examples/basic/ipc_shm_ipcapi.sh
-          examples/basic/ipc_shm_ipcapi_consumer.c
-          examples/basic/ipc_shm_ipcapi_producer.c
+          examples/basic/ipc_ipcapi_anon_fd.sh
+          examples/basic/ipc_ipcapi_consumer.c
+          examples/basic/ipc_ipcapi_producer.c
+          examples/basic/ipc_ipcapi_shm.sh
     DESTINATION "${CMAKE_INSTALL_DOCDIR}/examples")
 
 # Add the include directory and the headers target to the install.

README.md

@@ -142,11 +142,18 @@ More detailed documentation is available here: https://oneapi-src.github.io/unif
 #### OS memory provider
 
 A memory provider that provides memory from an operating system.
-It supports two types of memory mappings
+
+OS memory provider supports two types of memory mappings (set by the `visibility` parameter):
 1) private memory mapping (`UMF_MEM_MAP_PRIVATE`)
 2) shared memory mapping (`UMF_MEM_MAP_SHARED` - supported on Linux only yet)
 
-If the shared memory mapping is used then an anonymous file descriptor for memory mapping is created using:
+There are available two mechanisms for the shared memory mapping:
+1) a named shared memory object (used if the `shm_name` parameter is not NULL) or
+2) an anonymous file descriptor (used if the `shm_name` parameter is NULL)
+
+The `shm_name` parameter should be a null-terminated string of up to NAME_MAX (i.e., 255) characters none of which are slashes.
+
+An anonymous file descriptor for the shared memory mapping will be created using:
 1) `memfd_secret()` syscall - (if it is implemented and) if the `UMF_MEM_FD_FUNC` environment variable does not contain the "memfd_create" string or
 2) `memfd_create()` syscall - otherwise (and if it is implemented).
 

examples/CMakeLists.txt

@@ -116,8 +116,8 @@ else()
     )
 endif()
 
-if(LINUX)
-    set(BASE_NAME ipc_shm_ipcapi)
+function(build_umf_ipc_example name)
+    set(BASE_NAME ${name})
     set(EXAMPLE_NAME umf_example_${BASE_NAME})
 
     foreach(loop_var IN ITEMS "producer" "consumer")
@@ -133,22 +133,32 @@ if(LINUX)
 
         target_link_directories(${EX_NAME} PRIVATE ${LIBHWLOC_LIBRARY_DIRS})
     endforeach(loop_var)
+endfunction()
+
+function(add_umf_ipc_example script)
+    set(EXAMPLE_NAME umf_example_${script})
 
-    file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/basic/${BASE_NAME}.sh
+    file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/basic/${script}.sh
          DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
 
     add_test(
         NAME ${EXAMPLE_NAME}
-        COMMAND ${BASE_NAME}.sh
+        COMMAND ${script}.sh
         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
 
     set_tests_properties(${EXAMPLE_NAME} PROPERTIES LABELS "example")
     if(NOT UMF_TESTS_FAIL_ON_SKIP)
         set_tests_properties(${EXAMPLE_NAME} PROPERTIES SKIP_RETURN_CODE 125)
     endif()
+endfunction()
+
+if(LINUX)
+    build_umf_ipc_example(ipc_ipcapi)
+    add_umf_ipc_example(ipc_ipcapi_anon_fd)
+    add_umf_ipc_example(ipc_ipcapi_shm)
 else()
     message(
         STATUS
-            "IPC shared memory example with UMF pool API is supported on Linux only - skipping"
+            "IPC examples with UMF pool API are supported on Linux only - skipping"
     )
 endif()

examples/basic/ipc_shm_ipcapi.sh renamed to examples/basic/ipc_ipcapi_anon_fd.sh

@@ -7,10 +7,12 @@
 
 #!/bin/bash
 
+set -e
+
 # port should be a number from the range <1024, 65535>
 PORT=$(( 1024 + ( $$ % ( 65535 - 1024 ))))
 
-# The ipc_shm_ipcapi example requires using pidfd_getfd(2)
+# The ipc_ipcapi_anon_fd example requires using pidfd_getfd(2)
 # to obtain a duplicate of another process's file descriptor.
 # Permission to duplicate another process's file descriptor
 # is governed by a ptrace access mode PTRACE_MODE_ATTACH_REALCREDS check (see ptrace(2))
@@ -27,11 +29,11 @@ fi
 
 UMF_LOG_VAL="level:debug;flush:debug;output:stderr;pid:yes"
 
-echo "Starting ipc_shm_ipcapi CONSUMER on port $PORT ..."
-UMF_LOG=$UMF_LOG_VAL ./umf_example_ipc_shm_ipcapi_consumer $PORT &
+echo "Starting ipc_ipcapi_anon_fd CONSUMER on port $PORT ..."
+UMF_LOG=$UMF_LOG_VAL ./umf_example_ipc_ipcapi_consumer $PORT &
 
 echo "Waiting 1 sec ..."
 sleep 1
 
-echo "Starting ipc_shm_ipcapi PRODUCER on port $PORT ..."
-UMF_LOG=$UMF_LOG_VAL ./umf_example_ipc_shm_ipcapi_producer $PORT
+echo "Starting ipc_ipcapi_anon_fd PRODUCER on port $PORT ..."
+UMF_LOG=$UMF_LOG_VAL ./umf_example_ipc_ipcapi_producer $PORT

examples/basic/ipc_shm_ipcapi_consumer.c renamed to examples/basic/ipc_ipcapi_consumer.c

@@ -92,7 +92,7 @@ int main(int argc, char *argv[]) {
     int ret = -1;
 
     if (argc < 2) {
-        fprintf(stderr, "usage: %s port\n", argv[0]);
+        fprintf(stderr, "usage: %s <port> [shm_name]\n", argv[0]);
         return -1;
     }
 
@@ -104,6 +104,9 @@ int main(int argc, char *argv[]) {
 
     os_params = umfOsMemoryProviderParamsDefault();
     os_params.visibility = UMF_MEM_MAP_SHARED;
+    if (argc >= 3) {
+        os_params.shm_name = argv[2];
+    }
 
     // create OS memory provider
     umf_result = umfMemoryProviderCreate(umfOsMemoryProviderOps(), &os_params,

examples/basic/ipc_shm_ipcapi_producer.c renamed to examples/basic/ipc_ipcapi_producer.c

@@ -63,7 +63,7 @@ int main(int argc, char *argv[]) {
     int ret = -1;
 
     if (argc < 2) {
-        fprintf(stderr, "Usage: %s port\n", argv[0]);
+        fprintf(stderr, "usage: %s <port> [shm_name]\n", argv[0]);
         return -1;
     }
 
@@ -75,6 +75,9 @@ int main(int argc, char *argv[]) {
 
     os_params = umfOsMemoryProviderParamsDefault();
     os_params.visibility = UMF_MEM_MAP_SHARED;
+    if (argc >= 3) {
+        os_params.shm_name = argv[2];
+    }
 
     // create OS memory provider
     umf_result = umfMemoryProviderCreate(umfOsMemoryProviderOps(), &os_params,

examples/basic/ipc_ipcapi_shm.sh

@@ -0,0 +1,32 @@
+#
+# 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
+#
+
+#!/bin/bash
+
+set -e
+
+SHM_NAME="umf_shm_example"
+
+# port should be a number from the range <1024, 65535>
+PORT=$(( 1024 + ( $$ % ( 65535 - 1024 ))))
+
+UMF_LOG_VAL="level:debug;flush:debug;output:stderr;pid:yes"
+
+# make sure the SHM file does not exist
+rm -f /dev/shm/${SHM_NAME}
+
+echo "Starting ipc_ipcapi_shm CONSUMER on port $PORT ..."
+UMF_LOG=$UMF_LOG_VAL ./umf_example_ipc_ipcapi_consumer $PORT $SHM_NAME &
+
+echo "Waiting 1 sec ..."
+sleep 1
+
+echo "Starting ipc_ipcapi_shm PRODUCER on port $PORT ..."
+UMF_LOG=$UMF_LOG_VAL ./umf_example_ipc_ipcapi_producer $PORT $SHM_NAME
+
+# remove the SHM file
+rm -f /dev/shm/${SHM_NAME}

include/umf/providers/provider_os_memory.h

@@ -69,6 +69,8 @@ typedef struct umf_os_memory_provider_params_t {
     unsigned protection;
     /// memory visibility mode
     umf_memory_visibility_t visibility;
+    /// (optional) a name of a shared memory file (valid only in case of the shared memory visibility)
+    char *shm_name;
 
     // NUMA config
     /// ordered list of numa nodes
@@ -103,10 +105,11 @@ umfOsMemoryProviderParamsDefault(void) {
     umf_os_memory_provider_params_t params = {
         UMF_PROTECTION_READ | UMF_PROTECTION_WRITE, /* protection */
         UMF_MEM_MAP_PRIVATE,                        /* visibility mode */
-        NULL,                                       /* numa_list */
-        0,                                          /* numa_list_len */
-        UMF_NUMA_MODE_DEFAULT,                      /* numa_mode */
-        0                                           /* part_size */
+        NULL, /* (optional) a name of a shared memory file (valid only in case of the shared memory visibility) */
+        NULL, /* numa_list */
+        0,    /* numa_list_len */
+        UMF_NUMA_MODE_DEFAULT, /* numa_mode */
+        0                      /* part_size */
     };
 
     return params;

src/CMakeLists.txt

@@ -103,7 +103,7 @@ set(UMF_PRIVATE_LIBRARY_DIRS ${UMF_PRIVATE_LIBRARY_DIRS}
 
 if(LINUX)
     set(UMF_SOURCES ${UMF_SOURCES} ${UMF_SOURCES_LINUX})
-    set(UMF_LIBS ${UMF_LIBS} dl)
+    set(UMF_LIBS ${UMF_LIBS} dl rt) # librt for shm_open()
 elseif(WINDOWS)
     set(UMF_SOURCES ${UMF_SOURCES} ${UMF_SOURCES_WINDOWS})
 elseif(MACOSX)