hwlocality_shmem(3) Hardware Locality (hwloc) hwlocality_shmem(3)
NAME
hwlocality_shmem - Sharing topologies between processes
SYNOPSIS
Functions
int hwloc_shmem_topology_get_length (hwloc_topology_t topology, size_t
*lengthp, unsigned long flags)
int hwloc_shmem_topology_write (hwloc_topology_t topology, int fd,
hwloc_uint64_t fileoffset, void *mmap_address, size_t length,
unsigned long flags)
int hwloc_shmem_topology_adopt (hwloc_topology_t *topologyp, int fd,
hwloc_uint64_t fileoffset, void *mmap_address, size_t length,
unsigned long flags)
Detailed Description
These functions are used to share a topology between processes by
duplicating it into a file-backed shared-memory buffer.
The master process must first get the required shared-memory size for
storing this topology with hwloc_shmem_topology_get_length().
Then it must find a virtual memory area of that size that is available
in all processes (identical virtual addresses in all processes). On
Linux, this can be done by comparing holes found in /proc/<pid>/maps
for each process.
Once found, it must open a destination file for storing the buffer, and
pass it to hwloc_shmem_topology_write() together with virtual memory
address and length obtained above.
Other processes may then adopt this shared topology by opening the same
file and passing it to hwloc_shmem_topology_adopt() with the exact same
virtual memory address and length.
Function Documentation
int hwloc_shmem_topology_adopt (hwloc_topology_t * topologyp, int fd,
hwloc_uint64_t fileoffset, void * mmap_address, size_t length, unsigned
long flags)
Adopt a shared memory topology stored in a file. Map a file in virtual
memory and adopt the topology that was previously stored there with
hwloc_shmem_topology_write().
The returned adopted topology in topologyp can be used just like any
topology. And it must be destroyed with hwloc_topology_destroy() as
usual.
However the topology is read-only. For instance, it cannot be modified
with hwloc_topology_restrict() and object userdata pointers cannot be
changed.
The segment of the file pointed by descriptor fd, starting at offset
fileoffset, and of length length (in bytes), will be mapped at virtual
address mmap_address.
The file pointed by descriptor fd, the offset fileoffset, the requested
mapping virtual address mmap_address and the length length must be
identical to what was given to hwloc_shmem_topology_write() earlier.
Note
Flags flags are currently unused, must be 0.
The object userdata pointer should not be used unless the process
that created the shared topology also placed userdata-pointed
buffers in shared memory.
This function takes care of calling hwloc_topology_abi_check().
Returns
-1 with errno set to EBUSY if the virtual memory mapping defined by
mmap_address and length isn't available in the process.
-1 with errno set to EINVAL if fileoffset, mmap_address or length
aren't page-aligned, or do not match what was given to
hwloc_shmem_topology_write() earlier.
-1 with errno set to EINVAL if the layout of the topology structure
is different between the writer process and the adopter process.
int hwloc_shmem_topology_get_length (hwloc_topology_t topology, size_t *
lengthp, unsigned long flags)
Get the required shared memory length for storing a topology. This
length (in bytes) must be used in hwloc_shmem_topology_write() and
hwloc_shmem_topology_adopt() later.
Note
Flags flags are currently unused, must be 0.
int hwloc_shmem_topology_write (hwloc_topology_t topology, int fd,
hwloc_uint64_t fileoffset, void * mmap_address, size_t length, unsigned
long flags)
Duplicate a topology to a shared memory file. Temporarily map a file in
virtual memory and duplicate the topology topology by allocating
duplicates in there.
The segment of the file pointed by descriptor fd, starting at offset
fileoffset, and of length length (in bytes), will be temporarily mapped
at virtual address mmap_address during the duplication.
The mapping length length must have been previously obtained with
hwloc_shmem_topology_get_length() and the topology must not have been
modified in the meantime.
Note
Flags flags are currently unused, must be 0.
The object userdata pointer is duplicated but the pointed buffer is
not. However the caller may also allocate it manually in shared
memory to share it as well.
Returns
-1 with errno set to EBUSY if the virtual memory mapping defined by
mmap_address and length isn't available in the process.
-1 with errno set to EINVAL if fileoffset, mmap_address or length
aren't page-aligned.
Author
Generated automatically by Doxygen for Hardware Locality (hwloc) from
the source code.
Version 2.4.0 Thu Nov 26 2020 hwlocality_shmem(3)
hwloc 2.4.0 - Generated Fri Feb 5 16:30:19 CST 2021