FileMapping - SeqAn API Documentation

# Class FileMapping
A structure to memory-map a file.

Defined in | <seqan/file.h>
Signature | `template <[typename TSpec]> struct FileMapping;`

## Template Parameters

`TSpec` | The specializing type. Default: `void`.

## Interface Function Overview

- `bool adviseFileSegment(fileMapping, advise, addr, fileOfs, size);`
  Give advise about use of a memory-mapped file segment.
- `bool cancelFileSegment(fileMapping, addr, beginPos, size);`
  Cancel all outstanding transactions of a memory-mapped file segment.
- `bool close(fileMapping);`
  Close a file and its memory mapping.
- `bool closeAndResize(fileMapping, newFileSize);`
  Close a memory mapping and resize and close the underlying file.
- `bool flushFileSegment(fileMapping, addr, beginPos, size);`
  Wait for all outstanding transactions of a memory-mapped file segment.
- `TSize length(fileMapping);`
  Return the file size of a memory mapping.
- `TPtr mapFileSegment(fileMapping, fileOfs[, size[, mode]]);`
  Map a segment of a file into memory.
- `bool open(fileMapping, fileName[, openMode]);`
  Open a file to be mapped into memory.
- `bool openTemp(fileMapping);`
  Open a temporary file to be mapped into memory.
- `TPtr remapFileSegment(fileMapping, oldAddr, oldFileOfs, oldSize, newSize);`
  Change the size of a memory-mapped file segment.
- `bool resize(fileMapping, newFileSize);`
  Resize the underlying file.
- `bool unmappedFileSegment(fileMapping, addr, size);`
  Unmap a memory-mapped file segment.

## Interface Metafunction Overview

- `Size<TFileMapping>::Type;`
  Return the size type of the FileMapping.

## Detailed Description

This structure represents both a file and its memory mapping.

## Interface Functions Detail

### `bool adviseFileSegment(fileMapping, advise, addr, fileOfs, size);`

Give advise about use of a memory-mapped file segment.

#### Parameters

`fileMapping` | The FileMapping object to advise segment in.
`advise` | The advise type. Type: FileMappingAdvise.
`addr` | A pointer to the beginning of the memory-mapped segment in memory (returned by a prior call of mapFileSegment).
`fileOfs` | The absolute start address of the segment in bytes.
`size` | The segment length in bytes.

#### Returns

`bool` | `true` on success, `false` on failure.

#### Remarks

This function has no effect on Windows. On all other platforms it calls `posix_madvise`.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool cancelFileSegment(fileMapping, addr, beginPos, size);`

Cancel all outstanding transactions of a memory-mapped file segment.

#### Parameters

`fileMapping` | The FileMapping object.
`addr` | A pointer to the beginning of the memory-mapped segment in memory (returned by a prior call of FileMapping#mapFileSegment).
`beginPos` | the absolute start address of the segment in bytes.
`size` | The segment length in bytes.

#### Returns

`bool` | `true` on success, `false` on failure.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool close(fileMapping);`

Close a file and its memory mapping.

#### Parameters

`fileMapping` | The FileMapping to close

#### Returns

`bool` | `true` on success, `false` otherwise.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool closeAndResize(fileMapping, newFileSize);`

Close a memory mapping and resize and close the underlying file.

#### Parameters

`fileMapping` | The FileMapping to close.
`newFileSize` | The size the file should have after closing.

#### Returns

`bool` | `true` indicating success, `false` failure.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool flushFileSegment(fileMapping, addr, beginPos, size);`

Wait for all outstanding transactions of a memory-mapped file segment.

#### Parameters

`fileMapping` | A FileMapping object.
`addr` | A pointer to the beginning of memory-mapped segment in memory (returned by a prior call of mapFileSegment.
`beginPos` | The absolute start address of the segment in bytes.
`size` | The segment length in bytes.

#### Returns

`bool` | `true` on success, `false` on failure.

#### Remarks

This function has no effect under Windows. On all other platforms it calls `msync`. This function is only needed to synchronize file accesses in non-shared-memory environments.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TSize length(fileMapping);`

Return the file size of a memory mapping.

#### Parameters

`fileMapping` | The FileMapping to return the length for.

#### Returns

`TSize` | The file size (Metafunction: Size).

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TPtr mapFileSegment(fileMapping, fileOfs[, size[, mode]]);`

Map a segment of a file into memory.

#### Parameters

`fileMapping` | A FileMapping object.
`fileOfs` | The absolute start address of the segment in bytes.
`size` | The segment length in bytes.
`mode` | The mapping access mode. Default read/write open mode of the underlying file. Type: FileMappingMode.

#### Returns

`TPtr` | A pointer to the beginning of the memory-mapped segment in memory or `NULL` on error. TPtr is `void *`.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool open(fileMapping, fileName[, openMode]);`

Open a file to be mapped into memory.

#### Parameters

`fileMapping` | The FileMapping to open.
`fileName` | The path to the fie.
`openMode` | The mode to open the file in, flags from FileOpenMode to combine using OR. Write-only mode is not supported, use `OPEN_RDWR` if you need write access. If you omit the `OPEN_APPEND` flag in write mode, the file will be cleared when opened. Default: `OPEN_RDWR | OPEN_CREATE | OPEN_APPEND`.

#### Returns

`bool` | `true` if the opening was successful, `false` otherwise.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool openTemp(fileMapping);`

Open a temporary file to be mapped into memory.

#### Parameters

`fileMapping` | The FileMapping to open using a temporary file.

#### Returns

`bool` | `true` on success, `false` otherwise.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `TPtr remapFileSegment(fileMapping, oldAddr, oldFileOfs, oldSize, newSize);`

Change the size of a memory-mapped file segment.

#### Parameters

`fileMapping` | The FileMapping object.
`oldAddr` | The address returned by mapFileSegment.
`oldFileOfs` | The `fileOfs` parameter used in mapFileSegment.
`oldSize` | The `size` parameter used in mapFileSegment.
`newSize` | the new segment length in bytes.

#### Returns

`TPtr` | A pointer to the beginning of the memory-mapped segment in memory or `NULL` on error. Type: `void*`.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool resize(fileMapping, newFileSize);`

Resize the underlying file.

#### Parameters

`fileMapping` | The FileMapping to resize.
`newFileSize` | The new file size to set.

#### Returns

`bool` | `true` on success, `false` otherwise.

#### Remarks

On Windows, all existing file mappings must be unmapped via unmapFileSegment before claling this function.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

### `bool unmappedFileSegment(fileMapping, addr, size);`

Unmap a memory-mapped file segment.

#### Parameters

`fileMapping` | A FileMapping object.
`addr` | The pointer to the beginning of the memory-mapped segment in memory. Type: `void*`.
`size` | The segment length in bytes.

#### Returns

`bool` | `true` on success, `false` on failure.

#### Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

## Interface Metafunctions Detail

### `Size<TFileMapping>::Type;`

Return the size type of the FileMapping.

#### Template Parameters

`TFileMapping` | FileMapping to query.

#### Returns

`Type` | The size type of the FileMapping.

#### Dox Sources

    /*!
     * @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>.
     */