casacore
DynBuffer.h
Go to the documentation of this file.
1//# DynBuffer.h: Store data in dynamically allocated buffers
2//# Copyright (C) 1993,1994,1995,1996
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: aips2-request@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25//#
26//# $Id$
27
28#ifndef CASA_DYNBUFFER_H
29#define CASA_DYNBUFFER_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/casa/Containers/Block.h>
34
35
36namespace casacore { //# NAMESPACE CASACORE - BEGIN
37
38// <summary>
39// Store data in dynamically allocated buffers
40// </summary>
41
42// <use visibility=export>
43// <reviewed reviewer="Friso Olnon" date="1995/03/16" tests="tDynBuffer" demos="">
44// </reviewed>
45
46// <synopsis>
47// DynBuffer allows one to store data in dynamically allocated buffers.
48// When a buffer is full, an additional buffer can be allocated and
49// "linked" to the existing one; so, the data may not be stored contiguously
50// You can loop through all the linked buffers and get their individual
51// addresses and sizes, so that you can access the data.
52// </synopsis>
53
54// <example>
55// Example (without exception handling):
56// <srcblock>
57// uInt nrOfValues, nrNeeded, nrAvailable;// nr of data values
58// float* pData = floatarr; // ptr to data to be handled
59// Char* pBuffer; // ptr to buffer
60//
61// DynBuffer buffer; // create buffer
62// buffer.allocstart(); // prepare for storing
63// nrNeeded = nrOfValues; // nr of values to store
64// // copy data into dynamic buffer
65// while (nrNeeded > 0) {
66// nrAvailable = buffer.alloc (nrNeeded, sizeof(float), pBuffer);
67// // get buffer space:
68// // room for nrAvailable values
69// memcpy (pBuffer, pData, nrAvailable*sizeof(float));
70// // copy that many data values
71// nrNeeded -= nrAvailable; // how much more needed?
72// pData += nrAvailable; // pointer to as yet unstored data
73// }
74// // Maybe store more values
75// .
76// .
77// // Retrieve all the data values from the buffers and write them
78// buffer.nextstart(); // goto buffer start
79// while (buffer.next (nrAvailable, pBuffer)) {
80// // get next buffer
81// write (fd, nrAvailable, pBuffer); // write data from that buffer
82// }
83// </srcblock>
84// </example>
85
86// <motivation>
87// This class is developed as an intermediate buffer for
88// class <linkto class=AipsIO>AipsIO</linkto>,
89// but it may serve other purposes as well.
90// </motivation>
91
93{
94public:
95
96 // Allocate a first buffer of the specified number of bytes
97 // (default 4096). When the allocation fails, an exception is thrown.
98 DynBuffer (uInt nrOfBytes=4096);
99
100 // Remove the whole buffer, i.e. the first buffer and all the
101 // buffers appended to it.
103
104 // Prepare for storing data (re-initialize the buffer)
105 void allocstart ();
106
107 // Allocate buffer space for <src>nrOfValues</src> values of size
108 // <src>valueSize</src> bytes, and return the pointer <src>ptr</src>
109 // to the buffer and the number of values that fit in the buffer.
110 //
111 // When not all values fit in the current buffer, new buffer space
112 // is added (probably non-contiguous). If that allocation fails an
113 // exception is thrown.
114 uInt alloc (uInt nrOfValues, uInt valueSize, Char*& ptr);
115
116 // Remove buffer <src>nrOfBuffer</src> and the buffers appended to it,
117 // and re-initialize the current buffer. By default we keep the first
118 // buffer (i.e. the one numbered 0).
119 //
120 // The idea is that you may want to free intermediate storage
121 // space taken up by data that you no longer need, and that the
122 // first buffer is often big enough to hold further data. So, you
123 // only remove the first buffer in special cases.
124 void remove (uInt nrOfBuffer=1);
125
126 // Prepare for data retrieval (set up for looping through the buffers).
127 void nextstart ();
128
129 // Get the pointer to the next buffer and its used length in bytes.
130 // The function returns a <src>False</src> value if there are no more
131 // buffers.
132 Bool next (uInt& usedLength, Char*& ptr);
133
134private:
135 // Get the next buffer for storing <src>nrOfValues</src> values of
136 // size <src>valueSize</src> bytes, and return the number of values
137 // that can be stored in the free space of that buffer (maybe less
138 // than <src>nrOfValues</src>).
139 //
140 // The new current buffer can be the present one (if it has free
141 // space), the next buffer already allocated (if there is one), or
142 // a newly allocated and linked-in buffer. If, in the last case,
143 // the allocation fails an exception is thrown.
144 uInt newbuf (uInt nrOfValues, uInt valueSize);
145
146
147 // size of 1st buffer and min. bufsize
149 // buffernr for next function
151 // current buffernr
153 // nr of buffers allocated
155 // size of Blocks
157 // used length per buffer
159 // total length per buffer
161 // pointer to buffer
163 // used length of current buffer
165 // total length of current buffer
167 // pointer to current buffer
169};
170
171
172//# Allocate buffer space for the nrOfValues values.
173//# Return pointer to the buffer and nr of values that fit in it.
174//# Use a more specialized function if not all values fit.
175//# In this way the function can be kept small and thus used inline.
176//# newbuf will seldom be required, unless large vectors are stored.
177inline uInt DynBuffer::alloc (uInt nrOfValues, uInt valueSize, Char*& ptr)
178{
179 uInt n = nrOfValues;
180 if (n*valueSize > curtotlen_p-curuselen_p) {
181 n = newbuf (nrOfValues, valueSize);
182 }
183 ptr = curbufptr_p + curuselen_p;
184 curuselen_p += n*valueSize;
185 return n;
186}
187
188
189
190} //# NAMESPACE CASACORE - END
191
192#endif
uInt alloc(uInt nrOfValues, uInt valueSize, Char *&ptr)
Allocate buffer space for nrOfValues values of size valueSize bytes, and return the pointer ptr to th...
Definition: DynBuffer.h:177
uInt bufsz_p
size of 1st buffer and min.
Definition: DynBuffer.h:148
Int nextbuf_p
buffernr for next function
Definition: DynBuffer.h:150
~DynBuffer()
Remove the whole buffer, i.e.
Char * curbufptr_p
pointer to current buffer
Definition: DynBuffer.h:168
Block< uInt > totlen_p
total length per buffer
Definition: DynBuffer.h:160
uInt newbuf(uInt nrOfValues, uInt valueSize)
Get the next buffer for storing nrOfValues values of size valueSize bytes, and return the number of v...
void remove(uInt nrOfBuffer=1)
Remove buffer nrOfBuffer and the buffers appended to it, and re-initialize the current buffer.
Int nrbuf_p
nr of buffers allocated
Definition: DynBuffer.h:154
Int maxnrbuf_p
size of Blocks
Definition: DynBuffer.h:156
Bool next(uInt &usedLength, Char *&ptr)
Get the pointer to the next buffer and its used length in bytes.
Int curbuf_p
current buffernr
Definition: DynBuffer.h:152
void allocstart()
Prepare for storing data (re-initialize the buffer)
DynBuffer(uInt nrOfBytes=4096)
Allocate a first buffer of the specified number of bytes (default 4096).
uInt curuselen_p
used length of current buffer
Definition: DynBuffer.h:164
PtrBlock< Char * > bufptr_p
pointer to buffer
Definition: DynBuffer.h:162
void nextstart()
Prepare for data retrieval (set up for looping through the buffers).
uInt curtotlen_p
total length of current buffer
Definition: DynBuffer.h:166
Block< uInt > uselen_p
used length per buffer
Definition: DynBuffer.h:158
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
char Char
Definition: aipstype.h:46