doc/generated/html/api/group__map.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
   5 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
   6 <title>Xenomai API: Lightweight key-to-object mapping service</title>
   7 <link href="tabs.css" rel="stylesheet" type="text/css"/>
   8 <script type="text/javascript" src="jquery.js"></script>
   9 <script type="text/javascript" src="dynsections.js"></script>
  10 <link href="navtree.css" rel="stylesheet" type="text/css"/>
  11 <script type="text/javascript" src="resize.js"></script>
  12 <script type="text/javascript" src="navtree.js"></script>
  13 <script type="text/javascript">
  14   $(document).ready(initResizable);
  15 </script>
  16 <link href="search/search.css" rel="stylesheet" type="text/css"/>
  17 <script type="text/javascript" src="search/search.js"></script>
  18 <script type="text/javascript">
  19   $(document).ready(function() {
  20     if ($('.searchresults').length > 0) { searchBox.DOMSearchField().focus(); }
  21   });
  22 </script>
  23 <link rel="search" href="search-opensearch.php?v=opensearch.xml" type="application/opensearchdescription+xml" title="Xenomai API"/>
  24 <link href="doxygen.css" rel="stylesheet" type="text/css" />
  25 </head>
  26 <body>
  27 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
  28 <div id="titlearea">
  29 <table cellspacing="0" cellpadding="0">
  30  <tbody>
  31  <tr style="height: 56px;">
  32   <td style="padding-left: 0.5em;">
  33    <div id="projectname">Xenomai API
  34    &#160;<span id="projectnumber">2.6.3</span>
  35    </div>
  36   </td>
  37  </tr>
  38  </tbody>
  39 </table>
  40 </div>
  41 <!-- end header part -->
  42 <!-- Generated by Doxygen 1.8.1.2 -->
  43 <script type="text/javascript">
  44 var searchBox = new SearchBox("searchBox", "search",false,'Search');
  45 </script>
  46   <div id="navrow1" class="tabs">
  47     <ul class="tablist">
  48       <li><a href="index.html"><span>Main&#160;Page</span></a></li>
  49       <li><a href="pages.html"><span>Related&#160;Pages</span></a></li>
  50       <li><a href="modules.html"><span>Modules</span></a></li>
  51       <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
  52       <li><a href="files.html"><span>Files</span></a></li>
  53       <li><a href="examples.html"><span>Examples</span></a></li>
  54       <li>
  55         <div id="MSearchBox" class="MSearchBoxInactive">
  56           <div class="left">
  57             <form id="FSearchBox" action="search.php" method="get">
  58               <img id="MSearchSelect" src="search/mag.png" alt=""/>
  59               <input type="text" id="MSearchField" name="query" value="Search" size="20" accesskey="S"
  60                      onfocus="searchBox.OnSearchFieldFocus(true)"
  61                      onblur="searchBox.OnSearchFieldFocus(false)"/>
  62             </form>
  63           </div><div class="right"></div>
  64         </div>
  65       </li>
  66     </ul>
  67   </div>
  68 </div><!-- top -->
  69 <div id="side-nav" class="ui-resizable side-nav-resizable">
  70   <div id="nav-tree">
  71     <div id="nav-tree-contents">
  72       <div id="nav-sync" class="sync"></div>
  73     </div>
  74   </div>
  75   <div id="splitbar" style="-moz-user-select:none;"
  76        class="ui-resizable-handle">
  77   </div>
  78 </div>
  79 <script type="text/javascript">
  80 $(document).ready(function(){initNavTree('group__map.html','');});
  81 </script>
  82 <div id="doc-content">
  83 <div class="header">
  84   <div class="summary">
  85 <a href="#files">Files</a> &#124;
  86 <a href="#func-members">Functions</a>  </div>
  87   <div class="headertitle">
  88 <div class="title">Lightweight key-to-object mapping service</div>  </div>
  89 <div class="ingroups"><a class="el" href="group__nucleus.html">Xenomai nucleus.</a></div></div><!--header-->
  90 <div class="contents">
  91 <div class="dynheader">
  92 Collaboration diagram for Lightweight key-to-object mapping service:</div>
  93 <div class="dyncontent">
  94 <center><table><tr><td><img src="group__map.png" border="0" alt="" usemap="#group____map"/>
  95 <map name="group____map" id="group____map">
  96 <area shape="rect" id="node1" href="group__nucleus.html" title="Xenomai nucleus." alt="" coords="7,13,132,43"/></map>
  97 </td></tr></table></center>
  98 </div>
  99 <table class="memberdecls">
 100 <tr class="heading"><td colspan="2"><h2><a name="files"></a>
 101 Files</h2></td></tr>
 102 <tr class="memitem:map_8h"><td class="memItemLeft" align="right" valign="top">file &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="map_8h.html">map.h</a></td></tr>
 103 <tr class="memitem:map_8c"><td class="memItemLeft" align="right" valign="top">file &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="map_8c.html">map.c</a></td></tr>
 104 </table><table class="memberdecls">
 105 <tr class="heading"><td colspan="2"><h2><a name="func-members"></a>
 106 Functions</h2></td></tr>
 107 <tr class="memitem:ga011ef197e2f81ad708858902787f04f8"><td class="memItemLeft" align="right" valign="top">xnmap_t *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__map.html#ga011ef197e2f81ad708858902787f04f8">xnmap_create</a> (int nkeys, int reserve, int offset)</td></tr>
 108 <tr class="memdesc:ga011ef197e2f81ad708858902787f04f8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Create a map.  <a href="#ga011ef197e2f81ad708858902787f04f8"></a><br/></td></tr>
 109 <tr class="memitem:ga1a5b1c7a8e7966a2dd58404a0385aca8"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__map.html#ga1a5b1c7a8e7966a2dd58404a0385aca8">xnmap_delete</a> (xnmap_t *map)</td></tr>
 110 <tr class="memdesc:ga1a5b1c7a8e7966a2dd58404a0385aca8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Delete a map.  <a href="#ga1a5b1c7a8e7966a2dd58404a0385aca8"></a><br/></td></tr>
 111 <tr class="memitem:gadc5657b93b294c935ac6864fac5fdaa4"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__map.html#gadc5657b93b294c935ac6864fac5fdaa4">xnmap_enter</a> (xnmap_t *map, int key, void *objaddr)</td></tr>
 112 <tr class="memdesc:gadc5657b93b294c935ac6864fac5fdaa4"><td class="mdescLeft">&#160;</td><td class="mdescRight">Index an object into a map.  <a href="#gadc5657b93b294c935ac6864fac5fdaa4"></a><br/></td></tr>
 113 <tr class="memitem:ga06ec1012c075be6dbbadd2d88220abf5"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__map.html#ga06ec1012c075be6dbbadd2d88220abf5">xnmap_remove</a> (xnmap_t *map, int key)</td></tr>
 114 <tr class="memdesc:ga06ec1012c075be6dbbadd2d88220abf5"><td class="mdescLeft">&#160;</td><td class="mdescRight">Remove an object reference from a map.  <a href="#ga06ec1012c075be6dbbadd2d88220abf5"></a><br/></td></tr>
 115 <tr class="memitem:ga651ded315d1eec00d1e661e52ce4a10e"><td class="memItemLeft" align="right" valign="top">static void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__map.html#ga651ded315d1eec00d1e661e52ce4a10e">xnmap_fetch_nocheck</a> (xnmap_t *map, int key)</td></tr>
 116 <tr class="memdesc:ga651ded315d1eec00d1e661e52ce4a10e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Search an object into a map - unchecked form.  <a href="#ga651ded315d1eec00d1e661e52ce4a10e"></a><br/></td></tr>
 117 <tr class="memitem:ga52a2727670d06e52b9b73b0c2c1d60d7"><td class="memItemLeft" align="right" valign="top">static void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__map.html#ga52a2727670d06e52b9b73b0c2c1d60d7">xnmap_fetch</a> (xnmap_t *map, int key)</td></tr>
 118 <tr class="memdesc:ga52a2727670d06e52b9b73b0c2c1d60d7"><td class="mdescLeft">&#160;</td><td class="mdescRight">Search an object into a map.  <a href="#ga52a2727670d06e52b9b73b0c2c1d60d7"></a><br/></td></tr>
 119 </table>
 120 <a name="details" id="details"></a><h2>Detailed Description</h2>
 121 <p>A map is a simple indexing structure which associates unique integer keys with pointers to objects. The current implementation supports reservation, for naming/indexing the real-time objects skins create, either on a fixed, user-provided integer (i.e. a reserved key value), or by drawing the next available key internally if the caller did not specify any fixed key. For instance, in some given map, the key space ranging from 0 to 255 could be reserved for fixed keys, whilst the range from 256 to 511 could be available for drawing free keys dynamically.</p>
 122 <p>A maximum of 1024 unique keys per map is supported on 32bit machines.</p>
 123 <p>(This implementation should not be confused with C++ STL maps, which are dynamically expandable and allow arbitrary key types; Xenomai maps don't). </p>
 124 <h2>Function Documentation</h2>
 125 <a class="anchor" id="ga011ef197e2f81ad708858902787f04f8"></a>
 126 <div class="memitem">
 127 <div class="memproto">
 128       <table class="memname">
 129         <tr>
 130           <td class="memname">xnmap_t * xnmap_create </td>
 131           <td>(</td>
 132           <td class="paramtype">int&#160;</td>
 133           <td class="paramname"><em>nkeys</em>, </td>
 134         </tr>
 135         <tr>
 136           <td class="paramkey"></td>
 137           <td></td>
 138           <td class="paramtype">int&#160;</td>
 139           <td class="paramname"><em>reserve</em>, </td>
 140         </tr>
 141         <tr>
 142           <td class="paramkey"></td>
 143           <td></td>
 144           <td class="paramtype">int&#160;</td>
 145           <td class="paramname"><em>offset</em>&#160;</td>
 146         </tr>
 147         <tr>
 148           <td></td>
 149           <td>)</td>
 150           <td></td><td></td>
 151         </tr>
 152       </table>
 153 </div><div class="memdoc">
 154
 155 <p>Create a map. </p>
 156 <p>Allocates a new map with the specified addressing capabilities. The memory is obtained from the Xenomai system heap.</p>
 157 <dl class="params"><dt>Parameters</dt><dd>
 158   <table class="params">
 159     <tr><td class="paramname">nkeys</td><td>The maximum number of unique keys the map will be able to hold. This value cannot exceed the static limit represented by XNMAP_MAX_KEYS, and must be a power of two.</td></tr>
 160     <tr><td class="paramname">reserve</td><td>The number of keys which should be kept for reservation within the index space. Reserving a key means to specify a valid key to the <a class="el" href="group__map.html#gadc5657b93b294c935ac6864fac5fdaa4" title="Index an object into a map.">xnmap_enter()</a> service, which will then attempt to register this exact key, instead of drawing the next available key from the unreserved index space. When reservation is in effect, the unreserved index space will hold key values greater than <em>reserve</em>, keeping the low key values for the reserved space. For instance, passing <em>reserve</em> = 32 would cause the index range [ 0 .. 31 ] to be kept for reserved keys. When non-zero, <em>reserve</em> is rounded to the next multiple of BITS_PER_LONG. If <em>reserve</em> is zero no reservation will be available from the map.</td></tr>
 161     <tr><td class="paramname">offset</td><td>The lowest key value <a class="el" href="group__map.html#gadc5657b93b294c935ac6864fac5fdaa4" title="Index an object into a map.">xnmap_enter()</a> will return to the caller. Key values will be in the range [ 0 + offset .. <em>nkeys</em> + offset - 1 ]. Negative offsets are valid.</td></tr>
 162   </table>
 163   </dd>
 164 </dl>
 165 <dl class="section return"><dt>Returns</dt><dd>the address of the new map is returned on success; otherwise, NULL is returned if <em>nkeys</em> is invalid.</dd></dl>
 166 <p>Environments:</p>
 167 <p>This service can be called from:</p>
 168 <ul>
 169 <li>Kernel module initialization/cleanup code</li>
 170 <li>Kernel-based task</li>
 171 <li>User-space task</li>
 172 </ul>
 173 <p>Rescheduling: never. </p>
 174
 175 </div>
 176 </div>
 177 <a class="anchor" id="ga1a5b1c7a8e7966a2dd58404a0385aca8"></a>
 178 <div class="memitem">
 179 <div class="memproto">
 180       <table class="memname">
 181         <tr>
 182           <td class="memname">void xnmap_delete </td>
 183           <td>(</td>
 184           <td class="paramtype">xnmap_t *&#160;</td>
 185           <td class="paramname"><em>map</em></td><td>)</td>
 186           <td></td>
 187         </tr>
 188       </table>
 189 </div><div class="memdoc">
 190
 191 <p>Delete a map. </p>
 192 <p>Deletes a map, freeing any associated memory back to the Xenomai system heap.</p>
 193 <dl class="params"><dt>Parameters</dt><dd>
 194   <table class="params">
 195     <tr><td class="paramname">map</td><td>The address of the map to delete.</td></tr>
 196   </table>
 197   </dd>
 198 </dl>
 199 <p>Environments:</p>
 200 <p>This service can be called from:</p>
 201 <ul>
 202 <li>Kernel module initialization/cleanup code</li>
 203 <li>Kernel-based task</li>
 204 <li>User-space task</li>
 205 </ul>
 206 <p>Rescheduling: never. </p>
 207
 208 </div>
 209 </div>
 210 <a class="anchor" id="gadc5657b93b294c935ac6864fac5fdaa4"></a>
 211 <div class="memitem">
 212 <div class="memproto">
 213       <table class="memname">
 214         <tr>
 215           <td class="memname">int xnmap_enter </td>
 216           <td>(</td>
 217           <td class="paramtype">xnmap_t *&#160;</td>
 218           <td class="paramname"><em>map</em>, </td>
 219         </tr>
 220         <tr>
 221           <td class="paramkey"></td>
 222           <td></td>
 223           <td class="paramtype">int&#160;</td>
 224           <td class="paramname"><em>key</em>, </td>
 225         </tr>
 226         <tr>
 227           <td class="paramkey"></td>
 228           <td></td>
 229           <td class="paramtype">void *&#160;</td>
 230           <td class="paramname"><em>objaddr</em>&#160;</td>
 231         </tr>
 232         <tr>
 233           <td></td>
 234           <td>)</td>
 235           <td></td><td></td>
 236         </tr>
 237       </table>
 238 </div><div class="memdoc">
 239
 240 <p>Index an object into a map. </p>
 241 <p>Insert a new object into the given map.</p>
 242 <dl class="params"><dt>Parameters</dt><dd>
 243   <table class="params">
 244     <tr><td class="paramname">map</td><td>The address of the map to insert into.</td></tr>
 245     <tr><td class="paramname">key</td><td>The key to index the object on. If this key is within the valid index range [ 0 - offset .. nkeys - offset - 1 ], then an attempt to reserve this exact key is made. If <em>key</em> has an out-of-range value lower or equal to 0 - offset - 1, then an attempt is made to draw a free key from the unreserved index space.</td></tr>
 246     <tr><td class="paramname">objaddr</td><td>The address of the object to index on the key. This value will be returned by a successful call to <a class="el" href="group__map.html#ga52a2727670d06e52b9b73b0c2c1d60d7" title="Search an object into a map.">xnmap_fetch()</a> with the same key.</td></tr>
 247   </table>
 248   </dd>
 249 </dl>
 250 <dl class="section return"><dt>Returns</dt><dd>a valid key is returned on success, either <em>key</em> if reserved, or the next free key. Otherwise:</dd></dl>
 251 <ul>
 252 <li>-EEXIST is returned upon attempt to reserve a busy key.</li>
 253 </ul>
 254 <ul>
 255 <li>-ENOSPC when no more free key is available.</li>
 256 </ul>
 257 <p>Environments:</p>
 258 <p>This service can be called from:</p>
 259 <ul>
 260 <li>Kernel module initialization/cleanup code</li>
 261 <li>Interrupt service routine</li>
 262 <li>Kernel-based task</li>
 263 <li>User-space task</li>
 264 </ul>
 265 <p>Rescheduling: never. </p>
 266
 267 </div>
 268 </div>
 269 <a class="anchor" id="ga52a2727670d06e52b9b73b0c2c1d60d7"></a>
 270 <div class="memitem">
 271 <div class="memproto">
 272 <table class="mlabels">
 273   <tr>
 274   <td class="mlabels-left">
 275       <table class="memname">
 276         <tr>
 277           <td class="memname">void xnmap_fetch </td>
 278           <td>(</td>
 279           <td class="paramtype">xnmap_t *&#160;</td>
 280           <td class="paramname"><em>map</em>, </td>
 281         </tr>
 282         <tr>
 283           <td class="paramkey"></td>
 284           <td></td>
 285           <td class="paramtype">int&#160;</td>
 286           <td class="paramname"><em>key</em>&#160;</td>
 287         </tr>
 288         <tr>
 289           <td></td>
 290           <td>)</td>
 291           <td></td><td></td>
 292         </tr>
 293       </table>
 294   </td>
 295   <td class="mlabels-right">
 296 <span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">static</span></span>  </td>
 297   </tr>
 298 </table>
 299 </div><div class="memdoc">
 300
 301 <p>Search an object into a map. </p>
 302 <p>Retrieve an object reference from the given map by its index key.</p>
 303 <dl class="params"><dt>Parameters</dt><dd>
 304   <table class="params">
 305     <tr><td class="paramname">map</td><td>The address of the map to retrieve from.</td></tr>
 306     <tr><td class="paramname">key</td><td>The key to be searched for in the map index.</td></tr>
 307   </table>
 308   </dd>
 309 </dl>
 310 <dl class="section return"><dt>Returns</dt><dd>The indexed object address is returned on success, otherwise NULL is returned when <em>key</em> is invalid or no object is currently indexed on it.</dd></dl>
 311 <p>Environments:</p>
 312 <p>This service can be called from:</p>
 313 <ul>
 314 <li>Kernel module initialization/cleanup code</li>
 315 <li>Interrupt service routine</li>
 316 <li>Kernel-based task</li>
 317 <li>User-space task</li>
 318 </ul>
 319 <p>Rescheduling: never. </p>
 320
 321 </div>
 322 </div>
 323 <a class="anchor" id="ga651ded315d1eec00d1e661e52ce4a10e"></a>
 324 <div class="memitem">
 325 <div class="memproto">
 326 <table class="mlabels">
 327   <tr>
 328   <td class="mlabels-left">
 329       <table class="memname">
 330         <tr>
 331           <td class="memname">void xnmap_fetch_nocheck </td>
 332           <td>(</td>
 333           <td class="paramtype">xnmap_t *&#160;</td>
 334           <td class="paramname"><em>map</em>, </td>
 335         </tr>
 336         <tr>
 337           <td class="paramkey"></td>
 338           <td></td>
 339           <td class="paramtype">int&#160;</td>
 340           <td class="paramname"><em>key</em>&#160;</td>
 341         </tr>
 342         <tr>
 343           <td></td>
 344           <td>)</td>
 345           <td></td><td></td>
 346         </tr>
 347       </table>
 348   </td>
 349   <td class="mlabels-right">
 350 <span class="mlabels"><span class="mlabel">inline</span><span class="mlabel">static</span></span>  </td>
 351   </tr>
 352 </table>
 353 </div><div class="memdoc">
 354
 355 <p>Search an object into a map - unchecked form. </p>
 356 <p>Retrieve an object reference from the given map by its index key, but does not perform any sanity check on the provided key.</p>
 357 <dl class="params"><dt>Parameters</dt><dd>
 358   <table class="params">
 359     <tr><td class="paramname">map</td><td>The address of the map to retrieve from.</td></tr>
 360     <tr><td class="paramname">key</td><td>The key to be searched for in the map index.</td></tr>
 361   </table>
 362   </dd>
 363 </dl>
 364 <dl class="section return"><dt>Returns</dt><dd>The indexed object address is returned on success, otherwise NULL is returned when no object is currently indexed on <em>key</em>.</dd></dl>
 365 <p>Environments:</p>
 366 <p>This service can be called from:</p>
 367 <ul>
 368 <li>Kernel module initialization/cleanup code</li>
 369 <li>Interrupt service routine</li>
 370 <li>Kernel-based task</li>
 371 <li>User-space task</li>
 372 </ul>
 373 <p>Rescheduling: never. </p>
 374
 375 </div>
 376 </div>
 377 <a class="anchor" id="ga06ec1012c075be6dbbadd2d88220abf5"></a>
 378 <div class="memitem">
 379 <div class="memproto">
 380       <table class="memname">
 381         <tr>
 382           <td class="memname">int xnmap_remove </td>
 383           <td>(</td>
 384           <td class="paramtype">xnmap_t *&#160;</td>
 385           <td class="paramname"><em>map</em>, </td>
 386         </tr>
 387         <tr>
 388           <td class="paramkey"></td>
 389           <td></td>
 390           <td class="paramtype">int&#160;</td>
 391           <td class="paramname"><em>key</em>&#160;</td>
 392         </tr>
 393         <tr>
 394           <td></td>
 395           <td>)</td>
 396           <td></td><td></td>
 397         </tr>
 398       </table>
 399 </div><div class="memdoc">
 400
 401 <p>Remove an object reference from a map. </p>
 402 <p>Removes an object reference from the given map, releasing the associated key.</p>
 403 <dl class="params"><dt>Parameters</dt><dd>
 404   <table class="params">
 405     <tr><td class="paramname">map</td><td>The address of the map to remove from.</td></tr>
 406     <tr><td class="paramname">key</td><td>The key the object reference to be removed is indexed on.</td></tr>
 407   </table>
 408   </dd>
 409 </dl>
 410 <dl class="section return"><dt>Returns</dt><dd>0 is returned on success. Otherwise:</dd></dl>
 411 <ul>
 412 <li>-ESRCH is returned if <em>key</em> is invalid.</li>
 413 </ul>
 414 <p>Environments:</p>
 415 <p>This service can be called from:</p>
 416 <ul>
 417 <li>Kernel module initialization/cleanup code</li>
 418 <li>Interrupt service routine</li>
 419 <li>Kernel-based task</li>
 420 <li>User-space task</li>
 421 </ul>
 422 <p>Rescheduling: never. </p>
 423
 424 </div>
 425 </div>
 426 </div><!-- contents -->
 427 </div><!-- doc-content -->
 428 <!-- start footer part -->
 429 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
 430   <ul>
 431     <li class="footer">Generated on Fri Oct 4 2013 22:39:08 for Xenomai API by
 432     <a href="http://www.doxygen.org/index.html">
 433     <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.1.2 </li>
 434   </ul>
 435 </div>
 436 </body>
 437 </html>