.TH "hwlocality_shmem" 3 "Version 2.10.0rc2" "Hardware Locality (hwloc)" \" -*- nroff -*- .ad l .nh .SH NAME hwlocality_shmem \- Sharing topologies between processes .SH SYNOPSIS .br .PP .SS "Functions" .in +1c .ti -1c .RI "int \fBhwloc_shmem_topology_get_length\fP (\fBhwloc_topology_t\fP topology, size_t *lengthp, unsigned long flags)" .br .ti -1c .RI "int \fBhwloc_shmem_topology_write\fP (\fBhwloc_topology_t\fP topology, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)" .br .ti -1c .RI "int \fBhwloc_shmem_topology_adopt\fP (\fBhwloc_topology_t\fP *topologyp, int fd, hwloc_uint64_t fileoffset, void *mmap_address, size_t length, unsigned long flags)" .br .in -1c .SH "Detailed Description" .PP These functions are used to share a topology between processes by duplicating it into a file-backed shared-memory buffer\&. .PP The master process must first get the required shared-memory size for storing this topology with \fBhwloc_shmem_topology_get_length()\fP\&. .PP 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//maps for each process\&. .PP Once found, it must open a destination file for storing the buffer, and pass it to \fBhwloc_shmem_topology_write()\fP together with virtual memory address and length obtained above\&. .PP Other processes may then adopt this shared topology by opening the same file and passing it to \fBhwloc_shmem_topology_adopt()\fP with the exact same virtual memory address and length\&. .SH "Function Documentation" .PP .SS "int hwloc_shmem_topology_adopt (\fBhwloc_topology_t\fP * topologyp, int fd, hwloc_uint64_t fileoffset, void * mmap_address, size_t length, unsigned long flags)" .PP 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 \fBhwloc_shmem_topology_write()\fP\&. .PP The returned adopted topology in \fCtopologyp\fP can be used just like any topology\&. And it must be destroyed with \fBhwloc_topology_destroy()\fP as usual\&. .PP However the topology is read-only\&. For instance, it cannot be modified with \fBhwloc_topology_restrict()\fP and object userdata pointers cannot be changed\&. .PP The segment of the file pointed by descriptor \fCfd\fP, starting at offset \fCfileoffset\fP, and of length \fClength\fP (in bytes), will be mapped at virtual address \fCmmap_address\fP\&. .PP The file pointed by descriptor \fCfd\fP, the offset \fCfileoffset\fP, the requested mapping virtual address \fCmmap_address\fP and the length \fClength\fP must be identical to what was given to \fBhwloc_shmem_topology_write()\fP earlier\&. .PP \fBNote\fP .RS 4 Flags \fCflags\fP are currently unused, must be 0\&. .PP The object userdata pointer should not be used unless the process that created the shared topology also placed userdata-pointed buffers in shared memory\&. .PP This function takes care of calling \fBhwloc_topology_abi_check()\fP\&. .RE .PP \fBReturns\fP .RS 4 0 on success\&. .PP -1 with errno set to \fCEBUSY\fP if the virtual memory mapping defined by \fCmmap_address\fP and \fClength\fP isn't available in the process\&. .PP -1 with errno set to \fCEINVAL\fP if \fCfileoffset\fP, \fCmmap_address\fP or \fClength\fP aren't page-aligned, or do not match what was given to \fBhwloc_shmem_topology_write()\fP earlier\&. .PP -1 with errno set to \fCEINVAL\fP if the layout of the topology structure is different between the writer process and the adopter process\&. .RE .PP .SS "int hwloc_shmem_topology_get_length (\fBhwloc_topology_t\fP topology, size_t * lengthp, unsigned long flags)" .PP Get the required shared memory length for storing a topology\&. This length (in bytes) must be used in \fBhwloc_shmem_topology_write()\fP and \fBhwloc_shmem_topology_adopt()\fP later\&. .PP \fBReturns\fP .RS 4 the length, or -1 on error, for instance if flags are invalid\&. .RE .PP \fBNote\fP .RS 4 Flags \fCflags\fP are currently unused, must be 0\&. .RE .PP .SS "int hwloc_shmem_topology_write (\fBhwloc_topology_t\fP topology, int fd, hwloc_uint64_t fileoffset, void * mmap_address, size_t length, unsigned long flags)" .PP Duplicate a topology to a shared memory file\&. Temporarily map a file in virtual memory and duplicate the topology \fCtopology\fP by allocating duplicates in there\&. .PP The segment of the file pointed by descriptor \fCfd\fP, starting at offset \fCfileoffset\fP, and of length \fClength\fP (in bytes), will be temporarily mapped at virtual address \fCmmap_address\fP during the duplication\&. .PP The mapping length \fClength\fP must have been previously obtained with \fBhwloc_shmem_topology_get_length()\fP and the topology must not have been modified in the meantime\&. .PP \fBNote\fP .RS 4 Flags \fCflags\fP are currently unused, must be 0\&. .PP 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\&. .RE .PP \fBReturns\fP .RS 4 0 on success\&. .PP -1 with errno set to \fCEBUSY\fP if the virtual memory mapping defined by \fCmmap_address\fP and \fClength\fP isn't available in the process\&. .PP -1 with errno set to \fCEINVAL\fP if \fCfileoffset\fP, \fCmmap_address\fP or \fClength\fP aren't page-aligned\&. .RE .PP .SH "Author" .PP Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.