Debian Codegraph @

doc/doxygen-doc/html/a00184.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): Distributing items over a topology</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">Distributing items over a topology </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:ga8b835295a52b6768a5e6c8abb1f9c54d" id="r_ga8b835295a52b6768a5e6c8abb1f9c54d"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ga8b835295a52b6768a5e6c8abb1f9c54d">hwloc_distrib_flags_e</a> { <a class="el" href="#gga8b835295a52b6768a5e6c8abb1f9c54da2ca08404bfbebe9ed5f34c3d7635425a">HWLOC_DISTRIB_FLAG_REVERSE</a>
55 }</td></tr>
56 </table><table class="memberdecls">
57 <tr class="heading"><td colspan="2"><h2 id="header-func-members" class="groupheader"><a id="func-members" name="func-members"></a>
58 Functions</h2></td></tr>
59 <tr class="memitem:gac14e61485402837e87293079fa0270f2" id="r_gac14e61485402837e87293079fa0270f2"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#gac14e61485402837e87293079fa0270f2">hwloc_distrib</a> (<a class="el" href="a00169.html#ga9d1e76ee15a7dee158b786c30b6a6e38">hwloc_topology_t</a> topology, <a class="el" href="a00168.html#ga79b8ab56877ef99ac59b833203391c7d">hwloc_obj_t</a> *roots, unsigned n_roots, <a class="el" href="a00166.html#ga4bbf39b68b6f568fb92739e7c0ea7801">hwloc_cpuset_t</a> *set, unsigned n, int until, unsigned long flags)</td></tr>
60 </table>
61 <a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2>
62 <a name="doc-enum-members" id="doc-enum-members"></a><h2 id="header-doc-enum-members" class="groupheader">Enumeration Type Documentation</h2>
63 <a id="ga8b835295a52b6768a5e6c8abb1f9c54d" name="ga8b835295a52b6768a5e6c8abb1f9c54d"></a>
64 <h2 class="memtitle"><span class="permalink"><a href="#ga8b835295a52b6768a5e6c8abb1f9c54d">&#9670;&#160;</a></span>hwloc_distrib_flags_e</h2>
65
66 <div class="memitem">
67 <div class="memproto">
68 <table class="memname">
69 <tr>
70 <td class="memname">enum <a class="el" href="#ga8b835295a52b6768a5e6c8abb1f9c54d">hwloc_distrib_flags_e</a></td>
71 </tr>
72 </table>
73 </div><div class="memdoc">
74
75 <p>Flags to be given to <a class="el" href="#gac14e61485402837e87293079fa0270f2" title="Distribute n items over the topology under roots.">hwloc_distrib()</a>. </p>
76 <table class="fieldtable">
77 <tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="gga8b835295a52b6768a5e6c8abb1f9c54da2ca08404bfbebe9ed5f34c3d7635425a" name="gga8b835295a52b6768a5e6c8abb1f9c54da2ca08404bfbebe9ed5f34c3d7635425a"></a>HWLOC_DISTRIB_FLAG_REVERSE&#160;</td><td class="fielddoc"><p>Distrib in reverse order, starting from the last objects. </p>
78 </td></tr>
79 </table>
80
81 </div>
82 </div>
83 <a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2>
84 <a id="gac14e61485402837e87293079fa0270f2" name="gac14e61485402837e87293079fa0270f2"></a>
85 <h2 class="memtitle"><span class="permalink"><a href="#gac14e61485402837e87293079fa0270f2">&#9670;&#160;</a></span>hwloc_distrib()</h2>
86
87 <div class="memitem">
88 <div class="memproto">
89 <table class="mlabels">
90 <tr>
91 <td class="mlabels-left">
92 <table class="memname">
93 <tr>
94 <td class="memname">int hwloc_distrib </td>
95 <td>(</td>
96 <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>
97 </tr>
98 <tr>
99 <td class="paramkey"></td>
100 <td></td>
101 <td class="paramtype"><a class="el" href="a00168.html#ga79b8ab56877ef99ac59b833203391c7d">hwloc_obj_t</a> *</td> <td class="paramname"><span class="paramname"><em>roots</em></span>, </td>
102 </tr>
103 <tr>
104 <td class="paramkey"></td>
105 <td></td>
106 <td class="paramtype">unsigned</td> <td class="paramname"><span class="paramname"><em>n_roots</em></span>, </td>
107 </tr>
108 <tr>
109 <td class="paramkey"></td>
110 <td></td>
111 <td class="paramtype"><a class="el" href="a00166.html#ga4bbf39b68b6f568fb92739e7c0ea7801">hwloc_cpuset_t</a> *</td> <td class="paramname"><span class="paramname"><em>set</em></span>, </td>
112 </tr>
113 <tr>
114 <td class="paramkey"></td>
115 <td></td>
116 <td class="paramtype">unsigned</td> <td class="paramname"><span class="paramname"><em>n</em></span>, </td>
117 </tr>
118 <tr>
119 <td class="paramkey"></td>
120 <td></td>
121 <td class="paramtype">int</td> <td class="paramname"><span class="paramname"><em>until</em></span>, </td>
122 </tr>
123 <tr>
124 <td class="paramkey"></td>
125 <td></td>
126 <td class="paramtype">unsigned long</td> <td class="paramname"><span class="paramname"><em>flags</em></span>&#160;)</td>
127 </tr>
128 </table>
129 </td>
130 <td class="mlabels-right">
131 <span class="mlabels"><span class="mlabel inline">inline</span></span> </td>
132 </tr>
133 </table>
134 </div><div class="memdoc">
135
136 <p>Distribute <code class="param">n</code> items over the topology under <code class="param">roots</code>. </p>
137 <p>Array <code class="param">set</code> will be filled with <code class="param">n</code> cpusets recursively distributed linearly over the topology under objects <code class="param">roots</code>, down to depth <code class="param">until</code> (which can be INT_MAX to distribute down to the finest level).</p>
138 <p><code class="param">n_roots</code> is usually 1 and <code class="param">roots</code> only contains the topology root object so as to distribute over the entire topology.</p>
139 <p>This is typically useful when an application wants to distribute <code class="param">n</code> threads over a machine, giving each of them as much private cache as possible and keeping them locally in number order.</p>
140 <p>The caller may typically want to also call <a class="el" href="a00188.html#gaa611a77c092e679246afdf9a60d5db8b" title="Keep a single index among those set in bitmap bitmap.">hwloc_bitmap_singlify()</a> before binding a thread so that it does not move at all.</p>
141 <p><code class="param">flags</code> should be 0 or a OR'ed set of <a class="el" href="#ga8b835295a52b6768a5e6c8abb1f9c54d" title="Flags to be given to hwloc_distrib().">hwloc_distrib_flags_e</a>.</p>
142 <dl class="section return"><dt>Returns</dt><dd>0 on success, -1 on error.</dd></dl>
143 <dl class="section note"><dt>Note</dt><dd>On hybrid CPUs (or asymmetric platforms), distribution may be suboptimal since the number of cores or PUs inside packages or below caches may vary (the top-down recursive partitioning ignores these numbers until reaching their levels). Hence it is recommended to distribute only inside a single homogeneous domain. For instance on a CPU with energy-efficient E-cores and high-performance P-cores, one should distribute separately N tasks on E-cores and M tasks on P-cores instead of trying to distribute directly M+N tasks on the entire CPUs.</dd>
144 <dd>
145 This function requires the <code class="param">roots</code> objects to have a CPU set. </dd></dl>
146
147 </div>
148 </div>
149 </div><!-- contents -->
150 <!-- start footer part -->
151 <hr class="footer"/><address class="footer"><small>
152 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
153 </small></address>
154 </div><!-- doc-content -->
155 </body>
156 </html>