Class FileMapping

A structure to memory-map a file.

/*!
 * @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 advise segment in.
 * @param[in] advise The advise type. Type: @link FileMappingAdvise @endlink.
 * @param[in] addr A pointer to the 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 read/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>.
 */