1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
.TH "hwlocality_shmem" 3 "Version 2.12.0" "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/<pid>/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\&.
|
