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
           0 on success.

           -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.

       Returns
           the length, or -1 on error, for instance if flags are invalid.

       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
           0 on success.

           -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.