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
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
.TH "Buffer" 3 "19 Jul 2003" "CommonC++" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Buffer \- 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/Consumer buffer for use between threads.
.SH SYNOPSIS
.br
.PP
\fC#include <thread.h>\fP
.PP
Inherited by \fBFixedBuffer\fP.
.PP
.SS "Public Methods"
.in +1c
.ti -1c
.RI "\fBBuffer\fP (size_t capacity)"
.br
.RI "\fICreate a buffer object of known capacity.\fP"
.ti -1c
.RI "virtual \fB~Buffer\fP ()"
.br
.RI "\fIIn derived functions, may be used to free the actual memory used to hold buffered data.\fP"
.ti -1c
.RI "size_t \fBgetSize\fP (void)"
.br
.RI "\fIReturn the capacity of the buffer as specified at creation.\fP"
.ti -1c
.RI "size_t \fBgetUsed\fP (void)"
.br
.RI "\fIReturn the current capacity in use for the buffer.\fP"
.ti -1c
.RI "int \fBwait\fP (void *buf)"
.br
.RI "\fILet one or more threads wait for an object to become available in the buffer.\fP"
.ti -1c
.RI "int \fBpost\fP (void *buf)"
.br
.RI "\fIPost an object into the buffer and enable a waiting thread to receive it.\fP"
.ti -1c
.RI "int \fBpeek\fP (void *buf)"
.br
.RI "\fIPeek at the current content (first object) in the buffer.\fP"
.ti -1c
.RI "virtual bool \fBisValid\fP (void)"
.br
.RI "\fINew virtual to test if buffer is a valid object.\fP"
.in -1c
.SS "Protected Methods"
.in +1c
.ti -1c
.RI "virtual int \fBonPeek\fP (void *buf)=0"
.br
.RI "\fIInvoke derived class buffer peeking method.\fP"
.ti -1c
.RI "virtual int \fBonWait\fP (void *buf)=0"
.br
.RI "\fIInvoke derived class object request from buffer.\fP"
.ti -1c
.RI "virtual int \fBonPost\fP (void *buf)=0"
.br
.RI "\fIInvoke derived class posting of object to buffer.\fP"
.in -1c
.SS "Related Functions"
(Note that these are not member functions.)
.in +1c
.ti -1c
.RI "int \fBget\fP (Buffer &b, void *o)"
.br
.ti -1c
.RI "int \fBput\fP (Buffer &b, void *o)"
.br
.ti -1c
.RI "int \fBpeek\fP (Buffer &b, void *o)"
.br
.in -1c
.SH "DETAILED DESCRIPTION"
.PP
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/Consumer buffer for use between threads.
.PP
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.
.PP
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 \fBThread\fP and Buffer which can be used to implement message passing threads.
.PP
\fBAuthor: \fP
.in +1c
David Sugar <dyfet@ostel.com>
.PP
.SH "CONSTRUCTOR & DESTRUCTOR DOCUMENTATION"
.PP
.SS "Buffer::Buffer (size_t capacity)"
.PP
Create a buffer object of known capacity.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIcapacity\fP\fP
is the integer capacity of the buffer.
.SS "virtual Buffer::~Buffer ()\fC [inline, virtual]\fP"
.PP
In derived functions, may be used to free the actual memory used to hold buffered data.
.PP
.SH "MEMBER FUNCTION DOCUMENTATION"
.PP
.SS "size_t Buffer::getSize (void)\fC [inline]\fP"
.PP
Return the capacity of the buffer as specified at creation.
.PP
\fBReturns: \fP
.in +1c
size of buffer.
.SS "size_t Buffer::getUsed (void)\fC [inline]\fP"
.PP
Return the current capacity in use for the buffer.
.PP
Free space is technically \fBgetSize()\fP - \fBgetUsed()\fP.
.PP
\fBReturns: \fP
.in +1c
integer used capacity of the buffer.
.PP
\fBSee also: \fP
.in +1c
\fBgetSize\fP
.SS "virtual bool Buffer::isValid (void)\fC [inline, virtual]\fP"
.PP
New virtual to test if buffer is a valid object.
.PP
\fBReturns: \fP
.in +1c
true if object is valid.
.PP
Reimplemented in \fBFixedBuffer\fP.
.SS "virtual int Buffer::onPeek (void * buf)\fC [protected, pure virtual]\fP"
.PP
Invoke derived class buffer peeking method.
.PP
\fBReturns: \fP
.in +1c
size of object found.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIbuf\fP\fP
pointer to copy contents of head of buffer to.
.PP
Implemented in \fBFixedBuffer\fP.
.SS "virtual int Buffer::onPost (void * buf)\fC [protected, pure virtual]\fP"
.PP
Invoke derived class posting of object to buffer.
.PP
\fBReturns: \fP
.in +1c
size of object posted.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIbuf\fP\fP
pointer to object being posted to the buffer.
.PP
Implemented in \fBFixedBuffer\fP.
.SS "virtual int Buffer::onWait (void * buf)\fC [protected, pure virtual]\fP"
.PP
Invoke derived class object request from buffer.
.PP
\fBReturns: \fP
.in +1c
size of object returned.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIbuf\fP\fP
pointer to hold object returned from the buffer.
.PP
Implemented in \fBFixedBuffer\fP.
.SS "int Buffer::peek (void * buf)"
.PP
Peek at the current content (first object) in the buffer.
.PP
\fBReturns: \fP
.in +1c
size of object in the buffer.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIbuf\fP\fP
pointer to store object found in the buffer.
.SS "int Buffer::post (void * buf)"
.PP
Post an object into the buffer and enable a waiting thread to receive it.
.PP
\fBReturns: \fP
.in +1c
size of object posted in bytes.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIbuf\fP\fP
pointer to object to store in the buffer.
.SS "int Buffer::wait (void * buf)"
.PP
Let one or more threads wait for an object to become available in the buffer.
.PP
The waiting thread(s) will wait forever if no object is ever placed into the buffer.
.PP
\fBReturns: \fP
.in +1c
size of object passed by buffer in bytes.
.PP
\fBParameters: \fP
.in +1c
.TP
\fB\fIbuf\fP\fP
pointer to store object retrieved from the buffer.
.SH "FRIENDS AND RELATED FUNCTION DOCUMENTATION"
.PP
.SS "int get (Buffer & b, void * o)\fC [related]\fP"
.PP
.SS "int peek (Buffer & b, void * o)\fC [related]\fP"
.PP
.SS "int put (Buffer & b, void * o)\fC [related]\fP"
.PP
.SH "AUTHOR"
.PP
Generated automatically by Doxygen for CommonC++ from the source code.
|
