Project

General

Profile

Statistics
| Revision:

root / trunk / docs / libdragonfly / ring__buffer_8h.html @ 241

History | View | Annotate | Download (17.8 KB)

1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
3
<title>libdragonfly: ring_buffer.h File Reference</title>
4
<link href="doxygen.css" rel="stylesheet" type="text/css">
5
<link href="tabs.css" rel="stylesheet" type="text/css">
6
</head><body>
7
<!-- Generated by Doxygen 1.5.3 -->
8
<div class="tabs">
9
  <ul>
10
    <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
11
    <li><a href="modules.html"><span>Modules</span></a></li>
12
    <li class="current"><a href="files.html"><span>Files</span></a></li>
13
    <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
14
  </ul>
15
</div>
16
<h1>ring_buffer.h File Reference</h1>Ring Buffer. <a href="#_details">More...</a>
17
<p>
18

    
19
<p>
20
<a href="ring__buffer_8h-source.html">Go to the source code of this file.</a><table border="0" cellpadding="0" cellspacing="0">
21
<tr><td></td></tr>
22
<tr><td colspan="2"><br><h2>Defines</h2></td></tr>
23
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#883368e450d3596622905053d3b3ab83">RING_BUFFER_NEW</a>(struct_name, size, type,...)</td></tr>
24

    
25
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Creates the struct for a new ring buffer. This just expands to a structure definition and thus should be invoked in the global context.  <a href="#883368e450d3596622905053d3b3ab83"></a><br></td></tr>
26
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#3c186ab6ff12fa96c18f6d064720cc2c">RING_BUFFER_INIT</a>(buf, size)</td></tr>
27

    
28
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Initializes the ring buffer, setting its size to the correct value.  <a href="#3c186ab6ff12fa96c18f6d064720cc2c"></a><br></td></tr>
29
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#0ae5ca959a3b05583623551cc287a534">RING_BUFFER_CLEAR</a>(buf)</td></tr>
30

    
31
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Sets the specified ring buffer to be empty.  <a href="#0ae5ca959a3b05583623551cc287a534"></a><br></td></tr>
32
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#19daf3026b69a26bb3d383b14ae90e23">RING_BUFFER_EMPTY</a>(buf)&nbsp;&nbsp;&nbsp;((buf).start == (buf).end)</td></tr>
33

    
34
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Returns true if the ring buffer specified is empty.  <a href="#19daf3026b69a26bb3d383b14ae90e23"></a><br></td></tr>
35
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#2ed153688dc60c5503f2f7fdd2b73a4a">RING_BUFFER_FULL</a>(buf)&nbsp;&nbsp;&nbsp;(((buf).end + 1) % (buf).buffer_size == (buf).start)</td></tr>
36

    
37
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Returns true if the ring buffer specified is full.  <a href="#2ed153688dc60c5503f2f7fdd2b73a4a"></a><br></td></tr>
38
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#7708daab49219e2fd35534bc9cd15245">RING_BUFFER_ADD</a>(buf, val)</td></tr>
39

    
40
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Adds val to ring buffer buf. Note that val must be of the type used in creating the ring buffer to prevent the compiler from spewing confusing errors. Also, this assumes that the ring buffer is not full.  <a href="#7708daab49219e2fd35534bc9cd15245"></a><br></td></tr>
41
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#4a0f9de5ac14f60d678cda392921a629">RING_BUFFER_REMOVE</a>(buf, val_ret)</td></tr>
42

    
43
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Removes the value at the head of the ring buffer and puts it in val_ret. Note that val_ret must be the same type used in creating the ring buffer to prevent the compiler from spewing confusing errors. Also, this assumes that the ring buffer is not empty.  <a href="#4a0f9de5ac14f60d678cda392921a629"></a><br></td></tr>
44
<tr><td class="memItemLeft" nowrap align="right" valign="top">#define&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="ring__buffer_8h.html#6cb5596d0d7edccd628aca097f088f91">RING_BUFFER_PEEK</a>(buf, val_ret)</td></tr>
45

    
46
<tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">Checks the value at the head of the ring buffer without removing it and puts it into val_ret. Note that val_ret must be the same type used in creating the ring buffer to prevent the compiler from spewing confusing errors. Also, this assumes that the ring buffer is not empty.  <a href="#6cb5596d0d7edccd628aca097f088f91"></a><br></td></tr>
47
</table>
48
<hr><a name="_details"></a><h2>Detailed Description</h2>
49
Ring Buffer. 
50
<p>
51
Copyright (c) 2007 Colony Project<p>
52
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:<p>
53
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.<p>
54
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.<p>
55
Include macros to create a ring buffer. Originally written for 15-410. Modified for use in ATMega128 serial driver<p>
56
<dl class="author" compact><dt><b>Author:</b></dt><dd>Cornell Wright (cgwright) <p>
57
Jason P. Winters (jpwinter) </dd></dl>
58
<hr><h2>Define Documentation</h2>
59
<a class="anchor" name="7708daab49219e2fd35534bc9cd15245"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_ADD" ref="7708daab49219e2fd35534bc9cd15245" args="(buf, val)" -->
60
<div class="memitem">
61
<div class="memproto">
62
      <table class="memname">
63
        <tr>
64
          <td class="memname">#define RING_BUFFER_ADD          </td>
65
          <td>(</td>
66
          <td class="paramtype">buf,         <tr>
67
          <td class="paramkey"></td>
68
          <td></td>
69
          <td class="paramtype">val&nbsp;</td>
70
          <td class="paramname">          </td>
71
          <td>&nbsp;)&nbsp;</td>
72
          <td width="100%"></td>
73
        </tr>
74
      </table>
75
</div>
76
<div class="memdoc">
77

    
78
<p>
79
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keywordflow">do</span> {                                                            \
80
                (buf).queue[(buf).end] = val;   \
81
                (buf).end = ((buf).end + 1) % (buf).buffer_size;        \
82
        } <span class="keywordflow">while</span> (0)
83
</pre></div>Adds val to ring buffer buf. Note that val must be of the type used in creating the ring buffer to prevent the compiler from spewing confusing errors. Also, this assumes that the ring buffer is not full. 
84
<p>
85
<dl compact><dt><b>Parameters:</b></dt><dd>
86
  <table border="0" cellspacing="2" cellpadding="0">
87
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The ring buffer to add to. </td></tr>
88
    <tr><td valign="top"></td><td valign="top"><em>val</em>&nbsp;</td><td>The value to add. </td></tr>
89
  </table>
90
</dl>
91

    
92
</div>
93
</div><p>
94
<a class="anchor" name="0ae5ca959a3b05583623551cc287a534"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_CLEAR" ref="0ae5ca959a3b05583623551cc287a534" args="(buf)" -->
95
<div class="memitem">
96
<div class="memproto">
97
      <table class="memname">
98
        <tr>
99
          <td class="memname">#define RING_BUFFER_CLEAR          </td>
100
          <td>(</td>
101
          <td class="paramtype">buf&nbsp;</td>
102
          <td class="paramname">          </td>
103
          <td>&nbsp;)&nbsp;</td>
104
          <td width="100%"></td>
105
        </tr>
106
      </table>
107
</div>
108
<div class="memdoc">
109

    
110
<p>
111
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keywordflow">do</span> {                                            \
112
                (buf).start = 0;                \
113
                (buf).end = 0;                  \
114
        } <span class="keywordflow">while</span> (0)
115
</pre></div>Sets the specified ring buffer to be empty. 
116
<p>
117
<dl compact><dt><b>Parameters:</b></dt><dd>
118
  <table border="0" cellspacing="2" cellpadding="0">
119
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The ring buffer to make empty. </td></tr>
120
  </table>
121
</dl>
122

    
123
</div>
124
</div><p>
125
<a class="anchor" name="19daf3026b69a26bb3d383b14ae90e23"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_EMPTY" ref="19daf3026b69a26bb3d383b14ae90e23" args="(buf)" -->
126
<div class="memitem">
127
<div class="memproto">
128
      <table class="memname">
129
        <tr>
130
          <td class="memname">#define RING_BUFFER_EMPTY          </td>
131
          <td>(</td>
132
          <td class="paramtype">buf&nbsp;</td>
133
          <td class="paramname">          </td>
134
          <td>&nbsp;)&nbsp;</td>
135
          <td width="100%">&nbsp;&nbsp;&nbsp;((buf).start == (buf).end)</td>
136
        </tr>
137
      </table>
138
</div>
139
<div class="memdoc">
140

    
141
<p>
142
Returns true if the ring buffer specified is empty. 
143
<p>
144
<dl compact><dt><b>Parameters:</b></dt><dd>
145
  <table border="0" cellspacing="2" cellpadding="0">
146
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The buffer to check emptiness of. </td></tr>
147
  </table>
148
</dl>
149

    
150
</div>
151
</div><p>
152
<a class="anchor" name="2ed153688dc60c5503f2f7fdd2b73a4a"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_FULL" ref="2ed153688dc60c5503f2f7fdd2b73a4a" args="(buf)" -->
153
<div class="memitem">
154
<div class="memproto">
155
      <table class="memname">
156
        <tr>
157
          <td class="memname">#define RING_BUFFER_FULL          </td>
158
          <td>(</td>
159
          <td class="paramtype">buf&nbsp;</td>
160
          <td class="paramname">          </td>
161
          <td>&nbsp;)&nbsp;</td>
162
          <td width="100%">&nbsp;&nbsp;&nbsp;(((buf).end + 1) % (buf).buffer_size == (buf).start)</td>
163
        </tr>
164
      </table>
165
</div>
166
<div class="memdoc">
167

    
168
<p>
169
Returns true if the ring buffer specified is full. 
170
<p>
171
<dl compact><dt><b>Parameters:</b></dt><dd>
172
  <table border="0" cellspacing="2" cellpadding="0">
173
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The buffer to check fullness of. </td></tr>
174
  </table>
175
</dl>
176

    
177
</div>
178
</div><p>
179
<a class="anchor" name="3c186ab6ff12fa96c18f6d064720cc2c"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_INIT" ref="3c186ab6ff12fa96c18f6d064720cc2c" args="(buf, size)" -->
180
<div class="memitem">
181
<div class="memproto">
182
      <table class="memname">
183
        <tr>
184
          <td class="memname">#define RING_BUFFER_INIT          </td>
185
          <td>(</td>
186
          <td class="paramtype">buf,         <tr>
187
          <td class="paramkey"></td>
188
          <td></td>
189
          <td class="paramtype">size&nbsp;</td>
190
          <td class="paramname">          </td>
191
          <td>&nbsp;)&nbsp;</td>
192
          <td width="100%"></td>
193
        </tr>
194
      </table>
195
</div>
196
<div class="memdoc">
197

    
198
<p>
199
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keywordflow">do</span> {                                                                            \
200
                (buf).buffer_size = size;                               \
201
        } <span class="keywordflow">while</span>(0)
202
</pre></div>Initializes the ring buffer, setting its size to the correct value. 
203
<p>
204
<dl compact><dt><b>Parameters:</b></dt><dd>
205
  <table border="0" cellspacing="2" cellpadding="0">
206
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The ring buffer to initialize.</td></tr>
207
    <tr><td valign="top"></td><td valign="top"><em>size</em>&nbsp;</td><td>The size of the ring buffer (in array elements) </td></tr>
208
  </table>
209
</dl>
210

    
211
</div>
212
</div><p>
213
<a class="anchor" name="883368e450d3596622905053d3b3ab83"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_NEW" ref="883368e450d3596622905053d3b3ab83" args="(struct_name, size, type,...)" -->
214
<div class="memitem">
215
<div class="memproto">
216
      <table class="memname">
217
        <tr>
218
          <td class="memname">#define RING_BUFFER_NEW          </td>
219
          <td>(</td>
220
          <td class="paramtype">struct_name,         <tr>
221
          <td class="paramkey"></td>
222
          <td></td>
223
          <td class="paramtype">size,         <tr>
224
          <td class="paramkey"></td>
225
          <td></td>
226
          <td class="paramtype">type,         <tr>
227
          <td class="paramkey"></td>
228
          <td></td>
229
          <td class="paramtype"> <em>...</em>&nbsp;</td>
230
          <td class="paramname">          </td>
231
          <td>&nbsp;)&nbsp;</td>
232
          <td width="100%"></td>
233
        </tr>
234
      </table>
235
</div>
236
<div class="memdoc">
237

    
238
<p>
239
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keyword">struct </span>struct_name {    \
240
                type queue[size];       \
241
                uint8_t start;                  \
242
                uint8_t end;                    \
243
                uint8_t buffer_size;                    \
244
        } __VA_ARGS__
245
</pre></div>Creates the struct for a new ring buffer. This just expands to a structure definition and thus should be invoked in the global context. 
246
<p>
247
<dl compact><dt><b>Parameters:</b></dt><dd>
248
  <table border="0" cellspacing="2" cellpadding="0">
249
    <tr><td valign="top"></td><td valign="top"><em>struct_name</em>&nbsp;</td><td>Name of the ring buffer struct.</td></tr>
250
    <tr><td valign="top"></td><td valign="top"><em>size</em>&nbsp;</td><td>The size of the buffer to create.</td></tr>
251
    <tr><td valign="top"></td><td valign="top"><em>type</em>&nbsp;</td><td>The type of object that the queue is to hold.</td></tr>
252
    <tr><td valign="top"></td><td valign="top"><em>...</em>&nbsp;</td><td>Name or names of the instance or instances of the ring buffer(s) to be created. </td></tr>
253
  </table>
254
</dl>
255

    
256
</div>
257
</div><p>
258
<a class="anchor" name="6cb5596d0d7edccd628aca097f088f91"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_PEEK" ref="6cb5596d0d7edccd628aca097f088f91" args="(buf, val_ret)" -->
259
<div class="memitem">
260
<div class="memproto">
261
      <table class="memname">
262
        <tr>
263
          <td class="memname">#define RING_BUFFER_PEEK          </td>
264
          <td>(</td>
265
          <td class="paramtype">buf,         <tr>
266
          <td class="paramkey"></td>
267
          <td></td>
268
          <td class="paramtype">val_ret&nbsp;</td>
269
          <td class="paramname">          </td>
270
          <td>&nbsp;)&nbsp;</td>
271
          <td width="100%"></td>
272
        </tr>
273
      </table>
274
</div>
275
<div class="memdoc">
276

    
277
<p>
278
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keywordflow">do</span> { \
279
    (val_ret) = (buf).queue[(buf).start]; \
280
  } <span class="keywordflow">while</span>(0)
281
</pre></div>Checks the value at the head of the ring buffer without removing it and puts it into val_ret. Note that val_ret must be the same type used in creating the ring buffer to prevent the compiler from spewing confusing errors. Also, this assumes that the ring buffer is not empty. 
282
<p>
283
<dl compact><dt><b>Parameters:</b></dt><dd>
284
  <table border="0" cellspacing="2" cellpadding="0">
285
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The ring buffer to check from </td></tr>
286
    <tr><td valign="top"></td><td valign="top"><em>val_ret</em>&nbsp;</td><td>where to put the value checked from the head of the ring </td></tr>
287
  </table>
288
</dl>
289

    
290
</div>
291
</div><p>
292
<a class="anchor" name="4a0f9de5ac14f60d678cda392921a629"></a><!-- doxytag: member="ring_buffer.h::RING_BUFFER_REMOVE" ref="4a0f9de5ac14f60d678cda392921a629" args="(buf, val_ret)" -->
293
<div class="memitem">
294
<div class="memproto">
295
      <table class="memname">
296
        <tr>
297
          <td class="memname">#define RING_BUFFER_REMOVE          </td>
298
          <td>(</td>
299
          <td class="paramtype">buf,         <tr>
300
          <td class="paramkey"></td>
301
          <td></td>
302
          <td class="paramtype">val_ret&nbsp;</td>
303
          <td class="paramname">          </td>
304
          <td>&nbsp;)&nbsp;</td>
305
          <td width="100%"></td>
306
        </tr>
307
      </table>
308
</div>
309
<div class="memdoc">
310

    
311
<p>
312
<b>Value:</b><div class="fragment"><pre class="fragment"><span class="keywordflow">do</span> {    \
313
                (val_ret) = (buf).queue[(buf).start];   \
314
                (buf).start = ((buf).start + 1) % (buf).buffer_size;    \
315
        } <span class="keywordflow">while</span> (0)
316
</pre></div>Removes the value at the head of the ring buffer and puts it in val_ret. Note that val_ret must be the same type used in creating the ring buffer to prevent the compiler from spewing confusing errors. Also, this assumes that the ring buffer is not empty. 
317
<p>
318
<dl compact><dt><b>Parameters:</b></dt><dd>
319
  <table border="0" cellspacing="2" cellpadding="0">
320
    <tr><td valign="top"></td><td valign="top"><em>buf</em>&nbsp;</td><td>The ring buffer to remove from. </td></tr>
321
    <tr><td valign="top"></td><td valign="top"><em>val_ret</em>&nbsp;</td><td>Where to put the value removed from the head of the ring buffer. </td></tr>
322
  </table>
323
</dl>
324

    
325
</div>
326
</div><p>
327
<hr size="1"><address style="text-align: right;"><small>Generated on Thu Nov 8 23:15:40 2007 for libdragonfly by&nbsp;
328
<a href="http://www.doxygen.org/index.html">
329
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
330
</body>
331
</html>