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 <title>Xenomai API: Lightweight key-to-object mapping service</title>
   6 <link href="tabs.css" rel="stylesheet" type="text/css"/>
   7 <link href="doxygen.css" rel="stylesheet" type="text/css"/>
   8 </head>
   9 <body>
  10 <!-- Generated by Doxygen 1.7.1 -->
  11 <div class="navigation" id="top">
  12   <div class="tabs">
  13     <ul class="tablist">
  14       <li><a href="main.html"><span>Main&nbsp;Page</span></a></li>
  15       <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
  16       <li><a href="modules.html"><span>Modules</span></a></li>
  17       <li><a href="annotated.html"><span>Data&nbsp;Structures</span></a></li>
  18       <li><a href="files.html"><span>Files</span></a></li>
  19       <li><a href="examples.html"><span>Examples</span></a></li>
  20     </ul>
  21   </div>
  22 </div>
  23 <div class="header">
  24   <div class="summary">
  25 <a href="#files">Files</a> &#124;
  26 <a href="#func-members">Functions</a>  </div>
  27   <div class="headertitle">
  28 <h1>Lightweight key-to-object mapping service<br/>
  29 <small>
  30 [<a class="el" href="group__nucleus.html">Xenomai nucleus.</a>]</small>
  31 </h1>  </div>
  32 </div>
  33 <div class="contents">
  34
  35 <p><div class="dynheader">
  36 Collaboration diagram for Lightweight key-to-object mapping service:</div>
  37 <div class="dyncontent">
  38 <center><table><tr><td><img src="group__map.png" border="0" alt="" usemap="#group____map"/>
  39 <map name="group____map" id="group____map">
  40 <area shape="rect" id="node1" href="group__nucleus.html" title="Xenomai nucleus." alt="" coords="7,5,143,35"/></map>
  41 </td></tr></table></center>
  42 </div>
  43 </p>
  44 <table class="memberdecls">
  45 <tr><td colspan="2"><h2><a name="files"></a>
  46 Files</h2></td></tr>
  47 <tr><td class="memItemLeft" align="right" valign="top">file &nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="map_8h.html">map.h</a></td></tr>
  48 <tr><td class="memItemLeft" align="right" valign="top">file &nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="map_8c.html">map.c</a></td></tr>
  49 <tr><td colspan="2"><h2><a name="func-members"></a>
  50 Functions</h2></td></tr>
  51 <tr><td class="memItemLeft" align="right" valign="top">xnmap_t *&nbsp;</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>
  52 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Create a map.  <a href="#ga011ef197e2f81ad708858902787f04f8"></a><br/></td></tr>
  53 <tr><td class="memItemLeft" align="right" valign="top">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__map.html#ga1a5b1c7a8e7966a2dd58404a0385aca8">xnmap_delete</a> (xnmap_t *map)</td></tr>
  54 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Delete a map.  <a href="#ga1a5b1c7a8e7966a2dd58404a0385aca8"></a><br/></td></tr>
  55 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</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>
  56 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Index an object into a map.  <a href="#gadc5657b93b294c935ac6864fac5fdaa4"></a><br/></td></tr>
  57 <tr><td class="memItemLeft" align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__map.html#ga06ec1012c075be6dbbadd2d88220abf5">xnmap_remove</a> (xnmap_t *map, int key)</td></tr>
  58 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Remove an object reference from a map.  <a href="#ga06ec1012c075be6dbbadd2d88220abf5"></a><br/></td></tr>
  59 <tr><td class="memItemLeft" align="right" valign="top">static void *&nbsp;</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>
  60 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Search an object into a map - unchecked form.  <a href="#ga651ded315d1eec00d1e661e52ce4a10e"></a><br/></td></tr>
  61 <tr><td class="memItemLeft" align="right" valign="top">static void *&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__map.html#ga52a2727670d06e52b9b73b0c2c1d60d7">xnmap_fetch</a> (xnmap_t *map, int key)</td></tr>
  62 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Search an object into a map.  <a href="#ga52a2727670d06e52b9b73b0c2c1d60d7"></a><br/></td></tr>
  63 </table>
  64 <hr/><a name="_details"></a><h2>Detailed Description</h2>
  65 <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>
  66 <p>A maximum of 1024 unique keys per map is supported on 32bit machines.</p>
  67 <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>
  68 <hr/><h2>Function Documentation</h2>
  69 <a class="anchor" id="ga011ef197e2f81ad708858902787f04f8"></a><!-- doxytag: member="map.h::xnmap_create" ref="ga011ef197e2f81ad708858902787f04f8" args="(int nkeys, int reserve, int offset)" -->
  70 <div class="memitem">
  71 <div class="memproto">
  72       <table class="memname">
  73         <tr>
  74           <td class="memname">xnmap_t * xnmap_create </td>
  75           <td>(</td>
  76           <td class="paramtype">int&nbsp;</td>
  77           <td class="paramname"> <em>nkeys</em>, </td>
  78         </tr>
  79         <tr>
  80           <td class="paramkey"></td>
  81           <td></td>
  82           <td class="paramtype">int&nbsp;</td>
  83           <td class="paramname"> <em>reserve</em>, </td>
  84         </tr>
  85         <tr>
  86           <td class="paramkey"></td>
  87           <td></td>
  88           <td class="paramtype">int&nbsp;</td>
  89           <td class="paramname"> <em>offset</em></td><td>&nbsp;</td>
  90         </tr>
  91         <tr>
  92           <td></td>
  93           <td>)</td>
  94           <td></td><td></td><td></td>
  95         </tr>
  96       </table>
  97 </div>
  98 <div class="memdoc">
  99
 100 <p>Create a map. </p>
 101 <p>Allocates a new map with the specified addressing capabilities. The memory is obtained from the Xenomai system heap.</p>
 102 <dl><dt><b>Parameters:</b></dt><dd>
 103   <table border="0" cellspacing="2" cellpadding="0">
 104     <tr><td valign="top"></td><td valign="top"><em>nkeys</em>&nbsp;</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>
 105     <tr><td valign="top"></td><td valign="top"><em>reserve</em>&nbsp;</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>
 106     <tr><td valign="top"></td><td valign="top"><em>offset</em>&nbsp;</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>
 107   </table>
 108   </dd>
 109 </dl>
 110 <dl class="return"><dt><b>Returns:</b></dt><dd>the address of the new map is returned on success; otherwise, NULL is returned if <em>nkeys</em> is invalid.</dd></dl>
 111 <p>Environments:</p>
 112 <p>This service can be called from:</p>
 113 <ul>
 114 <li>Kernel module initialization/cleanup code</li>
 115 <li>Kernel-based task</li>
 116 <li>User-space task</li>
 117 </ul>
 118 <p>Rescheduling: never. </p>
 119
 120 </div>
 121 </div>
 122 <a class="anchor" id="ga1a5b1c7a8e7966a2dd58404a0385aca8"></a><!-- doxytag: member="map.h::xnmap_delete" ref="ga1a5b1c7a8e7966a2dd58404a0385aca8" args="(xnmap_t *map)" -->
 123 <div class="memitem">
 124 <div class="memproto">
 125       <table class="memname">
 126         <tr>
 127           <td class="memname">void xnmap_delete </td>
 128           <td>(</td>
 129           <td class="paramtype">xnmap_t *&nbsp;</td>
 130           <td class="paramname"> <em>map</em></td>
 131           <td>&nbsp;)&nbsp;</td>
 132           <td></td>
 133         </tr>
 134       </table>
 135 </div>
 136 <div class="memdoc">
 137
 138 <p>Delete a map. </p>
 139 <p>Deletes a map, freeing any associated memory back to the Xenomai system heap.</p>
 140 <dl><dt><b>Parameters:</b></dt><dd>
 141   <table border="0" cellspacing="2" cellpadding="0">
 142     <tr><td valign="top"></td><td valign="top"><em>map</em>&nbsp;</td><td>The address of the map to delete.</td></tr>
 143   </table>
 144   </dd>
 145 </dl>
 146 <p>Environments:</p>
 147 <p>This service can be called from:</p>
 148 <ul>
 149 <li>Kernel module initialization/cleanup code</li>
 150 <li>Kernel-based task</li>
 151 <li>User-space task</li>
 152 </ul>
 153 <p>Rescheduling: never. </p>
 154
 155 </div>
 156 </div>
 157 <a class="anchor" id="gadc5657b93b294c935ac6864fac5fdaa4"></a><!-- doxytag: member="map.h::xnmap_enter" ref="gadc5657b93b294c935ac6864fac5fdaa4" args="(xnmap_t *map, int key, void *objaddr)" -->
 158 <div class="memitem">
 159 <div class="memproto">
 160       <table class="memname">
 161         <tr>
 162           <td class="memname">int xnmap_enter </td>
 163           <td>(</td>
 164           <td class="paramtype">xnmap_t *&nbsp;</td>
 165           <td class="paramname"> <em>map</em>, </td>
 166         </tr>
 167         <tr>
 168           <td class="paramkey"></td>
 169           <td></td>
 170           <td class="paramtype">int&nbsp;</td>
 171           <td class="paramname"> <em>key</em>, </td>
 172         </tr>
 173         <tr>
 174           <td class="paramkey"></td>
 175           <td></td>
 176           <td class="paramtype">void *&nbsp;</td>
 177           <td class="paramname"> <em>objaddr</em></td><td>&nbsp;</td>
 178         </tr>
 179         <tr>
 180           <td></td>
 181           <td>)</td>
 182           <td></td><td></td><td></td>
 183         </tr>
 184       </table>
 185 </div>
 186 <div class="memdoc">
 187
 188 <p>Index an object into a map. </p>
 189 <p>Insert a new object into the given map.</p>
 190 <dl><dt><b>Parameters:</b></dt><dd>
 191   <table border="0" cellspacing="2" cellpadding="0">
 192     <tr><td valign="top"></td><td valign="top"><em>map</em>&nbsp;</td><td>The address of the map to insert into.</td></tr>
 193     <tr><td valign="top"></td><td valign="top"><em>key</em>&nbsp;</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>
 194     <tr><td valign="top"></td><td valign="top"><em>objaddr</em>&nbsp;</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>
 195   </table>
 196   </dd>
 197 </dl>
 198 <dl class="return"><dt><b>Returns:</b></dt><dd>a valid key is returned on success, either <em>key</em> if reserved, or the next free key. Otherwise:</dd></dl>
 199 <ul>
 200 <li>-EEXIST is returned upon attempt to reserve a busy key.</li>
 201 </ul>
 202 <ul>
 203 <li>-ENOSPC when no more free key is available.</li>
 204 </ul>
 205 <p>Environments:</p>
 206 <p>This service can be called from:</p>
 207 <ul>
 208 <li>Kernel module initialization/cleanup code</li>
 209 <li>Interrupt service routine</li>
 210 <li>Kernel-based task</li>
 211 <li>User-space task</li>
 212 </ul>
 213 <p>Rescheduling: never. </p>
 214
 215 </div>
 216 </div>
 217 <a class="anchor" id="ga52a2727670d06e52b9b73b0c2c1d60d7"></a><!-- doxytag: member="map.h::xnmap_fetch" ref="ga52a2727670d06e52b9b73b0c2c1d60d7" args="(xnmap_t *map, int key)" -->
 218 <div class="memitem">
 219 <div class="memproto">
 220       <table class="memname">
 221         <tr>
 222           <td class="memname">void xnmap_fetch </td>
 223           <td>(</td>
 224           <td class="paramtype">xnmap_t *&nbsp;</td>
 225           <td class="paramname"> <em>map</em>, </td>
 226         </tr>
 227         <tr>
 228           <td class="paramkey"></td>
 229           <td></td>
 230           <td class="paramtype">int&nbsp;</td>
 231           <td class="paramname"> <em>key</em></td><td>&nbsp;</td>
 232         </tr>
 233         <tr>
 234           <td></td>
 235           <td>)</td>
 236           <td></td><td></td><td><code> [inline, static]</code></td>
 237         </tr>
 238       </table>
 239 </div>
 240 <div class="memdoc">
 241
 242 <p>Search an object into a map. </p>
 243 <p>Retrieve an object reference from the given map by its index key.</p>
 244 <dl><dt><b>Parameters:</b></dt><dd>
 245   <table border="0" cellspacing="2" cellpadding="0">
 246     <tr><td valign="top"></td><td valign="top"><em>map</em>&nbsp;</td><td>The address of the map to retrieve from.</td></tr>
 247     <tr><td valign="top"></td><td valign="top"><em>key</em>&nbsp;</td><td>The key to be searched for in the map index.</td></tr>
 248   </table>
 249   </dd>
 250 </dl>
 251 <dl class="return"><dt><b>Returns:</b></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>
 252 <p>Environments:</p>
 253 <p>This service can be called from:</p>
 254 <ul>
 255 <li>Kernel module initialization/cleanup code</li>
 256 <li>Interrupt service routine</li>
 257 <li>Kernel-based task</li>
 258 <li>User-space task</li>
 259 </ul>
 260 <p>Rescheduling: never. </p>
 261
 262 </div>
 263 </div>
 264 <a class="anchor" id="ga651ded315d1eec00d1e661e52ce4a10e"></a><!-- doxytag: member="map.h::xnmap_fetch_nocheck" ref="ga651ded315d1eec00d1e661e52ce4a10e" args="(xnmap_t *map, int key)" -->
 265 <div class="memitem">
 266 <div class="memproto">
 267       <table class="memname">
 268         <tr>
 269           <td class="memname">void xnmap_fetch_nocheck </td>
 270           <td>(</td>
 271           <td class="paramtype">xnmap_t *&nbsp;</td>
 272           <td class="paramname"> <em>map</em>, </td>
 273         </tr>
 274         <tr>
 275           <td class="paramkey"></td>
 276           <td></td>
 277           <td class="paramtype">int&nbsp;</td>
 278           <td class="paramname"> <em>key</em></td><td>&nbsp;</td>
 279         </tr>
 280         <tr>
 281           <td></td>
 282           <td>)</td>
 283           <td></td><td></td><td><code> [inline, static]</code></td>
 284         </tr>
 285       </table>
 286 </div>
 287 <div class="memdoc">
 288
 289 <p>Search an object into a map - unchecked form. </p>
 290 <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>
 291 <dl><dt><b>Parameters:</b></dt><dd>
 292   <table border="0" cellspacing="2" cellpadding="0">
 293     <tr><td valign="top"></td><td valign="top"><em>map</em>&nbsp;</td><td>The address of the map to retrieve from.</td></tr>
 294     <tr><td valign="top"></td><td valign="top"><em>key</em>&nbsp;</td><td>The key to be searched for in the map index.</td></tr>
 295   </table>
 296   </dd>
 297 </dl>
 298 <dl class="return"><dt><b>Returns:</b></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>
 299 <p>Environments:</p>
 300 <p>This service can be called from:</p>
 301 <ul>
 302 <li>Kernel module initialization/cleanup code</li>
 303 <li>Interrupt service routine</li>
 304 <li>Kernel-based task</li>
 305 <li>User-space task</li>
 306 </ul>
 307 <p>Rescheduling: never. </p>
 308
 309 </div>
 310 </div>
 311 <a class="anchor" id="ga06ec1012c075be6dbbadd2d88220abf5"></a><!-- doxytag: member="map.h::xnmap_remove" ref="ga06ec1012c075be6dbbadd2d88220abf5" args="(xnmap_t *map, int key)" -->
 312 <div class="memitem">
 313 <div class="memproto">
 314       <table class="memname">
 315         <tr>
 316           <td class="memname">int xnmap_remove </td>
 317           <td>(</td>
 318           <td class="paramtype">xnmap_t *&nbsp;</td>
 319           <td class="paramname"> <em>map</em>, </td>
 320         </tr>
 321         <tr>
 322           <td class="paramkey"></td>
 323           <td></td>
 324           <td class="paramtype">int&nbsp;</td>
 325           <td class="paramname"> <em>key</em></td><td>&nbsp;</td>
 326         </tr>
 327         <tr>
 328           <td></td>
 329           <td>)</td>
 330           <td></td><td></td><td></td>
 331         </tr>
 332       </table>
 333 </div>
 334 <div class="memdoc">
 335
 336 <p>Remove an object reference from a map. </p>
 337 <p>Removes an object reference from the given map, releasing the associated key.</p>
 338 <dl><dt><b>Parameters:</b></dt><dd>
 339   <table border="0" cellspacing="2" cellpadding="0">
 340     <tr><td valign="top"></td><td valign="top"><em>map</em>&nbsp;</td><td>The address of the map to remove from.</td></tr>
 341     <tr><td valign="top"></td><td valign="top"><em>key</em>&nbsp;</td><td>The key the object reference to be removed is indexed on.</td></tr>
 342   </table>
 343   </dd>
 344 </dl>
 345 <dl class="return"><dt><b>Returns:</b></dt><dd>0 is returned on success. Otherwise:</dd></dl>
 346 <ul>
 347 <li>-ESRCH is returned if <em>key</em> is invalid.</li>
 348 </ul>
 349 <p>Environments:</p>
 350 <p>This service can be called from:</p>
 351 <ul>
 352 <li>Kernel module initialization/cleanup code</li>
 353 <li>Interrupt service routine</li>
 354 <li>Kernel-based task</li>
 355 <li>User-space task</li>
 356 </ul>
 357 <p>Rescheduling: never. </p>
 358
 359 </div>
 360 </div>
 361 </div>
 362 <hr class="footer"/><address class="footer"><small>Generated on Wed Nov 2 2011 18:01:09 for Xenomai API by&nbsp;
 363 <a href="http://www.doxygen.org/index.html">
 364 <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.1 </small></address>
 365 </body>
 366 </html>