1 /*
2 * Copyright © 2013-2018 Inria. All rights reserved.
3 * See COPYING in top-level directory.
4 */
5
6 /** \file
7 * \brief Sharing topologies between processes
8 */
9
10 #ifndef HWLOC_SHMEM_H
11 #define HWLOC_SHMEM_H
12
13 #include <hwloc.h>
14
15 #ifdef __cplusplus
16 extern "C" {
17 #elif 0
18 }
19 #endif
20
21
22 /** \defgroup hwlocality_shmem Sharing topologies between processes
23 *
24 * These functions are used to share a topology between processes by
25 * duplicating it into a file-backed shared-memory buffer.
26 *
27 * The master process must first get the required shared-memory size
28 * for storing this topology with hwloc_shmem_topology_get_length().
29 *
30 * Then it must find a virtual memory area of that size that is available
31 * in all processes (identical virtual addresses in all processes).
32 * On Linux, this can be done by comparing holes found in /proc/\<pid\>/maps
33 * for each process.
34 *
35 * Once found, it must open a destination file for storing the buffer,
36 * and pass it to hwloc_shmem_topology_write() together with
37 * virtual memory address and length obtained above.
38 *
39 * Other processes may then adopt this shared topology by opening the
40 * same file and passing it to hwloc_shmem_topology_adopt() with the
41 * exact same virtual memory address and length.
42 *
43 * @{
44 */
45
46 /** \brief Get the required shared memory length for storing a topology.
47 *
48 * This length (in bytes) must be used in hwloc_shmem_topology_write()
49 * and hwloc_shmem_topology_adopt() later.
50 *
51 * \note Flags \p flags are currently unused, must be 0.
52 */
53 HWLOC_DECLSPEC int hwloc_shmem_topology_get_length(hwloc_topology_t topology,
54 size_t *lengthp,
55 unsigned long flags);
56
57 /** \brief Duplicate a topology to a shared memory file.
58 *
59 * Temporarily map a file in virtual memory and duplicate the
60 * topology \p topology by allocating duplicates in there.
61 *
62 * The segment of the file pointed by descriptor \p fd,
63 * starting at offset \p fileoffset, and of length \p length (in bytes),
64 * will be temporarily mapped at virtual address \p mmap_address
65 * during the duplication.
66 *
67 * The mapping length \p length must have been previously obtained with
68 * hwloc_shmem_topology_get_length()
69 * and the topology must not have been modified in the meantime.
70 *
71 * \note Flags \p flags are currently unused, must be 0.
72 *
73 * \note The object userdata pointer is duplicated but the pointed buffer
74 * is not. However the caller may also allocate it manually in shared memory
75 * to share it as well.
76 *
77 * \return -1 with errno set to EBUSY if the virtual memory mapping defined
78 * by \p mmap_address and \p length isn't available in the process.
79 * \return -1 with errno set to EINVAL if \p fileoffset, \p mmap_address
80 * or \p length aren't page-aligned.
81 */
82 HWLOC_DECLSPEC int hwloc_shmem_topology_write(hwloc_topology_t topology,
83 int fd, hwloc_uint64_t fileoffset,
84 void *mmap_address, size_t length,
85 unsigned long flags);
86
87 /** \brief Adopt a shared memory topology stored in a file.
88 *
89 * Map a file in virtual memory and adopt the topology that was previously
90 * stored there with hwloc_shmem_topology_write().
91 *
92 * The returned adopted topology in \p topologyp can be used just like any
93 * topology. And it must be destroyed with hwloc_topology_destroy() as usual.
94 *
95 * However the topology is read-only.
96 * For instance, it cannot be modified with hwloc_topology_restrict()
97 * and object userdata pointers cannot be changed.
98 *
99 * The segment of the file pointed by descriptor \p fd,
100 * starting at offset \p fileoffset, and of length \p length (in bytes),
101 * will be mapped at virtual address \p mmap_address.
102 *
103 * The file pointed by descriptor \p fd, the offset \p fileoffset,
104 * the requested mapping virtual address \p mmap_address and the length \p length
105 * must be identical to what was given to hwloc_shmem_topology_write() earlier.
106 *
107 * \note Flags \p flags are currently unused, must be 0.
108 *
109 * \note The object userdata pointer should not be used unless the process
110 * that created the shared topology also placed userdata-pointed buffers
111 * in shared memory.
112 *
113 * \note This function takes care of calling hwloc_topology_abi_check().
114 *
115 * \return -1 with errno set to EBUSY if the virtual memory mapping defined
116 * by \p mmap_address and \p length isn't available in the process.
117 *
118 * \return -1 with errno set to EINVAL if \p fileoffset, \p mmap_address
119 * or \p length aren't page-aligned, or do not match what was given to
120 * hwloc_shmem_topology_write() earlier.
121 *
122 * \return -1 with errno set to EINVAL if the layout of the topology structure
123 * is different between the writer process and the adopter process.
124 */
125 HWLOC_DECLSPEC int hwloc_shmem_topology_adopt(hwloc_topology_t *topologyp,
126 int fd, hwloc_uint64_t fileoffset,
127 void *mmap_address, size_t length,
128 unsigned long flags);
129 /** @} */
130
131
132 #ifdef __cplusplus
133 } /* extern "C" */
134 #endif
135
136
137 #endif /* HWLOC_SHMEM_H */