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::Runtime;
  80  * using namespace Tizen::Base::Collection;
  81  * using namespace Tizen::Io;
  82  * using namespace Tizen::App;
  83  *
  84  * result
  85  * MyApp::Execute(void)
  86  * {
  87  *      File file;
  88  *      String filePath(App::GetInstance()->GetAppDataPath() + L”myFile.txt”);
  89  *      file.Construct(filePath, “w+);
  90  *
  91  *      String testMsg(L”MemoryMappedFileTest”);
  92  *      file.Write(testMsg);
  93  *      file.Flush();
  94  *
  95  *      long long mapLength = 4096;
  96  *      MemoryMappedFile mapFile;
  97  *      mapFile.Construct(file);
  98  *      void* pMappedAddr = mapFile.Map(null, mapLength, MEMORY_PROTECTION_MODE_READ | MEMORY_PROTECTION_MODE_WRITE, MEMORY_MAPPED_FILE_FLAG_SHARED, 0);
  99  *
 100  *      char* pBuffer = new char[testMsg.GetLength() + 1];
 101  *      memcpy(pBuffer, pMappedAddr, testMsg.GetLength());
 102  *
 103  * }
 104  *
 105  * @endcode
 106  */
 107 class _OSP_EXPORT_ MemoryMappedFile
 108         : public Tizen::Base::Object
 109 {
 110
 111 public:
 112         /**
 113         * 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.
 114         *
 115         * @since        2.0
 116         */
 117         MemoryMappedFile(void);
 118
 119         /**
 120         * This destructor overrides Tizen::Base::Object::~Object().
 121         *
 122         * @since        2.0
 123         */
 124         ~MemoryMappedFile(void);
 125
 126         /**
 127         * Initializes this instance of %MemoryMappedFile with a specified file.
 128         *
 129         * @since                2.0
 130         *
 131         * @return               An error code
 132         * @param[in]    file                            The File instance for memory mapping
 133         * @exception    E_SUCCESS                       The method is successful.
 134         * @exception    E_INVALID_ARG           The specified @c file is not opened for reading. @n
 135         *                                                                       The opening mode should not be "w" or "a".
 136         * @remarks              The specified @c file should be initialized by the Io::File::Construct() method.
 137         * @see                  Tizen::Io::File
 138         */
 139         result Construct(const File& file);
 140
 141         /**
 142         * Creates a new mapping for the specified file in the virtual address space of the calling process.
 143         *
 144         * @since                2.0
 145         *
 146         * @return               The mapped address space, @n
 147         *                               else @c null pointer if this method fails
 148         * @param[in]    address                                 A starting address of the mapping @n
 149         *                                                                               If the specified @c address is @c null, the system chooses the address.
 150         *                                                                               It should be a multiple of the page size.
 151         * @param[in]    length                                  The length of the mapping space
 152         * @param[in]    protection                              The memory protection of the mapping @n
 153         *                                                                               It is either Base::Runtime::MEMORY_PROTECTION_MODE_NONE or the bitwise-inclusive OR of one
 154         *                                                                               or more of the other modes in Base::Runtime::MemoryProtectionMode.
 155         * @param[in]    flag                                    The flag providing information about the handling of a memory mapped file @n
 156         *                                                                               It is the bitwise-inclusive OR of the flags in Tizen::Io::MemoryMappedFileFlag.
 157         * @param[in]    offset                                  The start offset of the specified file @n
 158         *                                                                               It should be a multiple of the page size.
 159         * @exception    E_SUCCESS                               The method is successful.
 160         * @exception    E_ILLEGAL_ACCESS                The specified @c flag is MEMORY_MAPPED_FILE_FLAG_SHARED and the specified @c
 161         *                                                                               protection is MEMORY_PROTECTION_MODE_WRITE, but the specified file of
 162         *                                                                               MemoryMappedFile::Construct() is not opened with read-write mode.
 163         * @exception    E_INVALID_ARG                   Either of the following conditions has occurred: @n
 164         *                                                                               - The specified @c address or @c offset is not aligned on a page boundary. @n
 165         *                                                                               - The specified @c length is not positive. @n
 166         *                                                                               - The specified @c protection, @c flag, or @c offset @ is invalid. @n
 167         *                                                                               - The specified @c flag cannot contain both MEMORY_MAPPED_FILE_FLAG_PRIVATE and
 168         *                                                                                 MEMORY_MAPPED_FILE_FLAG_SHARED.
 169         * @exception    E_MAX_EXCEEDED                  The number of mapped regions has exceeded the maximum limit.
 170         * @exception    E_OBJECT_LOCKED                 The mapped file has been locked.
 171         * @exception    E_OUT_OF_MEMORY                 Either of the following conditions has occurred: @n
 172         *                                                                               - The memory is insufficient. @n
 173         *                                                                               - The specified @c flag is MEMORY_MAPPED_FILE_FLAG_FIXED, and the specified address
 174         *                                                                                 range exceeds that allowed for the address space of a current process.
 175         * @exception    E_IO                                    Either of the following conditions has occurred: @n
 176         *                                                                               - The underlying file system does not support memory mapping. @n
 177         *                                                                               - The specified @c protection is MEMORY_PROTECTION_MODE_EXEC, but the mapped file
 178         *                                                                                 exists on a file system that has been mounted no-exec.
 179         * @remarks              The specific error code can be accessed using the GetLastResult() method. @n
 180         *                               When this instance is destructed, all mappings are deleted automatically.
 181         * @see                  Tizen::Base::Runtime::MemoryManager
 182         */
 183         void* Map(void* address, long long length, unsigned long protection, unsigned long flag, long long offset);
 184
 185         /**
 186         * Deletes the mapping of the specified address space. @n
 187         * Further references to the addresses within the range result in generation of an invalid memory access. @n
 188         * This method flushes all changes of a shared mapping to the correlated file on the permanent storage.
 189         *
 190         * @since                2.0
 191         *
 192         * @return               An error code
 193         * @param[in]    address                         The memory mapping address to unmap
 194         * @param[in]    length                          The length of the mapping space
 195         * @exception    E_SUCCESS                       The method is successful.
 196         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 197         *                                                                       - The specified @c address is not aligned on a page boundary. @n
 198         *                                                                       - The specified @c length is not positive. @n
 199         *                                                                       - The specified address range is out of the valid address space of a current process.
 200         * @remarks              When this instance is destructed, all mappings of the instance are not unmapped automatically.
 201         */
 202         result Unmap(void* address, long long length);
 203
 204         /**
 205         * Flushes all changes of an address range to the correlated file on the permanent storage.
 206         *
 207         * @since                2.0
 208         *
 209         * @return               An error code
 210         * @param[in]    address                         The memory mapping address to synchronize
 211         * @param[in]    length                          The length of the mapping space
 212         * @param[in]    syncFlag                        The synchronization option
 213         * @exception    E_SUCCESS                       The method is successful.
 214         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 215         *                                                                       - The specified @c address is not aligned on a page boundary. @n
 216         *                                                                       - The specified @c length is not positive. @n
 217         *                                                                       - The specified @c syncFlag is invalid. @n
 218         *                                                                       - The specified @c address space is not mapped.
 219         * @exception    E_IO                            Either of the following conditions has occurred: @n
 220         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 221         *                                                                       - %File corruption is detected.
 222         * @remarks              The specific page size of a current file system is provided by Tizen::System::SystemInfo class with
 223         *                               "StorageInfo" key.
 224         * @see                  Tizen::Io::MemoryMappedFileSyncFlag
 225     * @see              Tizen::System::SystemInfo
 226         */
 227         result Sync(void* address, long long length, MemoryMappedFileSyncFlag syncFlag);
 228
 229 private:
 230         /**
 231         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 232         *
 233         * @since        2.0
 234         */
 235         MemoryMappedFile(const MemoryMappedFile& rhs);
 236
 237         /**
 238         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 239         *
 240         * @since        2.0
 241         */
 242         MemoryMappedFile& operator =(const MemoryMappedFile& rhs);
 243
 244         class _MemoryMappedFileImpl* __pMemoryMappedFileImpl;
 245
 246         friend class _MemoryMappedFileImpl;
 247
 248 }; // MemoryMappedFile
 249
 250 }} // Tizen::Io
 251
 252 #endif // _FIO_MEMORY_MAPPED_FILE_H_
 253