Debian Codegraph @

doc/doxygen-doc/man/man3/hwlocality_shmem.3

raw
1 .TH "hwlocality_shmem" 3 "Version 2.14.0" "Hardware Locality (hwloc)" \" -*- nroff -*-
2 .ad l
3 .nh
4 .SH NAME
5 hwlocality_shmem \- Sharing topologies between processes
6 .SH SYNOPSIS
7 .br
8 .PP
9 .SS "Functions"
10
11 .in +1c
12 .ti -1c
13 .RI "int \fBhwloc_shmem_topology_get_length\fP (\fBhwloc_topology_t\fP topology, size_t *lengthp, unsigned long flags)"
14 .br
15 .ti -1c
16 .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)"
17 .br
18 .ti -1c
19 .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)"
20 .br
21 .in -1c
22 .SH "Detailed Description"
23 .PP
24 These functions are used to share a topology between processes by duplicating it into a file-backed shared-memory buffer\&.
25
26 .PP
27 The master process must first get the required shared-memory size for storing this topology with \fBhwloc_shmem_topology_get_length()\fP\&.
28
29 .PP
30 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\&.
31
32 .PP
33 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\&.
34
35 .PP
36 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\&.
37 .SH "Function Documentation"
38 .PP
39 .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)"
40
41 .PP
42 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\&.
43
44 .PP
45 The returned adopted topology in \fRtopologyp\fP can be used just like any topology\&. And it must be destroyed with \fBhwloc_topology_destroy()\fP as usual\&.
46
47 .PP
48 However the topology is read-only\&. For instance, it cannot be modified with \fBhwloc_topology_restrict()\fP and object userdata pointers cannot be changed\&.
49
50 .PP
51 The segment of the file pointed by descriptor \fRfd\fP, starting at offset \fRfileoffset\fP, and of length \fRlength\fP (in bytes), will be mapped at virtual address \fRmmap_address\fP\&.
52
53 .PP
54 The file pointed by descriptor \fRfd\fP, the offset \fRfileoffset\fP, the requested mapping virtual address \fRmmap_address\fP and the length \fRlength\fP must be identical to what was given to \fBhwloc_shmem_topology_write()\fP earlier\&.
55
56 .PP
57 \fBNote\fP
58 .RS 4
59 Flags \fRflags\fP are currently unused, must be 0\&.
60
61 .PP
62 The object userdata pointer should not be used unless the process that created the shared topology also placed userdata-pointed buffers in shared memory\&.
63
64 .PP
65 This function takes care of calling \fBhwloc_topology_abi_check()\fP\&.
66 .RE
67 .PP
68 \fBReturns\fP
69 .RS 4
70 0 on success\&.
71
72 .PP
73 -1 with errno set to \fREBUSY\fP if the virtual memory mapping defined by \fRmmap_address\fP and \fRlength\fP isn't available in the process\&.
74
75 .PP
76 -1 with errno set to \fREINVAL\fP if \fRfileoffset\fP, \fRmmap_address\fP or \fRlength\fP aren't page-aligned, or do not match what was given to \fBhwloc_shmem_topology_write()\fP earlier\&.
77
78 .PP
79 -1 with errno set to \fREINVAL\fP if the layout of the topology structure is different between the writer process and the adopter process\&.
80 .RE
81 .PP
82
83 .SS "int hwloc_shmem_topology_get_length (\fBhwloc_topology_t\fP topology, size_t * lengthp, unsigned long flags)"
84
85 .PP
86 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\&.
87
88 .PP
89 \fBReturns\fP
90 .RS 4
91 the length, or -1 on error, for instance if flags are invalid\&.
92 .RE
93 .PP
94 \fBNote\fP
95 .RS 4
96 Flags \fRflags\fP are currently unused, must be 0\&.
97 .RE
98 .PP
99
100 .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)"
101
102 .PP
103 Duplicate a topology to a shared memory file\&. Temporarily map a file in virtual memory and duplicate the topology \fRtopology\fP by allocating duplicates in there\&.
104
105 .PP
106 The segment of the file pointed by descriptor \fRfd\fP, starting at offset \fRfileoffset\fP, and of length \fRlength\fP (in bytes), will be temporarily mapped at virtual address \fRmmap_address\fP during the duplication\&.
107
108 .PP
109 The mapping length \fRlength\fP must have been previously obtained with \fBhwloc_shmem_topology_get_length()\fP and the topology must not have been modified in the meantime\&.
110
111 .PP
112 \fBNote\fP
113 .RS 4
114 Flags \fRflags\fP are currently unused, must be 0\&.
115
116 .PP
117 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\&.
118 .RE
119 .PP
120 \fBReturns\fP
121 .RS 4
122 0 on success\&.
123
124 .PP
125 -1 with errno set to \fREBUSY\fP if the virtual memory mapping defined by \fRmmap_address\fP and \fRlength\fP isn't available in the process\&.
126
127 .PP
128 -1 with errno set to \fREINVAL\fP if \fRfileoffset\fP, \fRmmap_address\fP or \fRlength\fP aren't page-aligned\&.
129 .RE
130 .PP
131
132 .SH "Author"
133 .PP
134 Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.