/*!
* @class FileMapping
*
* @headerfile <seqan/file.h>
*
* @brief A structure to memory-map a file.
*
* @signature template <[typename TSpec]> struct FileMapping;
*
* @tparam TSpec The specializing type. Default: <tt>void</tt>.
*
* This structure represents both a file and its memory mapping.
*
* @mfn FileMapping#Size
*
* @brief Return the size type of the FileMapping.
*
* @signature Size<TFileMapping>::Type;
*
* @tparam TFileMapping FileMapping to query.
*
* @return Type The size type of the FileMapping.
*
* @fn FileMapping#open
*
* @brief Open a file to be mapped into memory.
*
* @signature bool open(fileMapping, fileName[, openMode]);
*
* @param[in,out] fileMapping The FileMapping to open.
* @param[in] fileName The path to the fie.
* @param[in] openMode The mode to open the file in, flags from @link
* FileOpenMode @endlink to combine using OR. Write-only
* mode is not supported, use <tt>OPEN_RDWR</tt> if you need
* write access. If you omit the <tt>OPEN_APPEND</tt> flag
* in write mode, the file will be cleared when opened.
* Default: <tt>OPEN_RDWR | OPEN_CREATE | OPEN_APPEND</tt>.
*
* @return bool <tt>true</tt> if the opening was successful, <tt>false</tt>
* otherwise.
*
* @fn FileMapping#openTemp
*
* @brief Open a temporary file to be mapped into memory.
*
* @signature bool openTemp(fileMapping);
*
* @param[in,out] fileMapping The FileMapping to open using a temporary file.
*
* @return bool <tt>true</tt> on success, <tt>false</tt> otherwise.
*
* @fn FileMapping#close
*
* @brief Close a file and its memory mapping.
*
* @signature bool close(fileMapping);
*
* @param[in,out] fileMapping The FileMapping to close
*
* @return bool <tt>true</tt> on success, <tt>false</tt> otherwise.
*
* @fn FileMapping#closeAndResize
*
* @brief Close a memory mapping and resize and close the underlying file.
*
* @signature bool closeAndResize(fileMapping, newFileSize);
*
* @param[in,out] fileMapping The FileMapping to close.
* @param[in] newFileSize The size the file should have after closing.
*
* @return bool <tt>true</tt> indicating success, <tt>false</tt> failure.
*
* @fn FileMapping#length
*
* @brief Return the file size of a memory mapping.
*
* @signature TSize length(fileMapping);
*
* @param[in] fileMapping The FileMapping to return the length for.
*
* @return TSize The file size (Metafunction: @link FileMapping#Size @endlink).
*
* @fn FileMapping#resize
*
* @brief Resize the underlying file.
*
* @signature bool resize(fileMapping, newFileSize);
*
* @param[in,out] fileMapping The FileMapping to resize.
* @param[in] newFileSize The new file size to set.
*
* @return bool <tt>true</tt> on success, <tt>false</tt> otherwise.
*
* @section Remarks
*
* On Windows, all existing file mappings must be unmapped via @link
* FileMapping#unmapFileSegment @endlink before claling this function.
*
* @fn FileMapping#flushFileSegment
*
* @brief Wait for all outstanding transactions of a memory-mapped file segment.
*
* @signature bool flushFileSegment(fileMapping, addr, beginPos, size);
*
* @param[in,out] fileMapping A FileMapping object.
* @param[in] addr A pointer to the beginning of memory-mapped segment in memory
* (returned by a prior call of @link FileMapping#mapFileSegment
* @endlink.
* @param[in] beginPos The absolute start address of the segment in bytes.
* @param[in] size The segment length in bytes.
*
* @return bool <tt>true</tt> on success, <tt>false</tt> on failure.
*
* @section Remarks
*
* This function has no effect under Windows. On all other platforms it calls
* <tt>msync</tt>. This function is only needed to synchronize file accesses in
* non-shared-memory environments.
*
* @fn FileMapping#cancelFileSegment
*
* @brief Cancel all outstanding transactions of a memory-mapped file segment.
*
* @signature bool cancelFileSegment(fileMapping, addr, beginPos, size);
*
* @param[in,out] fileMapping The FileMapping object.
* @param[in] addr A pointer to the beginning of the memory-mapped segment in
* memory (returned by a prior call of
* FileMapping#mapFileSegment).
* @param[in] beginPos the absolute start address of the segment in bytes.
* @param[in] size The segment length in bytes.
*
* @return bool <tt>true</tt> on success, <tt>false</tt> on failure.
*
* @fn FileMapping#adviseFileSegment
*
* @brief Give advise about use of a memory-mapped file segment.
*
* @signature bool adviseFileSegment(fileMapping, advise, addr, fileOfs, size);
*
* @param[in,out] fileMapping The FileMapping object to adsive segment in.
* @param[in] advise The advise type. Type: @link FileMappingAdvise @endlink.
* @param[in] addr A pointer t othe beginning of the memory-mapped segment in
* memory (returned by a prior call of @link
* FileMapping#mapFileSegment @endlink).
* @param[in] fileOfs The absolute start address of the segment in bytes.
* @param[in] size The segment length in bytes.
*
* @return bool <tt>true</tt> on success, <tt>false</tt> on failure.
*
* @section Remarks
*
* This function has no effect on Windows. On all other platforms it calls
* <tt>posix_madvise</tt>.
*
* @fn FileMapping#mapFileSegment
*
* @brief Map a segment of a file into memory.
*
* @signature TPtr mapFileSegment(fileMapping, fileOfs[, size[, mode]]);
*
* @param[in,out] fileMapping A FileMapping object.
* @param[in] fileOfs The absolute start address of the segment in bytes.
* @param[in] size The segment length in bytes.
* @param[in] mode The mapping access mode. Default rread/write open mode of the
* underlying file. Type: @link FileMappingMode @endlink.
*
* @return TPtr A pointer to the beginning of the memory-mapped segment in
* memory or <tt>NULL</tt> on error. TPtr is <tt>void *</tt>.
*
* @fn FileMapping#unmapFileSegment
*
* @brief Unmap a memory-mapped file segment.
*
* @signature bool unmappedFileSegment(fileMapping, addr, size);
*
* @param[in,out] fileMapping A FileMapping object.
* @param[in] addr The pointer to the beginning of the memory-mapped segment in
* memory. Type: <tt>void*</tt>.
* @param[in] size The segment length in bytes.
*
* @return bool <tt>true</tt> on success, <tt>false</tt> on failure.
*
* @fn FileMapping#remapFileSegment
*
* @brief Change the size of a memory-mapped file segment.
*
* @signature TPtr remapFileSegment(fileMapping, oldAddr, oldFileOfs, oldSize,
* newSize);
*
* @param[in,out] fileMapping The FileMapping object.
* @param[in] oldAddr The address returned by @link FileMapping#mapFileSegment
* @endlink.
* @param[in] oldFileOfs The <tt>fileOfs</tt> parameter used in @link
* FileMapping#mapFileSegment @endlink.
* @param[in] oldSize The <tt>size</tt> parameter used in @link
* FileMapping#mapFileSegment @endlink.
* @param[in] newSize the new segment length in bytes.
*
* @return TPtr A pointer to the beginning of the memory-mapped segment in
* memory or <tt>NULL</tt> on error. Type: <tt>void*</tt>.
*/