Debian Codegraph @

doc/doxygen-doc/html/a00174.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2 <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
3 <head>
4 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
5 <meta http-equiv="X-UA-Compatible" content="IE=11"/>
6 <meta name="generator" content="Doxygen 1.15.0"/>
7 <meta name="viewport" content="width=device-width, initial-scale=1"/>
8 <title>Hardware Locality (hwloc): Memory binding</title>
9 <link href="tabs.css" rel="stylesheet" type="text/css"/>
10 <script type="text/javascript" src="jquery.js"></script>
11 <script type="text/javascript" src="dynsections.js"></script>
12 <script type="text/javascript" src="clipboard.js"></script>
13 <link href="doxygen.css" rel="stylesheet" type="text/css" />
14 </head>
15 <body>
16 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
17 <div id="titlearea">
18 <table cellspacing="0" cellpadding="0">
19 <tbody>
20 <tr id="projectrow">
21 <td id="projectalign">
22 <div id="projectname">Hardware Locality (hwloc)<span id="projectnumber">&#160;2.14.0</span>
23 </div>
24 </td>
25 </tr>
26 </tbody>
27 </table>
28 </div>
29 <!-- end header part -->
30 <!-- Generated by Doxygen 1.15.0 -->
31 <script type="text/javascript">
32 $(function() { codefold.init(); });
33 </script>
34 <script type="text/javascript" src="menudata.js"></script>
35 <script type="text/javascript" src="menu.js"></script>
36 <script type="text/javascript">
37 $(function() {
38 initMenu('',false,false,'search.php','Search',false);
39 });
40 </script>
41 <div id="main-nav"></div>
42 </div><!-- top -->
43 <div id="doc-content">
44 <div class="header">
45 <div class="summary">
46 <a href="#enum-members">Enumerations</a> &#124;
47 <a href="#func-members">Functions</a> </div>
48 <div class="headertitle"><div class="title">Memory binding </div></div>
49 </div><!--header-->
50 <div class="contents">
51 <table class="memberdecls">
52 <tr class="heading"><td colspan="2"><h2 id="header-enum-members" class="groupheader"><a id="enum-members" name="enum-members"></a>
53 Enumerations</h2></td></tr>
54 <tr class="memitem:gac9764f79505775d06407b40f5e4661e8" id="r_gac9764f79505775d06407b40f5e4661e8"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a> { <br />
55 &#160;&#160;<a class="el" href="#ggac9764f79505775d06407b40f5e4661e8a18675bb80ebc1bce5b652e9de8f3998c">HWLOC_MEMBIND_DEFAULT</a>
56 , <a class="el" href="#ggac9764f79505775d06407b40f5e4661e8a979c7aa78dd32780858f30f47a72cca0">HWLOC_MEMBIND_FIRSTTOUCH</a>
57 , <a class="el" href="#ggac9764f79505775d06407b40f5e4661e8ad811fa4b2a6002c4d63695a408ffde2c">HWLOC_MEMBIND_BIND</a>
58 , <a class="el" href="#ggac9764f79505775d06407b40f5e4661e8ae370075e5af016d42310f87ea5af236b">HWLOC_MEMBIND_INTERLEAVE</a>
59 , <br />
60 &#160;&#160;<a class="el" href="#ggac9764f79505775d06407b40f5e4661e8aa091c40c9557b69a26b69a0e8b84dafe">HWLOC_MEMBIND_WEIGHTED_INTERLEAVE</a>
61 , <a class="el" href="#ggac9764f79505775d06407b40f5e4661e8aecdd4164d647708fbb51a00d98dbb138">HWLOC_MEMBIND_NEXTTOUCH</a>
62 , <a class="el" href="#ggac9764f79505775d06407b40f5e4661e8a3185bd869b67817fb2bd5164bf360402">HWLOC_MEMBIND_MIXED</a>
63 <br />
64 }</td></tr>
65 <tr class="memitem:gab00475fd98815bf4fb9aaf752030e7d2" id="r_gab00475fd98815bf4fb9aaf752030e7d2"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#gab00475fd98815bf4fb9aaf752030e7d2">hwloc_membind_flags_t</a> { <br />
66 &#160;&#160;<a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1b1b74aef138f64aff214a8cbdfe8eb4">HWLOC_MEMBIND_PROCESS</a>
67 , <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1dc7dd5cdcd5796893a325a524555298">HWLOC_MEMBIND_THREAD</a>
68 , <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a0335311a0ee04166df2888d52b4a42c6">HWLOC_MEMBIND_STRICT</a>
69 , <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2aa6e49e54f52827cb143cc869cfd748af">HWLOC_MEMBIND_MIGRATE</a>
70 , <br />
71 &#160;&#160;<a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2aad6b9eaf2ee324ca58dc8f58094b9997">HWLOC_MEMBIND_NOCPUBIND</a>
72 , <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256">HWLOC_MEMBIND_BYNODESET</a>
73 <br />
74 }</td></tr>
75 </table><table class="memberdecls">
76 <tr class="heading"><td colspan="2"><h2 id="header-func-members" class="groupheader"><a id="func-members" name="func-members"></a>
77 Functions</h2></td></tr>
78 <tr class="memitem:ga020951efa0ce3862bd4faec295501a7f" id="r_ga020951efa0ce3862bd4faec295501a7f"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga020951efa0ce3862bd4faec295501a7f">hwloc_set_membind</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="a00188.html#gae991a108af01d408be2776c5b2c467b2">hwloc_const_bitmap_t</a> set, <a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a> policy, int flags)</td></tr>
79 <tr class="memitem:gae21f0a1a884929c784bebf070252aa56" id="r_gae21f0a1a884929c784bebf070252aa56"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#gae21f0a1a884929c784bebf070252aa56">hwloc_get_membind</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="a00188.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a> set, <a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a> *policy, int flags)</td></tr>
80 <tr class="memitem:gabc91ff16f7e41047924e3a4ae6d9da7e" id="r_gabc91ff16f7e41047924e3a4ae6d9da7e"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#gabc91ff16f7e41047924e3a4ae6d9da7e">hwloc_set_proc_membind</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, hwloc_pid_t pid, <a class="el" href="a00188.html#gae991a108af01d408be2776c5b2c467b2">hwloc_const_bitmap_t</a> set, <a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a> policy, int flags)</td></tr>
81 <tr class="memitem:ga1730ceb18ec6ee3b7bd3d0db81f07dc8" id="r_ga1730ceb18ec6ee3b7bd3d0db81f07dc8"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga1730ceb18ec6ee3b7bd3d0db81f07dc8">hwloc_get_proc_membind</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, hwloc_pid_t pid, <a class="el" href="a00188.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a> set, <a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a> *policy, int flags)</td></tr>
82 <tr class="memitem:gaf881faefe20701229f07dd7dbd0125ed" id="r_gaf881faefe20701229f07dd7dbd0125ed"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#gaf881faefe20701229f07dd7dbd0125ed">hwloc_set_area_membind</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, const void *addr, size_t len, <a class="el" href="a00188.html#gae991a108af01d408be2776c5b2c467b2">hwloc_const_bitmap_t</a> set, <a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a> policy, int flags)</td></tr>
83 <tr class="memitem:gaa87e0a6946ff145914fdf0b1c60567f8" id="r_gaa87e0a6946ff145914fdf0b1c60567f8"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#gaa87e0a6946ff145914fdf0b1c60567f8">hwloc_get_area_membind</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, const void *addr, size_t len, <a class="el" href="a00188.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a> set, <a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a> *policy, int flags)</td></tr>
84 <tr class="memitem:ga537c7508a4e2d1db05673ec5be6e805c" id="r_ga537c7508a4e2d1db05673ec5be6e805c"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga537c7508a4e2d1db05673ec5be6e805c">hwloc_get_area_memlocation</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, const void *addr, size_t len, <a class="el" href="a00188.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a> set, int flags)</td></tr>
85 <tr class="memitem:ga95856d8f13357f247d5fce142d443ae3" id="r_ga95856d8f13357f247d5fce142d443ae3"><td class="memItemLeft" align="right" valign="top">void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga95856d8f13357f247d5fce142d443ae3">hwloc_alloc</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, size_t len)</td></tr>
86 <tr class="memitem:gadf87089ef533db40460ccc24b5bc0d65" id="r_gadf87089ef533db40460ccc24b5bc0d65"><td class="memItemLeft" align="right" valign="top">void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#gadf87089ef533db40460ccc24b5bc0d65">hwloc_alloc_membind</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, size_t len, <a class="el" href="a00188.html#gae991a108af01d408be2776c5b2c467b2">hwloc_const_bitmap_t</a> set, <a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a> policy, int flags)</td></tr>
87 <tr class="memitem:gad0193dadaa1aebd85fe7bba69c552b4e" id="r_gad0193dadaa1aebd85fe7bba69c552b4e"><td class="memItemLeft" align="right" valign="top">void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#gad0193dadaa1aebd85fe7bba69c552b4e">hwloc_alloc_membind_policy</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, size_t len, <a class="el" href="a00188.html#gae991a108af01d408be2776c5b2c467b2">hwloc_const_bitmap_t</a> set, <a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a> policy, int flags)</td></tr>
88 <tr class="memitem:ga32dbd4f54e9e4a7179f2dde37ffe6ad7" id="r_ga32dbd4f54e9e4a7179f2dde37ffe6ad7"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga32dbd4f54e9e4a7179f2dde37ffe6ad7">hwloc_free</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, void *addr, size_t len)</td></tr>
89 </table>
90 <a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2>
91 <p>Memory binding can be done three ways:</p>
92 <ul>
93 <li>explicit memory allocation thanks to <a class="el" href="#gadf87089ef533db40460ccc24b5bc0d65" title="Allocate some memory on NUMA memory nodes specified by set.">hwloc_alloc_membind()</a> and friends: the binding will have effect on the memory allocated by these functions.</li>
94 <li>implicit memory binding through binding policy: <a class="el" href="#ga020951efa0ce3862bd4faec295501a7f" title="Set the default memory binding policy of the current process or thread to prefer the NUMA node(s) spe...">hwloc_set_membind()</a> and friends only define the current policy of the process, which will be applied to the subsequent calls to malloc() and friends.</li>
95 <li>migration of existing memory ranges, thanks to <a class="el" href="#gaf881faefe20701229f07dd7dbd0125ed" title="Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) specified by set.">hwloc_set_area_membind()</a> and friends, which move already-allocated data.</li>
96 </ul>
97 <p>Not all operating systems support all three ways. <a class="el" href="a00176.html#gac0927e93a9b962143be08a48bbff2e19" title="Retrieve the topology support.">hwloc_topology_get_support()</a> may be used to query about the actual memory binding support in the currently used operating system.</p>
98 <p>When the requested binding operation is not available and the <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a0335311a0ee04166df2888d52b4a42c6">HWLOC_MEMBIND_STRICT</a> flag was passed, the function returns -1. <code class="param">errno</code> will be set to <code>ENOSYS</code> when the system does support the specified action or policy (e.g., some systems only allow binding memory on a per-thread basis, whereas other systems only allow binding memory for all threads in a process). <code class="param">errno</code> will be set to <code>EXDEV</code> when the requested set can not be enforced (e.g., some systems only allow binding memory to a single NUMA node).</p>
99 <p>If <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a0335311a0ee04166df2888d52b4a42c6">HWLOC_MEMBIND_STRICT</a> was not passed, the function may fail as well, or the operating system may use a slightly different operation (with side-effects, smaller binding set, etc.) when the requested operation is not exactly supported.</p>
100 <p>The most portable form that should be preferred over the others whenever possible is as follows. It allocates some memory hopefully bound to the specified set. To do so, hwloc will possibly have to change the current memory binding policy in order to actually get the memory bound, if the OS does not provide any other way to simply allocate bound memory without changing the policy for all allocations. That is the difference with <a class="el" href="#gadf87089ef533db40460ccc24b5bc0d65" title="Allocate some memory on NUMA memory nodes specified by set.">hwloc_alloc_membind()</a>, which will never change the current memory binding policy.</p>
101 <div class="fragment"><div class="line"><a class="code hl_function" href="#gad0193dadaa1aebd85fe7bba69c552b4e">hwloc_alloc_membind_policy</a>(topology, size, set,</div>
102 <div class="line"> <a class="code hl_enumvalue" href="#ggac9764f79505775d06407b40f5e4661e8ad811fa4b2a6002c4d63695a408ffde2c">HWLOC_MEMBIND_BIND</a>, 0);</div>
103 <div class="ttc" id="aa00174_html_gad0193dadaa1aebd85fe7bba69c552b4e"><div class="ttname"><a href="#gad0193dadaa1aebd85fe7bba69c552b4e">hwloc_alloc_membind_policy</a></div><div class="ttdeci">void * hwloc_alloc_membind_policy(hwloc_topology_t topology, size_t len, hwloc_const_bitmap_t set, hwloc_membind_policy_t policy, int flags)</div><div class="ttdoc">Allocate some memory on NUMA memory nodes specified by set.</div></div>
104 <div class="ttc" id="aa00174_html_ggac9764f79505775d06407b40f5e4661e8ad811fa4b2a6002c4d63695a408ffde2c"><div class="ttname"><a href="#ggac9764f79505775d06407b40f5e4661e8ad811fa4b2a6002c4d63695a408ffde2c">HWLOC_MEMBIND_BIND</a></div><div class="ttdeci">@ HWLOC_MEMBIND_BIND</div><div class="ttdoc">Allocate memory on the specified nodes.</div><div class="ttdef"><b>Definition</b> hwloc.h:1542</div></div>
105 </div><!-- fragment --><p>Each hwloc memory binding function takes a bitmap argument that is a CPU set by default, or a NUMA memory node set if the flag <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256" title="Consider the bitmap argument as a nodeset.">HWLOC_MEMBIND_BYNODESET</a> is specified. See <a class="el" href="a00166.html">Object Sets (hwloc_cpuset_t and hwloc_nodeset_t)</a> and <a class="el" href="a00188.html">The bitmap API</a> for a discussion of CPU sets and NUMA memory node sets. It is also possible to convert between CPU set and node set using <a class="el" href="a00186.html#gaa06b612bcf2babdccfe0071f470ec9b7" title="Convert a CPU set into a NUMA node set.">hwloc_cpuset_to_nodeset()</a> or <a class="el" href="a00186.html#gae8180d79a731d610836f2a4789e00db1" title="Convert a NUMA node set into a CPU set.">hwloc_cpuset_from_nodeset()</a>.</p>
106 <p>Memory binding by CPU set cannot work for CPU-less NUMA memory nodes. Binding by nodeset should therefore be preferred whenever possible.</p>
107 <dl class="section see"><dt>See also</dt><dd>Some example codes are available under doc/examples/ in the source tree.</dd></dl>
108 <dl class="section note"><dt>Note</dt><dd>On some operating systems, memory binding affects the CPU binding; see <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2aad6b9eaf2ee324ca58dc8f58094b9997" title="Avoid any effect on CPU binding.">HWLOC_MEMBIND_NOCPUBIND</a> </dd></dl>
109 <a name="doc-enum-members" id="doc-enum-members"></a><h2 id="header-doc-enum-members" class="groupheader">Enumeration Type Documentation</h2>
110 <a id="gab00475fd98815bf4fb9aaf752030e7d2" name="gab00475fd98815bf4fb9aaf752030e7d2"></a>
111 <h2 class="memtitle"><span class="permalink"><a href="#gab00475fd98815bf4fb9aaf752030e7d2">&#9670;&#160;</a></span>hwloc_membind_flags_t</h2>
112
113 <div class="memitem">
114 <div class="memproto">
115 <table class="memname">
116 <tr>
117 <td class="memname">enum <a class="el" href="#gab00475fd98815bf4fb9aaf752030e7d2">hwloc_membind_flags_t</a></td>
118 </tr>
119 </table>
120 </div><div class="memdoc">
121
122 <p>Memory binding flags. </p>
123 <p>These flags can be used to refine the binding policy. All flags can be logically OR'ed together with the exception of <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1b1b74aef138f64aff214a8cbdfe8eb4" title="Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually e...">HWLOC_MEMBIND_PROCESS</a> and <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1dc7dd5cdcd5796893a325a524555298" title="Set policy for a specific thread of the current process. This flag is mutually exclusive with HWLOC_M...">HWLOC_MEMBIND_THREAD</a>; these two flags are mutually exclusive.</p>
124 <p>Not all systems support all kinds of binding. <a class="el" href="a00176.html#gac0927e93a9b962143be08a48bbff2e19" title="Retrieve the topology support.">hwloc_topology_get_support()</a> may be used to query about the actual memory binding support in the currently used operating system. See the "Detailed Description" section of <a class="el" href="a00174.html">Memory binding</a> for a description of errors that can occur. </p>
125 <table class="fieldtable">
126 <tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="ggab00475fd98815bf4fb9aaf752030e7d2a1b1b74aef138f64aff214a8cbdfe8eb4" name="ggab00475fd98815bf4fb9aaf752030e7d2a1b1b74aef138f64aff214a8cbdfe8eb4"></a>HWLOC_MEMBIND_PROCESS&#160;</td><td class="fielddoc"><p>Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually exclusive with <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1dc7dd5cdcd5796893a325a524555298" title="Set policy for a specific thread of the current process. This flag is mutually exclusive with HWLOC_M...">HWLOC_MEMBIND_THREAD</a>. </p>
127 </td></tr>
128 <tr><td class="fieldname"><a id="ggab00475fd98815bf4fb9aaf752030e7d2a1dc7dd5cdcd5796893a325a524555298" name="ggab00475fd98815bf4fb9aaf752030e7d2a1dc7dd5cdcd5796893a325a524555298"></a>HWLOC_MEMBIND_THREAD&#160;</td><td class="fielddoc"><p>Set policy for a specific thread of the current process. This flag is mutually exclusive with <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1b1b74aef138f64aff214a8cbdfe8eb4" title="Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually e...">HWLOC_MEMBIND_PROCESS</a>. </p>
129 </td></tr>
130 <tr><td class="fieldname"><a id="ggab00475fd98815bf4fb9aaf752030e7d2a0335311a0ee04166df2888d52b4a42c6" name="ggab00475fd98815bf4fb9aaf752030e7d2a0335311a0ee04166df2888d52b4a42c6"></a>HWLOC_MEMBIND_STRICT&#160;</td><td class="fielddoc"><p>Request strict binding from the OS. The function will fail if the binding can not be guaranteed / completely enforced.</p>
131 <p>This flag has slightly different meanings depending on which function it is used with. </p>
132 </td></tr>
133 <tr><td class="fieldname"><a id="ggab00475fd98815bf4fb9aaf752030e7d2aa6e49e54f52827cb143cc869cfd748af" name="ggab00475fd98815bf4fb9aaf752030e7d2aa6e49e54f52827cb143cc869cfd748af"></a>HWLOC_MEMBIND_MIGRATE&#160;</td><td class="fielddoc"><p>Migrate existing allocated memory. If the memory cannot be migrated and the <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a0335311a0ee04166df2888d52b4a42c6">HWLOC_MEMBIND_STRICT</a> flag is passed, an error will be returned. </p>
134 </td></tr>
135 <tr><td class="fieldname"><a id="ggab00475fd98815bf4fb9aaf752030e7d2aad6b9eaf2ee324ca58dc8f58094b9997" name="ggab00475fd98815bf4fb9aaf752030e7d2aad6b9eaf2ee324ca58dc8f58094b9997"></a>HWLOC_MEMBIND_NOCPUBIND&#160;</td><td class="fielddoc"><p>Avoid any effect on CPU binding. </p>
136 <p>On some operating systems, some underlying memory binding functions also bind the application to the corresponding CPU(s). Using this flag will cause hwloc to avoid using OS functions that could potentially affect CPU bindings. Note, however, that using NOCPUBIND may reduce hwloc's overall memory binding support. Specifically: some of hwloc's memory binding functions may fail with errno set to <code>ENOSYS</code> when used with NOCPUBIND. </p>
137 </td></tr>
138 <tr><td class="fieldname"><a id="ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256" name="ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256"></a>HWLOC_MEMBIND_BYNODESET&#160;</td><td class="fielddoc"><p>Consider the bitmap argument as a nodeset. </p>
139 <p>The bitmap argument is considered a nodeset if this flag is given, or a cpuset otherwise by default.</p>
140 <p>Memory binding by CPU set cannot work for CPU-less NUMA memory nodes. Binding by nodeset should therefore be preferred whenever possible. </p>
141 </td></tr>
142 </table>
143
144 </div>
145 </div>
146 <a id="gac9764f79505775d06407b40f5e4661e8" name="gac9764f79505775d06407b40f5e4661e8"></a>
147 <h2 class="memtitle"><span class="permalink"><a href="#gac9764f79505775d06407b40f5e4661e8">&#9670;&#160;</a></span>hwloc_membind_policy_t</h2>
148
149 <div class="memitem">
150 <div class="memproto">
151 <table class="memname">
152 <tr>
153 <td class="memname">enum <a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a></td>
154 </tr>
155 </table>
156 </div><div class="memdoc">
157
158 <p>Memory binding policy. </p>
159 <p>These constants can be used to choose the binding policy. Only one policy can be used at a time (i.e., the values cannot be OR'ed together).</p>
160 <p>Not all systems support all kinds of binding. <a class="el" href="a00176.html#gac0927e93a9b962143be08a48bbff2e19" title="Retrieve the topology support.">hwloc_topology_get_support()</a> may be used to query about the actual memory binding policy support in the currently used operating system. See the "Detailed Description" section of <a class="el" href="a00174.html">Memory binding</a> for a description of errors that can occur. </p>
161 <table class="fieldtable">
162 <tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="ggac9764f79505775d06407b40f5e4661e8a18675bb80ebc1bce5b652e9de8f3998c" name="ggac9764f79505775d06407b40f5e4661e8a18675bb80ebc1bce5b652e9de8f3998c"></a>HWLOC_MEMBIND_DEFAULT&#160;</td><td class="fielddoc"><p>Reset the memory allocation policy to the system default. Depending on the operating system, this may correspond to <a class="el" href="#ggac9764f79505775d06407b40f5e4661e8a979c7aa78dd32780858f30f47a72cca0" title="Allocate each memory page individually on the local NUMA node of the thread that touches it.">HWLOC_MEMBIND_FIRSTTOUCH</a> (Linux, FreeBSD), or <a class="el" href="#ggac9764f79505775d06407b40f5e4661e8ad811fa4b2a6002c4d63695a408ffde2c" title="Allocate memory on the specified nodes.">HWLOC_MEMBIND_BIND</a> (AIX, HP-UX, Solaris, Windows). This policy is never returned by get membind functions. The nodeset argument is ignored. </p>
163 </td></tr>
164 <tr><td class="fieldname"><a id="ggac9764f79505775d06407b40f5e4661e8a979c7aa78dd32780858f30f47a72cca0" name="ggac9764f79505775d06407b40f5e4661e8a979c7aa78dd32780858f30f47a72cca0"></a>HWLOC_MEMBIND_FIRSTTOUCH&#160;</td><td class="fielddoc"><p>Allocate each memory page individually on the local NUMA node of the thread that touches it. </p>
165 <p>The given nodeset should usually be <a class="el" href="a00185.html#ga3fd37303e99ace8b0d0ea03f95f8c514" title="Get topology node set.">hwloc_topology_get_topology_nodeset()</a> so that the touching thread may run and allocate on any node in the system.</p>
166 <p>On AIX, if the nodeset is smaller, pages are allocated locally (if the local node is in the nodeset) or from a random non-local node (otherwise). </p>
167 </td></tr>
168 <tr><td class="fieldname"><a id="ggac9764f79505775d06407b40f5e4661e8ad811fa4b2a6002c4d63695a408ffde2c" name="ggac9764f79505775d06407b40f5e4661e8ad811fa4b2a6002c4d63695a408ffde2c"></a>HWLOC_MEMBIND_BIND&#160;</td><td class="fielddoc"><p>Allocate memory on the specified nodes. </p>
169 <p>The actual behavior may slightly vary between operating systems, especially when (some of) the requested nodes are full. On Linux, by default, the MPOL_PREFERRED_MANY (or MPOL_PREFERRED) policy is used. However, if the hwloc strict flag is also given, the Linux MPOL_BIND policy is rather used. </p>
170 </td></tr>
171 <tr><td class="fieldname"><a id="ggac9764f79505775d06407b40f5e4661e8ae370075e5af016d42310f87ea5af236b" name="ggac9764f79505775d06407b40f5e4661e8ae370075e5af016d42310f87ea5af236b"></a>HWLOC_MEMBIND_INTERLEAVE&#160;</td><td class="fielddoc"><p>Allocate memory on the given nodes in an interleaved / round-robin manner. The precise layout of the memory across multiple NUMA nodes is OS/system specific. Interleaving can be useful when threads distributed across the specified NUMA nodes will all be accessing the whole memory range concurrently, since the interleave will then balance the memory references. </p>
172 </td></tr>
173 <tr><td class="fieldname"><a id="ggac9764f79505775d06407b40f5e4661e8aa091c40c9557b69a26b69a0e8b84dafe" name="ggac9764f79505775d06407b40f5e4661e8aa091c40c9557b69a26b69a0e8b84dafe"></a>HWLOC_MEMBIND_WEIGHTED_INTERLEAVE&#160;</td><td class="fielddoc"><p>Allocate memory on the given nodes in an interleaved / weighted manner. The precise layout of the memory across multiple NUMA nodes is OS/system specific. Weighted interleaving can be useful when threads distributed across the specified NUMA nodes with different bandwidth capabilities will all be accessing the whole memory range concurrently, since the interleave will then balance the memory references. </p>
174 </td></tr>
175 <tr><td class="fieldname"><a id="ggac9764f79505775d06407b40f5e4661e8aecdd4164d647708fbb51a00d98dbb138" name="ggac9764f79505775d06407b40f5e4661e8aecdd4164d647708fbb51a00d98dbb138"></a>HWLOC_MEMBIND_NEXTTOUCH&#160;</td><td class="fielddoc"><p>For each page bound with this policy, by next time it is touched (and next time only), it is moved from its current location to the local NUMA node of the thread where the memory reference occurred (if it needs to be moved at all). </p>
176 </td></tr>
177 <tr><td class="fieldname"><a id="ggac9764f79505775d06407b40f5e4661e8a3185bd869b67817fb2bd5164bf360402" name="ggac9764f79505775d06407b40f5e4661e8a3185bd869b67817fb2bd5164bf360402"></a>HWLOC_MEMBIND_MIXED&#160;</td><td class="fielddoc"><p>Returned by get_membind() functions when multiple threads or parts of a memory area have differing memory binding policies. Also returned when binding is unknown because binding hooks are empty when the topology is loaded from XML without HWLOC_THISSYSTEM=1, etc. </p>
178 </td></tr>
179 </table>
180
181 </div>
182 </div>
183 <a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2>
184 <a id="ga95856d8f13357f247d5fce142d443ae3" name="ga95856d8f13357f247d5fce142d443ae3"></a>
185 <h2 class="memtitle"><span class="permalink"><a href="#ga95856d8f13357f247d5fce142d443ae3">&#9670;&#160;</a></span>hwloc_alloc()</h2>
186
187 <div class="memitem">
188 <div class="memproto">
189 <table class="memname">
190 <tr>
191 <td class="memname">void * hwloc_alloc </td>
192 <td>(</td>
193 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
194 </tr>
195 <tr>
196 <td class="paramkey"></td>
197 <td></td>
198 <td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>len</em></span>&#160;)</td>
199 </tr>
200 </table>
201 </div><div class="memdoc">
202
203 <p>Allocate some memory. </p>
204 <p>This is equivalent to malloc(), except that it tries to allocate page-aligned memory from the OS.</p>
205 <dl class="section return"><dt>Returns</dt><dd>a pointer to the allocated area, or <code>NULL</code> on error.</dd></dl>
206 <dl class="section note"><dt>Note</dt><dd>The allocated memory should be freed with <a class="el" href="#ga32dbd4f54e9e4a7179f2dde37ffe6ad7" title="Free memory that was previously allocated by hwloc_alloc() or hwloc_alloc_membind().">hwloc_free()</a>. </dd></dl>
207
208 </div>
209 </div>
210 <a id="gadf87089ef533db40460ccc24b5bc0d65" name="gadf87089ef533db40460ccc24b5bc0d65"></a>
211 <h2 class="memtitle"><span class="permalink"><a href="#gadf87089ef533db40460ccc24b5bc0d65">&#9670;&#160;</a></span>hwloc_alloc_membind()</h2>
212
213 <div class="memitem">
214 <div class="memproto">
215 <table class="memname">
216 <tr>
217 <td class="memname">void * hwloc_alloc_membind </td>
218 <td>(</td>
219 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
220 </tr>
221 <tr>
222 <td class="paramkey"></td>
223 <td></td>
224 <td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>len</em></span>, </td>
225 </tr>
226 <tr>
227 <td class="paramkey"></td>
228 <td></td>
229 <td class="paramtype"><a class="el" href="a00188.html#gae991a108af01d408be2776c5b2c467b2">hwloc_const_bitmap_t</a></td> <td class="paramname"><span class="paramname"><em>set</em></span>, </td>
230 </tr>
231 <tr>
232 <td class="paramkey"></td>
233 <td></td>
234 <td class="paramtype"><a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a></td> <td class="paramname"><span class="paramname"><em>policy</em></span>, </td>
235 </tr>
236 <tr>
237 <td class="paramkey"></td>
238 <td></td>
239 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
240 </tr>
241 </table>
242 </div><div class="memdoc">
243
244 <p>Allocate some memory on NUMA memory nodes specified by <code class="param">set</code>. </p>
245 <dl class="section return"><dt>Returns</dt><dd>a pointer to the allocated area. </dd>
246 <dd>
247 NULL with errno set to <code>ENOSYS</code> if the action is not supported and <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a0335311a0ee04166df2888d52b4a42c6">HWLOC_MEMBIND_STRICT</a> is given. </dd>
248 <dd>
249 NULL with errno set to <code>EXDEV</code> if the binding cannot be enforced and <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a0335311a0ee04166df2888d52b4a42c6">HWLOC_MEMBIND_STRICT</a> is given. </dd>
250 <dd>
251 NULL with errno set to <code>ENOMEM</code> if the memory allocation failed even before trying to bind.</dd></dl>
252 <p>If <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256" title="Consider the bitmap argument as a nodeset.">HWLOC_MEMBIND_BYNODESET</a> is specified, set is considered a nodeset. Otherwise it's a cpuset.</p>
253 <dl class="section note"><dt>Note</dt><dd>The allocated memory should be freed with <a class="el" href="#ga32dbd4f54e9e4a7179f2dde37ffe6ad7" title="Free memory that was previously allocated by hwloc_alloc() or hwloc_alloc_membind().">hwloc_free()</a>. </dd></dl>
254
255 </div>
256 </div>
257 <a id="gad0193dadaa1aebd85fe7bba69c552b4e" name="gad0193dadaa1aebd85fe7bba69c552b4e"></a>
258 <h2 class="memtitle"><span class="permalink"><a href="#gad0193dadaa1aebd85fe7bba69c552b4e">&#9670;&#160;</a></span>hwloc_alloc_membind_policy()</h2>
259
260 <div class="memitem">
261 <div class="memproto">
262 <table class="mlabels">
263 <tr>
264 <td class="mlabels-left">
265 <table class="memname">
266 <tr>
267 <td class="memname">void * hwloc_alloc_membind_policy </td>
268 <td>(</td>
269 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
270 </tr>
271 <tr>
272 <td class="paramkey"></td>
273 <td></td>
274 <td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>len</em></span>, </td>
275 </tr>
276 <tr>
277 <td class="paramkey"></td>
278 <td></td>
279 <td class="paramtype"><a class="el" href="a00188.html#gae991a108af01d408be2776c5b2c467b2">hwloc_const_bitmap_t</a></td> <td class="paramname"><span class="paramname"><em>set</em></span>, </td>
280 </tr>
281 <tr>
282 <td class="paramkey"></td>
283 <td></td>
284 <td class="paramtype"><a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a></td> <td class="paramname"><span class="paramname"><em>policy</em></span>, </td>
285 </tr>
286 <tr>
287 <td class="paramkey"></td>
288 <td></td>
289 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
290 </tr>
291 </table>
292 </td>
293 <td class="mlabels-right">
294 <span class="mlabels"><span class="mlabel inline">inline</span></span> </td>
295 </tr>
296 </table>
297 </div><div class="memdoc">
298
299 <p>Allocate some memory on NUMA memory nodes specified by <code class="param">set</code>. </p>
300 <p>First, try to allocate properly with <a class="el" href="#gadf87089ef533db40460ccc24b5bc0d65" title="Allocate some memory on NUMA memory nodes specified by set.">hwloc_alloc_membind()</a>. On failure, the current process or thread memory binding policy is changed with <a class="el" href="#ga020951efa0ce3862bd4faec295501a7f" title="Set the default memory binding policy of the current process or thread to prefer the NUMA node(s) spe...">hwloc_set_membind()</a> before allocating memory. Thus this function works in more cases, at the expense of changing the current state (possibly affecting future allocations that would not specify any policy).</p>
301 <p>If <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256" title="Consider the bitmap argument as a nodeset.">HWLOC_MEMBIND_BYNODESET</a> is specified, set is considered a nodeset. Otherwise it's a cpuset.</p>
302 <dl class="section return"><dt>Returns</dt><dd>a pointer to the allocated area, or <code>NULL</code> on error. </dd></dl>
303
304 </div>
305 </div>
306 <a id="ga32dbd4f54e9e4a7179f2dde37ffe6ad7" name="ga32dbd4f54e9e4a7179f2dde37ffe6ad7"></a>
307 <h2 class="memtitle"><span class="permalink"><a href="#ga32dbd4f54e9e4a7179f2dde37ffe6ad7">&#9670;&#160;</a></span>hwloc_free()</h2>
308
309 <div class="memitem">
310 <div class="memproto">
311 <table class="memname">
312 <tr>
313 <td class="memname">int hwloc_free </td>
314 <td>(</td>
315 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
316 </tr>
317 <tr>
318 <td class="paramkey"></td>
319 <td></td>
320 <td class="paramtype">void *</td> <td class="paramname"><span class="paramname"><em>addr</em></span>, </td>
321 </tr>
322 <tr>
323 <td class="paramkey"></td>
324 <td></td>
325 <td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>len</em></span>&#160;)</td>
326 </tr>
327 </table>
328 </div><div class="memdoc">
329
330 <p>Free memory that was previously allocated by <a class="el" href="#ga95856d8f13357f247d5fce142d443ae3" title="Allocate some memory.">hwloc_alloc()</a> or <a class="el" href="#gadf87089ef533db40460ccc24b5bc0d65" title="Allocate some memory on NUMA memory nodes specified by set.">hwloc_alloc_membind()</a>. </p>
331 <dl class="section return"><dt>Returns</dt><dd>0 on success, -1 on error. </dd></dl>
332
333 </div>
334 </div>
335 <a id="gaa87e0a6946ff145914fdf0b1c60567f8" name="gaa87e0a6946ff145914fdf0b1c60567f8"></a>
336 <h2 class="memtitle"><span class="permalink"><a href="#gaa87e0a6946ff145914fdf0b1c60567f8">&#9670;&#160;</a></span>hwloc_get_area_membind()</h2>
337
338 <div class="memitem">
339 <div class="memproto">
340 <table class="memname">
341 <tr>
342 <td class="memname">int hwloc_get_area_membind </td>
343 <td>(</td>
344 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
345 </tr>
346 <tr>
347 <td class="paramkey"></td>
348 <td></td>
349 <td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>addr</em></span>, </td>
350 </tr>
351 <tr>
352 <td class="paramkey"></td>
353 <td></td>
354 <td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>len</em></span>, </td>
355 </tr>
356 <tr>
357 <td class="paramkey"></td>
358 <td></td>
359 <td class="paramtype"><a class="el" href="a00188.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a></td> <td class="paramname"><span class="paramname"><em>set</em></span>, </td>
360 </tr>
361 <tr>
362 <td class="paramkey"></td>
363 <td></td>
364 <td class="paramtype"><a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a> *</td> <td class="paramname"><span class="paramname"><em>policy</em></span>, </td>
365 </tr>
366 <tr>
367 <td class="paramkey"></td>
368 <td></td>
369 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
370 </tr>
371 </table>
372 </div><div class="memdoc">
373
374 <p>Query the CPUs near the physical NUMA node(s) and binding policy of the memory identified by (<code class="param">addr</code>, <code class="param">len</code> ). </p>
375 <p>The bitmap <code class="param">set</code> (previously allocated by the caller) is filled with the memory area binding.</p>
376 <p>This function has two output parameters: <code class="param">set</code> and <code class="param">policy</code>. The values returned in these parameters depend on both the <code class="param">flags</code> passed in and the memory binding policies and nodesets of the pages in the address range.</p>
377 <p>If <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a0335311a0ee04166df2888d52b4a42c6">HWLOC_MEMBIND_STRICT</a> is specified, the target pages are first checked to see if they all have the same memory binding policy and nodeset. If they do not, -1 is returned and errno is set to <code>EXDEV</code>. If they are identical across all pages, the set and policy are returned in <code class="param">set</code> and <code class="param">policy</code>, respectively.</p>
378 <p>If <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a0335311a0ee04166df2888d52b4a42c6">HWLOC_MEMBIND_STRICT</a> is not specified, the union of all NUMA node(s) containing pages in the address range is calculated. If all pages in the target have the same policy, it is returned in <code class="param">policy</code>. Otherwise, <code class="param">policy</code> is set to <a class="el" href="#ggac9764f79505775d06407b40f5e4661e8a3185bd869b67817fb2bd5164bf360402" title="Returned by get_membind() functions when multiple threads or parts of a memory area have differing me...">HWLOC_MEMBIND_MIXED</a>.</p>
379 <p>If <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256" title="Consider the bitmap argument as a nodeset.">HWLOC_MEMBIND_BYNODESET</a> is specified, set is considered a nodeset. Otherwise it's a cpuset.</p>
380 <p>If any other flags are specified, -1 is returned and errno is set to <code>EINVAL</code>.</p>
381 <dl class="section return"><dt>Returns</dt><dd>0 on success. </dd>
382 <dd>
383 -1 with errno set to <code>EINVAL</code> if <code class="param">len</code> is 0. </dd></dl>
384
385 </div>
386 </div>
387 <a id="ga537c7508a4e2d1db05673ec5be6e805c" name="ga537c7508a4e2d1db05673ec5be6e805c"></a>
388 <h2 class="memtitle"><span class="permalink"><a href="#ga537c7508a4e2d1db05673ec5be6e805c">&#9670;&#160;</a></span>hwloc_get_area_memlocation()</h2>
389
390 <div class="memitem">
391 <div class="memproto">
392 <table class="memname">
393 <tr>
394 <td class="memname">int hwloc_get_area_memlocation </td>
395 <td>(</td>
396 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
397 </tr>
398 <tr>
399 <td class="paramkey"></td>
400 <td></td>
401 <td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>addr</em></span>, </td>
402 </tr>
403 <tr>
404 <td class="paramkey"></td>
405 <td></td>
406 <td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>len</em></span>, </td>
407 </tr>
408 <tr>
409 <td class="paramkey"></td>
410 <td></td>
411 <td class="paramtype"><a class="el" href="a00188.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a></td> <td class="paramname"><span class="paramname"><em>set</em></span>, </td>
412 </tr>
413 <tr>
414 <td class="paramkey"></td>
415 <td></td>
416 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
417 </tr>
418 </table>
419 </div><div class="memdoc">
420
421 <p>Get the NUMA nodes where memory identified by (<code class="param">addr</code>, <code class="param">len</code> ) is physically allocated. </p>
422 <p>The bitmap <code class="param">set</code> (previously allocated by the caller) is filled according to the NUMA nodes where the memory area pages are physically allocated. If no page is actually allocated yet, <code class="param">set</code> may be empty.</p>
423 <p>If pages spread to multiple nodes, it is not specified whether they spread equitably, or whether most of them are on a single node, etc.</p>
424 <p>The operating system may move memory pages from one processor to another at any time according to their binding, so this function may return something that is already outdated.</p>
425 <p>If <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256" title="Consider the bitmap argument as a nodeset.">HWLOC_MEMBIND_BYNODESET</a> is specified in <code class="param">flags</code>, set is considered a nodeset. Otherwise it's a cpuset.</p>
426 <p>If <code class="param">len</code> is 0, <code class="param">set</code> is emptied.</p>
427 <dl class="section return"><dt>Returns</dt><dd>0 on success, -1 on error. </dd></dl>
428
429 </div>
430 </div>
431 <a id="gae21f0a1a884929c784bebf070252aa56" name="gae21f0a1a884929c784bebf070252aa56"></a>
432 <h2 class="memtitle"><span class="permalink"><a href="#gae21f0a1a884929c784bebf070252aa56">&#9670;&#160;</a></span>hwloc_get_membind()</h2>
433
434 <div class="memitem">
435 <div class="memproto">
436 <table class="memname">
437 <tr>
438 <td class="memname">int hwloc_get_membind </td>
439 <td>(</td>
440 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
441 </tr>
442 <tr>
443 <td class="paramkey"></td>
444 <td></td>
445 <td class="paramtype"><a class="el" href="a00188.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a></td> <td class="paramname"><span class="paramname"><em>set</em></span>, </td>
446 </tr>
447 <tr>
448 <td class="paramkey"></td>
449 <td></td>
450 <td class="paramtype"><a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a> *</td> <td class="paramname"><span class="paramname"><em>policy</em></span>, </td>
451 </tr>
452 <tr>
453 <td class="paramkey"></td>
454 <td></td>
455 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
456 </tr>
457 </table>
458 </div><div class="memdoc">
459
460 <p>Query the default memory binding policy and physical locality of the current process or thread. </p>
461 <p>The bitmap <code class="param">set</code> (previously allocated by the caller) is filled with the process or thread memory binding.</p>
462 <p>This function has two output parameters: <code class="param">set</code> and <code class="param">policy</code>. The values returned in these parameters depend on both the <code class="param">flags</code> passed in and the current memory binding policies and nodesets in the queried target.</p>
463 <p>Passing the <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1b1b74aef138f64aff214a8cbdfe8eb4" title="Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually e...">HWLOC_MEMBIND_PROCESS</a> flag specifies that the query target is the current policies and nodesets for all the threads in the current process. Passing <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1dc7dd5cdcd5796893a325a524555298" title="Set policy for a specific thread of the current process. This flag is mutually exclusive with HWLOC_M...">HWLOC_MEMBIND_THREAD</a> specifies that the query target is the current policy and nodeset for only the thread invoking this function.</p>
464 <p>If neither of these flags are passed (which is the most portable method), the process is assumed to be single threaded. This allows hwloc to use either process-based OS functions or thread-based OS functions, depending on which are available.</p>
465 <p><a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a0335311a0ee04166df2888d52b4a42c6">HWLOC_MEMBIND_STRICT</a> is only meaningful when <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1b1b74aef138f64aff214a8cbdfe8eb4" title="Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually e...">HWLOC_MEMBIND_PROCESS</a> is also specified. In this case, hwloc will check the default memory policies and nodesets for all threads in the process. If they are not identical, -1 is returned and errno is set to <code>EXDEV</code>. If they are identical, the values are returned in <code class="param">set</code> and <code class="param">policy</code>.</p>
466 <p>Otherwise, if <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1b1b74aef138f64aff214a8cbdfe8eb4" title="Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually e...">HWLOC_MEMBIND_PROCESS</a> is specified (and <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a0335311a0ee04166df2888d52b4a42c6">HWLOC_MEMBIND_STRICT</a> is <em>not</em> specified), the default set from each thread is logically OR'ed together. If all threads' default policies are the same, <code class="param">policy</code> is set to that policy. If they are different, <code class="param">policy</code> is set to <a class="el" href="#ggac9764f79505775d06407b40f5e4661e8a3185bd869b67817fb2bd5164bf360402" title="Returned by get_membind() functions when multiple threads or parts of a memory area have differing me...">HWLOC_MEMBIND_MIXED</a>.</p>
467 <p>In the <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1dc7dd5cdcd5796893a325a524555298" title="Set policy for a specific thread of the current process. This flag is mutually exclusive with HWLOC_M...">HWLOC_MEMBIND_THREAD</a> case (or when neither <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1b1b74aef138f64aff214a8cbdfe8eb4" title="Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually e...">HWLOC_MEMBIND_PROCESS</a> or <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1dc7dd5cdcd5796893a325a524555298" title="Set policy for a specific thread of the current process. This flag is mutually exclusive with HWLOC_M...">HWLOC_MEMBIND_THREAD</a> is specified), there is only one set and policy; they are returned in <code class="param">set</code> and <code class="param">policy</code>, respectively.</p>
468 <p>If <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256" title="Consider the bitmap argument as a nodeset.">HWLOC_MEMBIND_BYNODESET</a> is specified, set is considered a nodeset. Otherwise it's a cpuset.</p>
469 <p>If any other flags are specified, -1 is returned and errno is set to <code>EINVAL</code>.</p>
470 <dl class="section return"><dt>Returns</dt><dd>0 on success, -1 on error. </dd></dl>
471
472 </div>
473 </div>
474 <a id="ga1730ceb18ec6ee3b7bd3d0db81f07dc8" name="ga1730ceb18ec6ee3b7bd3d0db81f07dc8"></a>
475 <h2 class="memtitle"><span class="permalink"><a href="#ga1730ceb18ec6ee3b7bd3d0db81f07dc8">&#9670;&#160;</a></span>hwloc_get_proc_membind()</h2>
476
477 <div class="memitem">
478 <div class="memproto">
479 <table class="memname">
480 <tr>
481 <td class="memname">int hwloc_get_proc_membind </td>
482 <td>(</td>
483 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
484 </tr>
485 <tr>
486 <td class="paramkey"></td>
487 <td></td>
488 <td class="paramtype">hwloc_pid_t</td> <td class="paramname"><span class="paramname"><em>pid</em></span>, </td>
489 </tr>
490 <tr>
491 <td class="paramkey"></td>
492 <td></td>
493 <td class="paramtype"><a class="el" href="a00188.html#gaa3c2bf4c776d603dcebbb61b0c923d84">hwloc_bitmap_t</a></td> <td class="paramname"><span class="paramname"><em>set</em></span>, </td>
494 </tr>
495 <tr>
496 <td class="paramkey"></td>
497 <td></td>
498 <td class="paramtype"><a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a> *</td> <td class="paramname"><span class="paramname"><em>policy</em></span>, </td>
499 </tr>
500 <tr>
501 <td class="paramkey"></td>
502 <td></td>
503 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
504 </tr>
505 </table>
506 </div><div class="memdoc">
507
508 <p>Query the default memory binding policy and physical locality of the specified process. </p>
509 <p>The bitmap <code class="param">set</code> (previously allocated by the caller) is filled with the process memory binding.</p>
510 <p>This function has two output parameters: <code class="param">set</code> and <code class="param">policy</code>. The values returned in these parameters depend on both the <code class="param">flags</code> passed in and the current memory binding policies and nodesets in the queried target.</p>
511 <p>Passing the <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1b1b74aef138f64aff214a8cbdfe8eb4" title="Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually e...">HWLOC_MEMBIND_PROCESS</a> flag specifies that the query target is the current policies and nodesets for all the threads in the specified process. If <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1b1b74aef138f64aff214a8cbdfe8eb4" title="Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually e...">HWLOC_MEMBIND_PROCESS</a> is not specified (which is the most portable method), the process is assumed to be single threaded. This allows hwloc to use either process-based OS functions or thread-based OS functions, depending on which are available.</p>
512 <p>Note that it does not make sense to pass <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1dc7dd5cdcd5796893a325a524555298" title="Set policy for a specific thread of the current process. This flag is mutually exclusive with HWLOC_M...">HWLOC_MEMBIND_THREAD</a> to this function.</p>
513 <p>If <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a0335311a0ee04166df2888d52b4a42c6">HWLOC_MEMBIND_STRICT</a> is specified, hwloc will check the default memory policies and nodesets for all threads in the specified process. If they are not identical, -1 is returned and errno is set to <code>EXDEV</code>. If they are identical, the values are returned in <code class="param">set</code> and <code class="param">policy</code>.</p>
514 <p>Otherwise, <code class="param">set</code> is set to the logical OR of all threads' default set. If all threads' default policies are the same, <code class="param">policy</code> is set to that policy. If they are different, <code class="param">policy</code> is set to <a class="el" href="#ggac9764f79505775d06407b40f5e4661e8a3185bd869b67817fb2bd5164bf360402" title="Returned by get_membind() functions when multiple threads or parts of a memory area have differing me...">HWLOC_MEMBIND_MIXED</a>.</p>
515 <p>If <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256" title="Consider the bitmap argument as a nodeset.">HWLOC_MEMBIND_BYNODESET</a> is specified, set is considered a nodeset. Otherwise it's a cpuset.</p>
516 <p>If any other flags are specified, -1 is returned and errno is set to <code>EINVAL</code>.</p>
517 <dl class="section return"><dt>Returns</dt><dd>0 on success, -1 on error.</dd></dl>
518 <dl class="section note"><dt>Note</dt><dd><code class="param">hwloc_pid_t</code> is <code class="param">pid_t</code> on Unix platforms, and <code class="param">HANDLE</code> on native Windows platforms. </dd></dl>
519
520 </div>
521 </div>
522 <a id="gaf881faefe20701229f07dd7dbd0125ed" name="gaf881faefe20701229f07dd7dbd0125ed"></a>
523 <h2 class="memtitle"><span class="permalink"><a href="#gaf881faefe20701229f07dd7dbd0125ed">&#9670;&#160;</a></span>hwloc_set_area_membind()</h2>
524
525 <div class="memitem">
526 <div class="memproto">
527 <table class="memname">
528 <tr>
529 <td class="memname">int hwloc_set_area_membind </td>
530 <td>(</td>
531 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
532 </tr>
533 <tr>
534 <td class="paramkey"></td>
535 <td></td>
536 <td class="paramtype">const void *</td> <td class="paramname"><span class="paramname"><em>addr</em></span>, </td>
537 </tr>
538 <tr>
539 <td class="paramkey"></td>
540 <td></td>
541 <td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>len</em></span>, </td>
542 </tr>
543 <tr>
544 <td class="paramkey"></td>
545 <td></td>
546 <td class="paramtype"><a class="el" href="a00188.html#gae991a108af01d408be2776c5b2c467b2">hwloc_const_bitmap_t</a></td> <td class="paramname"><span class="paramname"><em>set</em></span>, </td>
547 </tr>
548 <tr>
549 <td class="paramkey"></td>
550 <td></td>
551 <td class="paramtype"><a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a></td> <td class="paramname"><span class="paramname"><em>policy</em></span>, </td>
552 </tr>
553 <tr>
554 <td class="paramkey"></td>
555 <td></td>
556 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
557 </tr>
558 </table>
559 </div><div class="memdoc">
560
561 <p>Bind the already-allocated memory identified by (addr, len) to the NUMA node(s) specified by <code class="param">set</code>. </p>
562 <p>If <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256" title="Consider the bitmap argument as a nodeset.">HWLOC_MEMBIND_BYNODESET</a> is specified, set is considered a nodeset. Otherwise it's a cpuset.</p>
563 <dl class="section return"><dt>Returns</dt><dd>0 on success or if <code class="param">len</code> is 0. </dd>
564 <dd>
565 -1 with errno set to <code>ENOSYS</code> if the action is not supported. </dd>
566 <dd>
567 -1 with errno set to <code>EXDEV</code> if the binding cannot be enforced. </dd></dl>
568
569 </div>
570 </div>
571 <a id="ga020951efa0ce3862bd4faec295501a7f" name="ga020951efa0ce3862bd4faec295501a7f"></a>
572 <h2 class="memtitle"><span class="permalink"><a href="#ga020951efa0ce3862bd4faec295501a7f">&#9670;&#160;</a></span>hwloc_set_membind()</h2>
573
574 <div class="memitem">
575 <div class="memproto">
576 <table class="memname">
577 <tr>
578 <td class="memname">int hwloc_set_membind </td>
579 <td>(</td>
580 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
581 </tr>
582 <tr>
583 <td class="paramkey"></td>
584 <td></td>
585 <td class="paramtype"><a class="el" href="a00188.html#gae991a108af01d408be2776c5b2c467b2">hwloc_const_bitmap_t</a></td> <td class="paramname"><span class="paramname"><em>set</em></span>, </td>
586 </tr>
587 <tr>
588 <td class="paramkey"></td>
589 <td></td>
590 <td class="paramtype"><a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a></td> <td class="paramname"><span class="paramname"><em>policy</em></span>, </td>
591 </tr>
592 <tr>
593 <td class="paramkey"></td>
594 <td></td>
595 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
596 </tr>
597 </table>
598 </div><div class="memdoc">
599
600 <p>Set the default memory binding policy of the current process or thread to prefer the NUMA node(s) specified by <code class="param">set</code>. </p>
601 <p>If neither <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1b1b74aef138f64aff214a8cbdfe8eb4" title="Set policy for all threads of the specified (possibly multithreaded) process. This flag is mutually e...">HWLOC_MEMBIND_PROCESS</a> nor <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a1dc7dd5cdcd5796893a325a524555298" title="Set policy for a specific thread of the current process. This flag is mutually exclusive with HWLOC_M...">HWLOC_MEMBIND_THREAD</a> is specified, the current process is assumed to be single-threaded. This is the most portable form as it permits hwloc to use either process-based OS functions or thread-based OS functions, depending on which are available.</p>
602 <p>If <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256" title="Consider the bitmap argument as a nodeset.">HWLOC_MEMBIND_BYNODESET</a> is specified, set is considered a nodeset. Otherwise it's a cpuset.</p>
603 <dl class="section return"><dt>Returns</dt><dd>0 on success. </dd>
604 <dd>
605 -1 with errno set to <code>ENOSYS</code> if the action is not supported. </dd>
606 <dd>
607 -1 with errno set to <code>EXDEV</code> if the binding cannot be enforced. </dd></dl>
608
609 </div>
610 </div>
611 <a id="gabc91ff16f7e41047924e3a4ae6d9da7e" name="gabc91ff16f7e41047924e3a4ae6d9da7e"></a>
612 <h2 class="memtitle"><span class="permalink"><a href="#gabc91ff16f7e41047924e3a4ae6d9da7e">&#9670;&#160;</a></span>hwloc_set_proc_membind()</h2>
613
614 <div class="memitem">
615 <div class="memproto">
616 <table class="memname">
617 <tr>
618 <td class="memname">int hwloc_set_proc_membind </td>
619 <td>(</td>
620 <td class="paramtype"><a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a></td> <td class="paramname"><span class="paramname"><em>topology</em></span>, </td>
621 </tr>
622 <tr>
623 <td class="paramkey"></td>
624 <td></td>
625 <td class="paramtype">hwloc_pid_t</td> <td class="paramname"><span class="paramname"><em>pid</em></span>, </td>
626 </tr>
627 <tr>
628 <td class="paramkey"></td>
629 <td></td>
630 <td class="paramtype"><a class="el" href="a00188.html#gae991a108af01d408be2776c5b2c467b2">hwloc_const_bitmap_t</a></td> <td class="paramname"><span class="paramname"><em>set</em></span>, </td>
631 </tr>
632 <tr>
633 <td class="paramkey"></td>
634 <td></td>
635 <td class="paramtype"><a class="el" href="#gac9764f79505775d06407b40f5e4661e8">hwloc_membind_policy_t</a></td> <td class="paramname"><span class="paramname"><em>policy</em></span>, </td>
636 </tr>
637 <tr>
638 <td class="paramkey"></td>
639 <td></td>
640 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
641 </tr>
642 </table>
643 </div><div class="memdoc">
644
645 <p>Set the default memory binding policy of the specified process to prefer the NUMA node(s) specified by <code class="param">set</code>. </p>
646 <p>If <a class="el" href="#ggab00475fd98815bf4fb9aaf752030e7d2a71f19fe4505f1c083dc8e6f7bdea6256" title="Consider the bitmap argument as a nodeset.">HWLOC_MEMBIND_BYNODESET</a> is specified, set is considered a nodeset. Otherwise it's a cpuset.</p>
647 <dl class="section return"><dt>Returns</dt><dd>0 on success. </dd>
648 <dd>
649 -1 with errno set to <code>ENOSYS</code> if the action is not supported. </dd>
650 <dd>
651 -1 with errno set to <code>EXDEV</code> if the binding cannot be enforced.</dd></dl>
652 <dl class="section note"><dt>Note</dt><dd><code class="param">hwloc_pid_t</code> is <code class="param">pid_t</code> on Unix platforms, and <code class="param">HANDLE</code> on native Windows platforms. </dd></dl>
653
654 </div>
655 </div>
656 </div><!-- contents -->
657 <!-- start footer part -->
658 <hr class="footer"/><address class="footer"><small>
659 Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.15.0
660 </small></address>
661 </div><!-- doc-content -->
662 </body>
663 </html>