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
37namespace 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
63class MMapfdIO: public FiledesIO
64{
65public:
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
122protected:
123 // Reset the position pointer to the given value. It returns the
124 // new position.
126
127 // Unmap the file.
128 void unmapFile();
129
130private:
131 // Forbid copy constructor and assignment
132 // <group>
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.
MMapfdIO & operator=(const MMapfdIO &)
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.
const void * getReadPointer(Int64 offset) const
Get a read or write pointer to the given position in the mapped file.
void map(int fd, const String &fileName)
Map the given file descriptor entirely into memory with read access.
MMapfdIO()
Default constructor.
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.
void * getWritePointer(Int64 offset)
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