casacore
Loading...
Searching...
No Matches
FilebufIO.h
Go to the documentation of this file.
1//# FilebufIO.h: Class for buffered IO on a file
2//# Copyright (C) 1996,1997,1999,2001,2002
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_FILEBUFIO_H
29#define CASA_FILEBUFIO_H
30
31
32//# Includes
33#include <casacore/casa/aips.h>
34#include <casacore/casa/IO/ByteIO.h>
35#include <casacore/casa/BasicSL/String.h>
36
37
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40// <summary> Class for buffered IO on a file.</summary>
41
42// <use visibility=export>
43
44// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tByteIO" demos="">
45// </reviewed>
46
47// <prerequisite>
48// <li> <linkto class=ByteIO>ByteIO</linkto>
49// </prerequisite>
50
51// <synopsis>
52// This class is a specialization of class
53// <linkto class=ByteIO>ByteIO</linkto>.
54// This class is doing IO on a file in a buffered way to reduce the number
55// of file accesses as much as possible.
56// It is part of the entire IO framework. It can for
57// instance be used to store data in canonical format in a file
58// in an IO-efficient way
59// <br>
60// The buffer size is dynamic, so any time it can be set as needed.
61// <p>
62// It is also possible to construct a <src>FilebufIO</src> object
63// from a file descriptor (e.g. for a pipe or socket).
64// The constructor will determine automatically if the file is
65// readable, writable and seekable.
66// </synopsis>
67
68// <example>
69// This example shows how FilebufIO can be used with an fd.
70// It uses the fd for a regular file, which could be done in an easier
71// way using class <linkto class=RegularFileIO>RegularFileIO</linkto>.
72// However, when using pipes or sockets, this would be the only way.
73// <srcblock>
74// // Get a file descriptor for the file.
75// int fd = open ("file.name");
76// // Use that as the source of AipsIO (which will also use CanonicalIO).
77// FilebufIO fio (fd);
78// AipsIO stream (&fio);
79// // Read the data.
80// Int vali;
81// Bool valb;
82// stream >> vali >> valb;
83// </srcblock>
84// </example>
85
86// <motivation>
87// The stdio package was used, but it proved to be very slow on SOlaris.
88// After a seek the buffer was refreshed, which increased the number
89// of file accesses enormously.
90// Also the interaction between reads and writes in stdio was poor.
91// </motivation>
92
93
94class FilebufIO: public ByteIO
95{
96public:
97 // Default constructor.
98 // A stream can be attached using the attach function.
100
101 // Construct from the given file descriptor.
102 // Note that the destructor and the detach function implicitly close
103 // the file descriptor.
104 explicit FilebufIO (int fd, uInt bufferSize=16384);
105
106 // Attach to the given file descriptor.
107 // Note that the destructor and the detach function implicitly close
108 // the file descriptor.
109 void attach (int fd, uInt bufferSize=16384);
110
111 // The destructor closes the file when it was owned and opened and not
112 // closed yet.
113 virtual ~FilebufIO();
114
115 // Write the number of bytes.
116 virtual void write (Int64 size, const void* buf);
117
118 // Read <src>size</src> bytes from the File. Returns the number of bytes
119 // actually read. Will throw an exception (AipsError) if the requested
120 // number of bytes could not be read unless throwException is set to
121 // False. Will always throw an exception if the file is not readable or
122 // the system call returns an undocumented value.
123 virtual Int64 read (Int64 size, void* buf, Bool throwException=True);
124
125 // Flush the current buffer.
126 virtual void flush();
127
128 // Resync the file (i.e. empty the current buffer).
129 virtual void resync();
130
131 // Get the length of the byte stream.
132 virtual Int64 length();
133
134 // Is the IO stream readable?
135 virtual Bool isReadable() const;
136
137 // Is the IO stream writable?
138 virtual Bool isWritable() const;
139
140 // Is the IO stream seekable?
141 virtual Bool isSeekable() const;
142
143 // Get the file name of the file attached.
144 virtual String fileName() const;
145
146 // Get the buffer size.
148 { return itsBufSize; }
149
150protected:
151 // Detach the FILE. Close it when needed.
152 void detach (Bool closeFile=False);
153
154 // Determine if the file descriptor is readable and/or writable.
155 void fillRWFlags (int fd);
156
157 // Determine if the file is seekable.
159
160 // Reset the position pointer to the given value. It returns the
161 // new position.
163
164 // Set a new buffer size.
165 // If a buffer was already existing, flush and delete it.
166 void setBuffer (Int64 bufSize);
167
168 // Write a buffer of given length into the file at given offset.
169 void writeBuffer (Int64 offset, const char* buf, Int64 size);
170
171 // Read a buffer of given length from the file at given offset.
172 Int64 readBuffer (Int64 offset, char* buf, Int64 size,
173 Bool throwException);
174
175 // Write a block into the stream at the current offset.
176 // It is guaranteed that the block fits in a single buffer.
177 void writeBlock (Int64 size, const char* buf);
178
179 // Read a block from the stream at the current offset.
180 // It is guaranteed that the block fits in a single buffer.
181 Int64 readBlock (Int64 size, char* buf, Bool throwException);
182
183private:
188 Int64 itsBufSize; // the buffer size
189 Int64 itsBufLen; // the current buffer length used
191 Int64 itsBufOffset; // file offset of current buffer
192 Int64 itsOffset; // current file offset
193 Int64 itsSeekOffset; // offset last seeked
194 Bool itsDirty; // data written into current buffer?
195
196 // Copy constructor, should not be used.
197 FilebufIO (const FilebufIO& that);
198
199 // Assignment, should not be used.
201};
202
203
204} //# NAMESPACE CASACORE - END
205
206#endif
SeekOption
Define the possible seek options.
Definition ByteIO.h:82
virtual Bool isSeekable() const
Is the IO stream seekable?
uInt bufferSize() const
Get the buffer size.
Definition FilebufIO.h:147
Int64 readBlock(Int64 size, char *buf, Bool throwException)
Read a block from the stream at the current offset.
FilebufIO()
Default constructor.
void writeBuffer(Int64 offset, const char *buf, Int64 size)
Write a buffer of given length into the file at given offset.
void fillRWFlags(int fd)
Determine if the file descriptor is readable and/or writable.
Int64 readBuffer(Int64 offset, char *buf, Int64 size, Bool throwException)
Read a buffer of given length from the file at given offset.
void writeBlock(Int64 size, const char *buf)
Write a block into the stream at the current offset.
void setBuffer(Int64 bufSize)
Set a new buffer size.
virtual Bool isWritable() const
Is the IO stream writable?
virtual ~FilebufIO()
The destructor closes the file when it was owned and opened and not closed yet.
void attach(int fd, uInt bufferSize=16384)
Attach to the given file descriptor.
virtual Int64 length()
Get the length of the byte stream.
virtual String fileName() const
Get the file name of the file attached.
void detach(Bool closeFile=False)
Detach the FILE.
FilebufIO(const FilebufIO &that)
Copy constructor, should not be used.
virtual void resync()
Resync the file (i.e.
virtual Int64 read(Int64 size, void *buf, Bool throwException=True)
Read size bytes from the File.
virtual void write(Int64 size, const void *buf)
Write the number of bytes.
FilebufIO & operator=(const FilebufIO &that)
Assignment, should not be used.
void fillSeekable()
Determine if the file is seekable.
virtual Bool isReadable() const
Is the IO stream readable?
virtual Int64 doSeek(Int64 offset, ByteIO::SeekOption)
Reset the position pointer to the given value.
FilebufIO(int fd, uInt bufferSize=16384)
Construct from the given file descriptor.
virtual void flush()
Flush the current buffer.
String: the storage and methods of handling collections of characters.
Definition String.h:225
this file contains all the compiler specific defines
Definition mainpage.dox:28
const Bool False
Definition aipstype.h:44
unsigned int uInt
Definition aipstype.h:51
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition aipsxtype.h:38
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
const Bool True
Definition aipstype.h:43