Spec External String
String that is stored in external memory.

Extends String
All Extended String
All Impl'd AssignableConcept, ContainerConcept, DestructibleConcept, ForwardContainerConcept, RandomAccessContainerConcept, ReversibleContainerConcept, SegmentableConcept, StringConcept, TextConcept
Defined in <seqan/file.h>
Signature template <typename TValue[, typename TConfig]> class String<TValue, External<TConfig> >;

Template Parameters

TValue The type that is used for the items/characters stored in the string.
TConfig A structure to confgure the external string. Defaults to ExternalConfigLarge<>. See ExternalConfig, ExternalConfigLarge, and ExternalConfigSize.

Member Function Overview

Member Functions Inherited From String

Member Functions Inherited From AssignableConcept

Member Functions Inherited From RandomAccessContainerConcept

Interface Function Overview

Interface Functions Inherited From String

Interface Functions Inherited From AssignableConcept

Interface Functions Inherited From ContainerConcept

Interface Functions Inherited From RandomAccessContainerConcept

Interface Functions Inherited From SegmentableConcept

Interface Functions Inherited From StringConcept

Interface Functions Inherited From TextConcept

Interface Metafunction Overview

Interface Metafunctions Inherited From ContainerConcept

Interface Metafunctions Inherited From SegmentableConcept

Interface Metafunctions Inherited From TextConcept

Detailed Description

The External String enables to access sequences larger than the available internal memory (RAM) by using external memory (e.g. Hard disk, Network storage, ...) via a File object. Sequences of nearly arbitrary size can be accessed even larger than the logically addressable memory, i.e. they can in particular contain more than 2^32 elements on a 32bit system (see Tag.ExternalConfigLarge). See the String constructor for more details.

This String also supports fast appending and removing of values at the end (see Block String, appendValue)

The External String implements a LRU mechanism to swap out pages. The External String's Iterator detects a forward or backward iteration and asynchronously prefetches pages that certainly will be accessed and automatically swaps out pages that certainly won't be accessed any more in the iteration process.

The String is implemented like a virtual memory manager. It divides its character sequence into pages of a fixed length (e.g. 4MB) and maintains a page table with information for each page (e.g. resides in memory or was swapped out, is dirty and needs to be saved, ...). Besides the page table the String also contains a size-limited list of page frames. A page frame is reserved internal memory for a page. When accessing values of a page that is stored in external memory, the page is loaded to a page frame first. In case that there is no page frame free, another page is swapped out before to free a page frame.

Member Functions Detail

String::String(); String::String(file); String::String(fileName[, openMode]);

Constructor

Parameters

file The File to use for reading and writing. You must ensture that file is open as the string will not call open and close on the file.
fileName The path to open. Type: char const *
openMode The open mode.

Remarks

When a file or file name is given, this file will be used for the ExternalString. If the file exists, this file will be used and determines the strings length and content. If the file doesn't exist, a new and empty file will be created and used for the string. In both cases, the string won't delete the file in the destructor.

When no file is given (default c'tor) the string will be empty and no file is used until the string needs to swap out page frames. Then a temporary file will be used which will be deleted when the string is destroyed.

Instead of giving file or fileName to the constructor, you could also use the default constructor and call open or openTemp afterwards to reach the same behaviour.

Data Races

Thread safety unknown!

Interface Functions Detail

bool close(str);

Close the external string.

Parameters

str The ExternalString to close the file of.

Returns

bool true if the closing succeeded, false otherwise.

Data Races

Thread safety unknown!

void flush(str);

Waits for all open read/write requests to complete.

Parameters

str The ExternalString to flush.

Data Races

Thread safety unknown!

bool open(str, fileName[, openMode]);

Open the ExternalString's underlying file from a path.

Parameters

str The ExternalString to open.
fileName Path to the file to open. Type: char const *.
openMode The open mode. Type: int.

Returns

bool true if the operation succeeded and false otherwise.

Data Races

Thread safety unknown!

bool openTemp(str);

Open an ExternalString using an temporary file.

Parameters

str The ExternalString to open using temporary file.

Returns

bool true if opening succeeded, false otherwise.

Data Races

Thread safety unknown!