include/hwloc/shmem.h

0001 /*
0002  * SPDX-License-Identifier: BSD-3-Clause
0003  * Copyright © 2013-2023 Inria.  All rights reserved.
0004  * See COPYING in top-level directory.
0005  */
0006
0007 /** \file
0008  * \brief Sharing topologies between processes
0009  */
0010
0011 #ifndef HWLOC_SHMEM_H
0012 #define HWLOC_SHMEM_H
0013
0014 #include "hwloc.h"
0015
0016 #ifdef __cplusplus
0017 extern "C" {
0018 #elif 0
0019 }
0020 #endif
0021
0022
0023 /** \defgroup hwlocality_shmem Sharing topologies between processes
0024  *
0025  * These functions are used to share a topology between processes by
0026  * duplicating it into a file-backed shared-memory buffer.
0027  *
0028  * The master process must first get the required shared-memory size
0029  * for storing this topology with hwloc_shmem_topology_get_length().
0030  *
0031  * Then it must find a virtual memory area of that size that is available
0032  * in all processes (identical virtual addresses in all processes).
0033  * On Linux, this can be done by comparing holes found in /proc/\<pid\>/maps
0034  * for each process.
0035  *
0036  * Once found, it must open a destination file for storing the buffer,
0037  * and pass it to hwloc_shmem_topology_write() together with
0038  * virtual memory address and length obtained above.
0039  *
0040  * Other processes may then adopt this shared topology by opening the
0041  * same file and passing it to hwloc_shmem_topology_adopt() with the
0042  * exact same virtual memory address and length.
0043  *
0044  * @{
0045  */
0046
0047 /** \brief Get the required shared memory length for storing a topology.
0048  *
0049  * This length (in bytes) must be used in hwloc_shmem_topology_write()
0050  * and hwloc_shmem_topology_adopt() later.
0051  *
0052  * \return the length, or -1 on error, for instance if flags are invalid.
0053  *
0054  * \note Flags \p flags are currently unused, must be 0.
0055  */
0056 HWLOC_DECLSPEC int hwloc_shmem_topology_get_length(hwloc_topology_t topology,
0057                            size_t *lengthp,
0058                            unsigned long flags);
0059
0060 /** \brief Duplicate a topology to a shared memory file.
0061  *
0062  * Temporarily map a file in virtual memory and duplicate the
0063  * topology \p topology by allocating duplicates in there.
0064  *
0065  * The segment of the file pointed by descriptor \p fd,
0066  * starting at offset \p fileoffset, and of length \p length (in bytes),
0067  * will be temporarily mapped at virtual address \p mmap_address
0068  * during the duplication.
0069  *
0070  * The mapping length \p length must have been previously obtained with
0071  * hwloc_shmem_topology_get_length()
0072  * and the topology must not have been modified in the meantime.
0073  *
0074  * \note Flags \p flags are currently unused, must be 0.
0075  *
0076  * \note The object userdata pointer is duplicated but the pointed buffer
0077  * is not. However the caller may also allocate it manually in shared memory
0078  * to share it as well.
0079  *
0080  * \return 0 on success.
0081  * \return -1 with errno set to \c EBUSY if the virtual memory mapping defined
0082  * by \p mmap_address and \p length isn't available in the process.
0083  * \return -1 with errno set to \c EINVAL if \p fileoffset, \p mmap_address
0084  * or \p length aren't page-aligned.
0085  */
0086 HWLOC_DECLSPEC int hwloc_shmem_topology_write(hwloc_topology_t topology,
0087                           int fd, hwloc_uint64_t fileoffset,
0088                           void *mmap_address, size_t length,
0089                           unsigned long flags);
0090
0091 /** \brief Adopt a shared memory topology stored in a file.
0092  *
0093  * Map a file in virtual memory and adopt the topology that was previously
0094  * stored there with hwloc_shmem_topology_write().
0095  *
0096  * The returned adopted topology in \p topologyp can be used just like any
0097  * topology. And it must be destroyed with hwloc_topology_destroy() as usual.
0098  *
0099  * However the topology is read-only.
0100  * For instance, it cannot be modified with hwloc_topology_restrict()
0101  * and object userdata pointers cannot be changed.
0102  *
0103  * The segment of the file pointed by descriptor \p fd,
0104  * starting at offset \p fileoffset, and of length \p length (in bytes),
0105  * will be mapped at virtual address \p mmap_address.
0106  *
0107  * The file pointed by descriptor \p fd, the offset \p fileoffset,
0108  * the requested mapping virtual address \p mmap_address and the length \p length
0109  * must be identical to what was given to hwloc_shmem_topology_write() earlier.
0110  *
0111  * \note Flags \p flags are currently unused, must be 0.
0112  *
0113  * \note The object userdata pointer should not be used unless the process
0114  * that created the shared topology also placed userdata-pointed buffers
0115  * in shared memory.
0116  *
0117  * \note This function takes care of calling hwloc_topology_abi_check().
0118  *
0119  * \return 0 on success.
0120  *
0121  * \return -1 with errno set to \c EBUSY if the virtual memory mapping defined
0122  * by \p mmap_address and \p length isn't available in the process.
0123  *
0124  * \return -1 with errno set to \c EINVAL if \p fileoffset, \p mmap_address
0125  * or \p length aren't page-aligned, or do not match what was given to
0126  * hwloc_shmem_topology_write() earlier.
0127  *
0128  * \return -1 with errno set to \c EINVAL if the layout of the topology structure
0129  * is different between the writer process and the adopter process.
0130  */
0131 HWLOC_DECLSPEC int hwloc_shmem_topology_adopt(hwloc_topology_t *topologyp,
0132                           int fd, hwloc_uint64_t fileoffset,
0133                           void *mmap_address, size_t length,
0134                           unsigned long flags);
0135 /** @} */
0136
0137
0138 #ifdef __cplusplus
0139 } /* extern "C" */
0140 #endif
0141
0142
0143 #endif /* HWLOC_SHMEM_H */