include/hwloc/shmem.h

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