1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
<HTML><HEAD><TITLE>Buffer Class</TITLE></HEAD>
<BODY bgcolor="#ffffff">
<H1>Buffer Class Reference</H1>
<p>
[<A HREF="index.html">APE Index</A>] [<A HREF="hier.html">APE Hierarchy</A>]
[<A HREF="header-list.html">Headers</A>]
</p>
<HR>
<P>Producer/Consumer buffer for use between threads. <a href="#short">More...</a></P>
<P>
<code>
#include <<a href="thread-h.html">thread.h</a>>
</code>
</P>
<H2>Public Members</H2>
<UL>
<LI> <b><a href="#ref0">Buffer</a></b> (size_t capacity)
</LI>
<LI>virtual <b><a href="#ref1">~Buffer</a></b> ()
</LI>
<LI>inline size_t <b><a href="#ref2">getSize</a></b> (void)
</LI>
<LI>inline size_t <b><a href="#ref3">getUsed</a></b> (void)
</LI>
<LI>int <b><a href="#ref4">Wait</a></b> (void *buf)
</LI>
<LI>int <b><a href="#ref5">Post</a></b> (void *buf)
</LI>
<LI>int <b><a href="#ref6">Peek</a></b> (void *buf)
</LI>
</UL>
<H2>Protected Members</H2>
<UL>
<LI>virtual int <b><a href="#ref7">OnPeek</a></b> (void *buf)
</LI>
<LI>virtual int <b><a href="#ref8">OnWait</a></b> (void *buf)
</LI>
<LI>virtual int <b><a href="#ref9">OnPost</a></b> (void *buf)
</LI>
</UL>
<HR>
<H2><a name="short">Detailed Description</a></H2>
<P>
The buffer class represents an IPC service that is built upon a buffer
of fixed capacity that can be used to transfer objects between one or
more producer and consumer threads. Producer threads post objects
into the buffer, and consumer threads wait for and receive objects from
the buffer. Semaphores are used to to block the buffer from overflowing
and indicate when there is data available, and mutexes are used to protect
multiple consumers and producer threads from stepping over each other.
The buffer class is an abstract class in that the actual data being
buffered is not directly specified within the buffer class itself. The
buffer class should be used as a base class for a class that actually
impliments buffering and which may be aware of the data types actually
are being buffered. A template class could be created based on buffer
for this purpose. Another possibility is to create a class derived
from both Thread and Buffer which can be used to implement message passing
threads.
</P><HR>
<H3><b> <a name="ref0"></a><a name="Buffer">Buffer</a>(size_t capacity) </b><code>[public]</code></H3>
<p>Create a buffer object of known capacity.
</p>
<dl><dt><b>Parameters</b>:<dd>
<table width="100%" border="0">
<tr><td align="left" valign="top">
capcity</td><td align="left" valign="top">
is the integer capacity of the buffer.</td></tr>
</table>
</dl>
<H3><b> <a name="ref1"></a><a name="~Buffer">~Buffer</a>() </b><code>[public virtual]</code></H3>
<p>In derived functions, may be used to free the actual memory
used to hold buffered data.
</p>
<H3><b>inline size_t <a name="ref2"></a><a name="getSize">getSize</a>(void) </b><code>[public]</code></H3>
<p>Return the capacity of the buffer as specified at creation.
</p>
<dl><dt><b>Returns</b>:<dd>
size of buffer.</dl>
<H3><b>inline size_t <a name="ref3"></a><a name="getUsed">getUsed</a>(void) </b><code>[public]</code></H3>
<p>Return the current capacity in use for the buffer. Free space
is technically getSize() - getUsed().
</p>
<dl><dt><b>Returns</b>:<dd>
integer used capacity of the buffer.</dl>
<dl><dt><b>See Also</b>:<dd><a href="Buffer.html#getSize">getSize</a></dl>
<H3><b>int <a name="ref4"></a><a name="Wait">Wait</a>(void *buf) </b><code>[public]</code></H3>
<p>Let one or more threads wait for an object to become available
in the buffer. The waiting thread(s) will wait forever if no
object is ever placed into the buffer.
</p><p>
</p>
<dl><dt><b>Parameters</b>:<dd>
<table width="100%" border="0">
<tr><td align="left" valign="top">
buf</td><td align="left" valign="top">
pointer to store object retrieved from the buffer.</td></tr>
</table>
</dl>
<dl><dt><b>Returns</b>:<dd>
size of object passed by buffer in bytes.</dl>
<H3><b>int <a name="ref5"></a><a name="Post">Post</a>(void *buf) </b><code>[public]</code></H3>
<p>Post an object into the buffer and enable a waiting thread to
receive it.
</p><p>
</p>
<dl><dt><b>Parameters</b>:<dd>
<table width="100%" border="0">
<tr><td align="left" valign="top">
buf</td><td align="left" valign="top">
pointer to object to store in the buffer.</td></tr>
</table>
</dl>
<dl><dt><b>Returns</b>:<dd>
size of object posted in bytes.</dl>
<H3><b>int <a name="ref6"></a><a name="Peek">Peek</a>(void *buf) </b><code>[public]</code></H3>
<p>Peek at the current content (first object) in the buffer.
</p><p>
</p>
<dl><dt><b>Parameters</b>:<dd>
<table width="100%" border="0">
<tr><td align="left" valign="top">
buf</td><td align="left" valign="top">
pointer to store object found in the buffer.</td></tr>
</table>
</dl>
<dl><dt><b>Returns</b>:<dd>
size of object in the buffer.</dl>
<H3><b>int <a name="ref7"></a><a name="OnPeek">OnPeek</a>(void *buf) </b><code>[protected virtual]</code></H3>
<p>Invoke derived class buffer peeking method.
</p>
<dl><dt><b>Parameters</b>:<dd>
<table width="100%" border="0">
<tr><td align="left" valign="top">
buf</td><td align="left" valign="top">
pointer to copy contents of head of buffer to.</td></tr>
</table>
</dl>
<dl><dt><b>Returns</b>:<dd>
size of object found.</dl>
<H3><b>int <a name="ref8"></a><a name="OnWait">OnWait</a>(void *buf) </b><code>[protected virtual]</code></H3>
<p>Invoke derived class object request from buffer.
</p>
<dl><dt><b>Parameters</b>:<dd>
<table width="100%" border="0">
<tr><td align="left" valign="top">
buf</td><td align="left" valign="top">
pointer to hold object returned from the buffer.</td></tr>
</table>
</dl>
<dl><dt><b>Returns</b>:<dd>
size of object returned.</dl>
<H3><b>int <a name="ref9"></a><a name="OnPost">OnPost</a>(void *buf) </b><code>[protected virtual]</code></H3>
<p>Invoke derived class posting of object to buffer.
</p>
<dl><dt><b>Parameters</b>:<dd>
<table width="100%" border="0">
<tr><td align="left" valign="top">
buf</td><td align="left" valign="top">
pointer to object being posted to the buffer.</td></tr>
</table>
</dl>
<dl><dt><b>Returns</b>:<dd>
size of object posted.</dl>
<HR>
<TABLE WIDTH="100%"><TR><TD ALIGN="left" VALIGN="top">
<UL><LI><I>Author</I>: David Sugar <dyfet@ostel.com> </LI>
<LI>Documentation generated by dyfet@home.sys on Thu Dec 16 09:54:26 EST 1999
</LI>
</UL></TD><TD ALIGN="RIGHT" VALIGN="TOP">
<b>K</b><i>doc</i>
</TD>
</TR></TABLE></BODY></HTML>
|
