casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
34 
35 
36 namespace 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 
92 class DynBuffer
93 {
94 public:
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.
102  ~DynBuffer ();
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 
134 private:
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.
177 inline 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
int Int
Definition: aipstype.h:50
Block< uInt > uselen_p
used length per buffer
Definition: DynBuffer.h:158
char Char
Definition: aipstype.h:46
uInt bufsz_p
size of 1st buffer and min.
Definition: DynBuffer.h:148
void nextstart()
Prepare for data retrieval (set up for looping through the buffers).
uInt curuselen_p
used length of current buffer
Definition: DynBuffer.h:164
uInt curtotlen_p
total length of current buffer
Definition: DynBuffer.h:166
~DynBuffer()
Remove the whole buffer, i.e.
Block< uInt > totlen_p
total length per buffer
Definition: DynBuffer.h:160
DynBuffer(uInt nrOfBytes=4096)
Allocate a first buffer of the specified number of bytes (default 4096).
uInt newbuf(uInt nrOfValues, uInt valueSize)
Get the next buffer for storing nrOfValues values of size valueSize bytes, and return the number of v...
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
void allocstart()
Prepare for storing data (re-initialize the buffer)
Int curbuf_p
current buffernr
Definition: DynBuffer.h:152
Store data in dynamically allocated buffers.
Definition: DynBuffer.h:92
Char * curbufptr_p
pointer to current buffer
Definition: DynBuffer.h:168
Int nrbuf_p
nr of buffers allocated
Definition: DynBuffer.h:154
Int maxnrbuf_p
size of Blocks
Definition: DynBuffer.h:156
Int nextbuf_p
buffernr for next function
Definition: DynBuffer.h:150
Bool next(uInt &usedLength, Char *&ptr)
Get the pointer to the next buffer and its used length in bytes.
unsigned int uInt
Definition: aipstype.h:51
PtrBlock< Char * > bufptr_p
pointer to buffer
Definition: DynBuffer.h:162
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42