00001 //# MMapfdIO.h: Memory-mapped IO on a file descriptor 00002 //# 00003 //# Copyright (C) 2009 00004 //# Associated Universities, Inc. Washington DC, USA. 00005 //# 00006 //# This library is free software; you can redistribute it and/or modify it 00007 //# under the terms of the GNU Library General Public License as published by 00008 //# the Free Software Foundation; either version 2 of the License, or (at your 00009 //# option) any later version. 00010 //# 00011 //# This library is distributed in the hope that it will be useful, but WITHOUT 00012 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00013 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00014 //# License for more details. 00015 //# 00016 //# You should have received a copy of the GNU Library General Public License 00017 //# along with this library; if not, write to the Free Software Foundation, 00018 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00019 //# 00020 //# Correspondence concerning AIPS++ should be addressed as follows: 00021 //# Internet email: aips2-request@nrao.edu. 00022 //# Postal address: AIPS++ Project Office 00023 //# National Radio Astronomy Observatory 00024 //# 520 Edgemont Road 00025 //# Charlottesville, VA 22903-2475 USA 00026 //# 00027 //# $Id$ 00028 00029 #ifndef CASA_MMAPFDIO_H 00030 #define CASA_MMAPFDIO_H 00031 00032 //# Includes 00033 #include <casacore/casa/aips.h> 00034 #include <casacore/casa/IO/FiledesIO.h> 00035 #include <casacore/casa/OS/RegularFile.h> 00036 00037 namespace casacore 00038 { 00039 00040 // <summary> 00041 // Memory-mapped IO on a file. 00042 // </summary> 00043 00044 // <synopsis> 00045 // Memory-mapped IO lets the OS take care of caching file segments. 00046 // This is particularly useful for the Tiled Storage Manager which keeps a 00047 // cache of tiles. When using memory-mapped IO it does not need to do that 00048 // anymore. 00049 // 00050 // On 32-bit systems its use is limited because for large files the 4 GB 00051 // memory space is insufficient. However, for 64-bit systems the memory 00052 // space is large enough to make use of it. 00053 // 00054 // In the general case there is direct access to the mapped file space. 00055 // The read and write methods copies the data into/from a buffer. 00056 // However, to avoid the copying it is possible to get a direct pointer 00057 // to the mapped data. This should be used with care, because writing to 00058 // it will cause a segmentation if the file is readonly. If the file is 00059 // writable, writing into the mapped data segment means changing the file 00060 // contents. 00061 // </synopsis> 00062 00063 class MMapfdIO: public FiledesIO 00064 { 00065 public: 00066 // Default constructor. 00067 // A file can be memory-mapped using the map function. 00068 MMapfdIO(); 00069 00070 // Map the given file descriptor entirely into memory with read access. 00071 // The map has also write access if the file is opened for write. 00072 // The file name is only used in possible error messages. 00073 MMapfdIO (int fd, const String& fileName); 00074 00075 // Destructor. 00076 // If needed, it will flush and unmap the file, but not close it. 00077 ~MMapfdIO(); 00078 00079 // Map the given file descriptor entirely into memory with read access. 00080 // The map has also write access if the file is opened for write. 00081 // An exception is thrown if a file descriptor was already attached. 00082 // The file name is only used in possible error messages. 00083 void map (int fd, const String& fileName); 00084 00085 // Map or remap the entire file. 00086 // Remapping is needed if the file has grown elsewhere. 00087 void mapFile(); 00088 00089 // Flush changed mapped data to the file. 00090 // Nothing is done if the file is readonly. 00091 void flush(); 00092 00093 // Write the number of bytes from the seek position on. 00094 // The file will be extended and remapped if writing beyond end-of-file. 00095 // In that case possible pointers obtained using <src>getXXPointer</src> 00096 // are not valid anymore. 00097 virtual void write (Int64 size, const void* buf); 00098 00099 // Read <src>size</src> bytes from the File. Returns the number of bytes 00100 // actually read. Will throw an exception (AipsError) if the requested 00101 // number of bytes could not be read unless throwException is set to 00102 // False. Will always throw an exception if the file is not readable or 00103 // the system call returns an undocumented value. 00104 virtual Int64 read (Int64 size, void* buf, Bool throwException=True); 00105 00106 // Get a read or write pointer to the given position in the mapped file. 00107 // An exception is thrown if beyond end-of-file or it not writable. 00108 // These functions should be used with care. If the pointer is used to 00109 // access data beyond the file size, a segmentation fault will occur. 00110 // So it means that the write pointer can only be used to update the file, 00111 // not to extend it. The <src>seek</src> and <src>write</src> functions 00112 // should be used to extend a file. 00113 // <group> 00114 const void* getReadPointer (Int64 offset) const; 00115 void* getWritePointer (Int64 offset); 00116 // </group> 00117 00118 // Get the file size. 00119 Int64 getFileSize() const 00120 { return itsFileSize; } 00121 00122 protected: 00123 // Reset the position pointer to the given value. It returns the 00124 // new position. 00125 virtual Int64 doSeek (Int64 offset, ByteIO::SeekOption); 00126 00127 // Unmap the file. 00128 void unmapFile(); 00129 00130 private: 00131 // Forbid copy constructor and assignment 00132 // <group> 00133 MMapfdIO (const MMapfdIO&); 00134 MMapfdIO& operator= (const MMapfdIO&); 00135 // </group> 00136 00137 Int64 itsFileSize; //# File size 00138 Int64 itsPosition; //# Current seek position 00139 char* itsPtr; //# Pointer to memory map 00140 Bool itsIsWritable; 00141 }; 00142 00143 } // end namespace 00144 00145 #endif