inc/FIoMemoryMappedFile.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the License);
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16
  17 /**
  18  * @file        FIoMemoryMappedFile.h
  19  * @brief       This is the header file for the %MemoryMappedFile class.
  20  *
  21  * This header file contains the declarations of the %MemoryMappedFile class.
  22  */
  23
  24 #ifndef _FIO_MEMORY_MAPPED_FILE_H_
  25 #define _FIO_MEMORY_MAPPED_FILE_H_
  26
  27 #include <FOspConfig.h>
  28 #include <FBaseObject.h>
  29
  30 namespace Tizen { namespace Io
  31 {
  32
  33 /**
  34  * @enum        MemoryMappedFileFlag
  35  *
  36  * Defines flags providing information about the handling of a memory mapped file.
  37  *
  38  * @since       2.0
  39  */
  40 enum MemoryMappedFileFlag
  41 {
  42         MEMORY_MAPPED_FILE_FLAG_SHARED = 0x01,  /**< Changes are shared with other processes mapping the same file */
  43         MEMORY_MAPPED_FILE_FLAG_PRIVATE = 0x02, /**< Changes are not visible to other processes mapping the same file */
  44         MEMORY_MAPPED_FILE_FLAG_FIXED = 0x10    /**< This forces the system to use the specified mapping address exactly,
  45                                                                                           which should be a multiple of the page size */
  46 };
  47
  48 /**
  49  * @enum        MemoryMappedFileSyncFlag
  50  *
  51  * Defines synchronization flags of a memory mapped file.
  52  *
  53  * @since       2.0
  54  */
  55 enum MemoryMappedFileSyncFlag
  56 {
  57         MEMORY_MAPPED_FILE_SYNC_FLAG_ASYNC = 0x01,              /**< Asynchronous update */
  58         MEMORY_MAPPED_FILE_SYNC_FLAG_SYNC = 0x02                /**< Synchronous update */
  59 };
  60
  61 /**
  62  * @class       MemoryMappedFile
  63  * @brief       This class provides features mapping a file to virtual address space.
  64  *
  65  * @since       2.0
  66  *
  67  * @final       This class is not intended for extension.
  68  *
  69  * The %MemoryMappedFile class provides features for using a memory mapped file,
  70  * which maps the data of a file to an application's virtual address space.
  71  *
  72  * @code
  73  *
  74  * #include <FBase.h>
  75  * #include <FIo.h>
  76  * #include <FApp.h>
  77  *
  78  * using namespace Tizen::Base;
  79  * using namespace Tizen::Base::Collection;
  80  * using namespace Tizen::Io;
  81  * using namespace Tizen::App;
  82  *
  83  * result
  84  * MyApp::Execute(void)
  85  * {
  86  *      String filePath(App::GetInstance()->GetAppDataPath() + L”myFile.txt”);
  87  *      file.Construct(filePath, “w+);
  88  *
  89  *      String testMsg(L”MemoryMappedFileTest”);
  90  *      file.Write(testMsg);
  91  *      file.Flush();
  92  *
  93  *      long long mapLength = 4096;
  94  *      MemoryMappedFile mapFile;
  95  *      mapFile.Construct(file);
  96  *      void* pMappedAddr = mapFile.Map(null, mapLength, MEMORY_PROTECTION_MODE_READ | MEMORY_PROTECTION_MODE_WRITE, MEMORY_MAPPED_FILE_FLAG_SHARED, 0);
  97  *
  98  *      char* pBuffer = new char[testMsg.GetLength() + 1];
  99  *      memcpy(pBuffer, pMappedAddr, testMsg.GetLength());
 100  *
 101  * }
 102  *
 103  * @endcode
 104  */
 105 class _OSP_EXPORT_ MemoryMappedFile
 106         : public Tizen::Base::Object
 107 {
 108
 109 public:
 110         /**
 111         * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 112         *
 113         * @since        2.0
 114         */
 115         MemoryMappedFile(void);
 116
 117         /**
 118         * This destructor overrides Tizen::Base::Object::~Object().
 119         *
 120         * @since        2.0
 121         */
 122         ~MemoryMappedFile(void);
 123
 124         /**
 125         * Initializes this instance of %MemoryMappedFile with a specified file.
 126         *
 127         * @since                2.0
 128         *
 129         * @return               An error code
 130         * @param[in]    file                            The File instance for memory mapping
 131         * @exception    E_SUCCESS                       The method is successful.
 132         * @exception    E_INVALID_ARG           The specified @c file is not opened for reading. @n
 133         *                                                                       The opening mode should not be "w" or "a".
 134         * @remarks              The specified @c file should be initialized by the Io::File::Construct() method.
 135         * @see                  Tizen::Io::File
 136         */
 137         result Construct(const File& file);
 138
 139         /**
 140         * Creates a new mapping for the specified file in the virtual address space of the calling process.
 141         *
 142         * @since                2.0
 143         *
 144         * @return               The mapped address space, @n
 145         *                               else @c null pointer if this method fails
 146         * @param[in]    address                                 A starting address of the mapping @n
 147         *                                                                               If the specified @c address is @c null, the system chooses the address.
 148         *                                                                               It should be a multiple of the page size.
 149         * @param[in]    length                                  The length of the mapping space
 150         * @param[in]    protection                              The memory protection of the mapping @n
 151         *                                                                               It is either Base::Runtime::MEMORY_PROTECTION_MODE_NONE or the bitwise-inclusive OR of one
 152         *                                                                               or more of the other modes in Base::Runtime::MemoryProtectionMode.
 153         * @param[in]    flag                                    The flag providing information about the handling of a memory mapped file @n
 154         *                                                                               It is the bitwise-inclusive OR of the flags in Tizen::Io::MemoryMappedFileFlag.
 155         * @param[in]    offset                                  The start offset of the specified file @n
 156         *                                                                               It should be a multiple of the page size.
 157         * @exception    E_SUCCESS                               The method is successful.
 158         * @exception    E_ILLEGAL_ACCESS                The specified @c flag is MEMORY_MAPPED_FILE_FLAG_SHARED and the specified @c
 159         *                                                                               protection is MEMORY_PROTECTION_MODE_WRITE, but the specified file of
 160         *                                                                               MemoryMappedFile::Construct() is not opened with read-write mode.
 161         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 162         *                                                                               - The specified @c address or @c offset is not aligned on a page boundary. @n
 163         *                                                                               - The specified @c length is not positive. @n
 164         *                                                                               - The specified @c protection, @c flag, or @c offset @ is invalid. @n
 165         *                                                                               - The specified @c flag cannot contain both MEMORY_MAPPED_FILE_FLAG_PRIVATE and
 166         *                                                                                 MEMORY_MAPPED_FILE_FLAG_SHARED.
 167         * @exception    E_MAX_EXCEEDED                  The number of mapped regions has exceeded the maximum limit.
 168         * @exception    E_OBJECT_LOCKED                 The mapped file has been locked.
 169         * @exception    E_OUT_OF_MEMORY                 Either of the following conditions has occurred: @n
 170         *                                                                               - The memory is insufficient. @n
 171         *                                                                               - The specified @c flag is MEMORY_MAPPED_FILE_FLAG_FIXED, and the specified address
 172         *                                                                                 range exceeds that allowed for the address space of a current process.
 173         * @exception    E_IO                                    Either of the following conditions has occurred: @n
 174         *                                                                               - The underlying file system does not support memory mapping. @n
 175         *                                                                               - The specified @c protection is MEMORY_PROTECTION_MODE_EXEC, but the mapped file
 176         *                                                                                 exists on a file system that has been mounted no-exec.
 177         * @remarks              The specific error code can be accessed using the GetLastResult() method. @n
 178         *                               When this instance is destructed, all mappings are deleted automatically.
 179         * @see                  Tizen::Base::Runtime::MemoryManager
 180         */
 181         void* Map(void* address, long long length, unsigned long protection, unsigned long flag, long long offset);
 182
 183         /**
 184         * Deletes the mapping of the specified address space. @n
 185         * Further references to the addresses within the range result in generation of an invalid memory access. @n
 186         * This method flushes all changes of a shared mapping to the correlated file on the permanent storage.
 187         *
 188         * @since                2.0
 189         *
 190         * @return               An error code
 191         * @param[in]    address                         The memory mapping address to unmap
 192         * @param[in]    length                          The length of the mapping space
 193         * @exception    E_SUCCESS                       The method is successful.
 194         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 195         *                                                                       - The specified @c address is not aligned on a page boundary. @n
 196         *                                                                       - The specified @c length is not positive. @n
 197         *                                                                       - The specified address range is out of the valid address space of a current process.
 198         * @remarks              When this instance is destructed, all mappings of the instance are not unmapped automatically.
 199         */
 200         result Unmap(void* address, long long length);
 201
 202         /**
 203         * Flushes all changes of an address range to the correlated file on the permanent storage.
 204         *
 205         * @since                2.0
 206         *
 207         * @return               An error code
 208         * @param[in]    address                         The memory mapping address to synchronize
 209         * @param[in]    length                          The length of the mapping space
 210         * @param[in]    syncFlag                        The synchronization option
 211         * @exception    E_SUCCESS                       The method is successful.
 212         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 213         *                                                                       - The specified @c address is not aligned on a page boundary. @n
 214         *                                                                       - The specified @c length is not positive. @n
 215         *                                                                       - The specified @c syncFlag is invalid. @n
 216         *                                                                       - The specified @c address space is not mapped.
 217         * @exception    E_IO                            Either of the following conditions has occurred: @n
 218         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 219         *                                                                       - %File corruption is detected.
 220         * @remarks              The specific page size of a current file system is provided by Tizen::System::SystemInfo class with
 221         *                               "StorageInfo" key.
 222         * @see                  Tizen::Io::MemoryMappedFileSyncFlag
 223     * @see              Tizen::System::SystemInfo
 224         */
 225         result Sync(void* address, long long length, MemoryMappedFileSyncFlag syncFlag);
 226
 227 private:
 228         /**
 229         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 230         *
 231         * @since        2.0
 232         */
 233         MemoryMappedFile(const MemoryMappedFile& rhs);
 234
 235         /**
 236         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 237         *
 238         * @since        2.0
 239         */
 240         MemoryMappedFile& operator =(const MemoryMappedFile& rhs);
 241
 242         class _MemoryMappedFileImpl* __pMemoryMappedFileImpl;
 243
 244         friend class _MemoryMappedFileImpl;
 245
 246 }; // MemoryMappedFile
 247
 248 }} // Tizen::Io
 249
 250 #endif // _FIO_MEMORY_MAPPED_FILE_H_
 251