casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
36 
37 
38 namespace 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 
94 class FilebufIO: public ByteIO
95 {
96 public:
97  // Default constructor.
98  // A stream can be attached using the attach function.
99  FilebufIO();
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.
147  uInt bufferSize() const
148  { return itsBufSize; }
149 
150 protected:
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.
158  void fillSeekable();
159 
160  // Reset the position pointer to the given value. It returns the
161  // new position.
162  virtual Int64 doSeek (Int64 offset, ByteIO::SeekOption);
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 
183 private:
187  int itsFile;
188  Int64 itsBufSize; // the buffer size
189  Int64 itsBufLen; // the current buffer length used
190  char* itsBuffer;
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.
200  FilebufIO& operator= (const FilebufIO& that);
201 };
202 
203 
204 } //# NAMESPACE CASACORE - END
205 
206 #endif
virtual Bool isReadable() const
Is the IO stream readable?
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
void attach(int fd, uInt bufferSize=16384)
Attach to the given file descriptor.
virtual void flush()
Flush the current buffer.
Class for buffered IO on a file.
Definition: FilebufIO.h:94
Int64 readBlock(Int64 size, char *buf, Bool throwException)
Read a block from the stream at the current offset.
void fillSeekable()
Determine if the file is seekable.
SeekOption
Define the possible seek options.
Definition: ByteIO.h:82
FilebufIO & operator=(const FilebufIO &that)
Assignment, should not be used.
void writeBlock(Int64 size, const char *buf)
Write a block into the stream at the current offset.
size_t size() const
virtual Bool isSeekable() const
Is the IO stream seekable?
virtual Int64 read(Int64 size, void *buf, Bool throwException=True)
Read size bytes from the File.
void detach(Bool closeFile=False)
Detach the FILE.
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 setBuffer(Int64 bufSize)
Set a new buffer size.
Abstract base class for IO on a byte stream.
Definition: ByteIO.h:61
virtual Int64 doSeek(Int64 offset, ByteIO::SeekOption)
Reset the position pointer to the given value.
uInt bufferSize() const
Get the buffer size.
Definition: FilebufIO.h:147
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual String fileName() const
Get the file name of the file attached.
Int64 readBuffer(Int64 offset, char *buf, Int64 size, Bool throwException)
Read a buffer of given length from the file at given offset.
FilebufIO()
Default constructor.
const Bool False
Definition: aipstype.h:44
virtual Int64 length()
Get the length of the byte stream.
void writeBuffer(Int64 offset, const char *buf, Int64 size)
Write a buffer of given length into the file at given offset.
virtual void write(Int64 size, const void *buf)
Write the number of bytes.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
void fillRWFlags(int fd)
Determine if the file descriptor is readable and/or writable.
const Bool True
Definition: aipstype.h:43
unsigned int uInt
Definition: aipstype.h:51
virtual void resync()
Resync the file (i.e.
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42