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