casacore
MMapfdIO.h
Go to the documentation of this file.
1 //# MMapfdIO.h: Memory-mapped IO on a file descriptor
2 //#
3 //# Copyright (C) 2009
4 //# Associated Universities, Inc. Washington DC, USA.
5 //#
6 //# This library is free software; you can redistribute it and/or modify it
7 //# under the terms of the GNU Library General Public License as published by
8 //# the Free Software Foundation; either version 2 of the License, or (at your
9 //# option) any later version.
10 //#
11 //# This library is distributed in the hope that it will be useful, but WITHOUT
12 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
14 //# License for more details.
15 //#
16 //# You should have received a copy of the GNU Library General Public License
17 //# along with this library; if not, write to the Free Software Foundation,
18 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
19 //#
20 //# Correspondence concerning AIPS++ should be addressed as follows:
21 //# Internet email: aips2-request@nrao.edu.
22 //# Postal address: AIPS++ Project Office
23 //# National Radio Astronomy Observatory
24 //# 520 Edgemont Road
25 //# Charlottesville, VA 22903-2475 USA
26 //#
27 //# $Id$
28 
29 #ifndef CASA_MMAPFDIO_H
30 #define CASA_MMAPFDIO_H
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/IO/FiledesIO.h>
35 #include <casacore/casa/OS/RegularFile.h>
36 
37 namespace casacore
38 {
39 
40 // <summary>
41 // Memory-mapped IO on a file.
42 // </summary>
43 
44 // <synopsis>
45 // Memory-mapped IO lets the OS take care of caching file segments.
46 // This is particularly useful for the Tiled Storage Manager which keeps a
47 // cache of tiles. When using memory-mapped IO it does not need to do that
48 // anymore.
49 //
50 // On 32-bit systems its use is limited because for large files the 4 GB
51 // memory space is insufficient. However, for 64-bit systems the memory
52 // space is large enough to make use of it.
53 //
54 // In the general case there is direct access to the mapped file space.
55 // The read and write methods copies the data into/from a buffer.
56 // However, to avoid the copying it is possible to get a direct pointer
57 // to the mapped data. This should be used with care, because writing to
58 // it will cause a segmentation if the file is readonly. If the file is
59 // writable, writing into the mapped data segment means changing the file
60 // contents.
61 // </synopsis>
62 
63 class MMapfdIO: public FiledesIO
64 {
65 public:
66  // Default constructor.
67  // A file can be memory-mapped using the map function.
69 
70  // Map the given file descriptor entirely into memory with read access.
71  // The map has also write access if the file is opened for write.
72  // The file name is only used in possible error messages.
73  MMapfdIO (int fd, const String& fileName);
74 
75  // Destructor.
76  // If needed, it will flush and unmap the file, but not close it.
78 
79  // Map the given file descriptor entirely into memory with read access.
80  // The map has also write access if the file is opened for write.
81  // An exception is thrown if a file descriptor was already attached.
82  // The file name is only used in possible error messages.
83  void map (int fd, const String& fileName);
84 
85  // Map or remap the entire file.
86  // Remapping is needed if the file has grown elsewhere.
87  void mapFile();
88 
89  // Flush changed mapped data to the file.
90  // Nothing is done if the file is readonly.
91  void flush();
92 
93  // Write the number of bytes from the seek position on.
94  // The file will be extended and remapped if writing beyond end-of-file.
95  // In that case possible pointers obtained using <src>getXXPointer</src>
96  // are not valid anymore.
97  virtual void write (Int64 size, const void* buf);
98 
99  // Read <src>size</src> bytes from the File. Returns the number of bytes
100  // actually read. Will throw an exception (AipsError) if the requested
101  // number of bytes could not be read unless throwException is set to
102  // False. Will always throw an exception if the file is not readable or
103  // the system call returns an undocumented value.
104  virtual Int64 read (Int64 size, void* buf, Bool throwException=True);
105 
106  // Get a read or write pointer to the given position in the mapped file.
107  // An exception is thrown if beyond end-of-file or it not writable.
108  // These functions should be used with care. If the pointer is used to
109  // access data beyond the file size, a segmentation fault will occur.
110  // So it means that the write pointer can only be used to update the file,
111  // not to extend it. The <src>seek</src> and <src>write</src> functions
112  // should be used to extend a file.
113  // <group>
114  const void* getReadPointer (Int64 offset) const;
115  void* getWritePointer (Int64 offset);
116  // </group>
117 
118  // Get the file size.
120  { return itsFileSize; }
121 
122 protected:
123  // Reset the position pointer to the given value. It returns the
124  // new position.
126 
127  // Unmap the file.
128  void unmapFile();
129 
130 private:
131  // Forbid copy constructor and assignment
132  // <group>
133  MMapfdIO (const MMapfdIO&);
135  // </group>
136 
137  Int64 itsFileSize; //# File size
138  Int64 itsPosition; //# Current seek position
139  char* itsPtr; //# Pointer to memory map
141 };
142 
143 } // end namespace
144 
145 #endif
SeekOption
Define the possible seek options.
Definition: ByteIO.h:82
int fd() const
Get the file descriptor.
Definition: FiledesIO.h:163
virtual String fileName() const
Get the file name of the file attached.
MMapfdIO(const MMapfdIO &)
Forbid copy constructor and assignment.
virtual Int64 read(Int64 size, void *buf, Bool throwException=True)
Read size bytes from the File.
Int64 getFileSize() const
Get the file size.
Definition: MMapfdIO.h:119
MMapfdIO(int fd, const String &fileName)
Map the given file descriptor entirely into memory with read access.
virtual void write(Int64 size, const void *buf)
Write the number of bytes from the seek position on.
void map(int fd, const String &fileName)
Map the given file descriptor entirely into memory with read access.
MMapfdIO & operator=(const MMapfdIO &)
MMapfdIO()
Default constructor.
void * getWritePointer(Int64 offset)
void unmapFile()
Unmap the file.
~MMapfdIO()
Destructor.
virtual Int64 doSeek(Int64 offset, ByteIO::SeekOption)
Reset the position pointer to the given value.
void flush()
Flush changed mapped data to the file.
void mapFile()
Map or remap the entire file.
const void * getReadPointer(Int64 offset) const
Get a read or write pointer to the given position in the mapped file.
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
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