SwappableVector< number > Class Template Reference
[Vector classes]

Inheritance diagram for SwappableVector< number >:

Inheritance graph
[legend]

List of all members.

Classes

class  ExcInvalidCopyOperation
class  ExcInvalidFilename
class  ExcSizeNonzero
class  ExcSizeZero

Public Member Functions

 SwappableVector ()
 SwappableVector (const SwappableVector &v)
virtual ~SwappableVector ()
SwappableVectoroperator= (const SwappableVector &)
void swap_out (const std::string &filename)
void reload ()
void alert ()
void kill_file ()
const std::string & get_filename () const
unsigned int memory_consumption () const

Private Member Functions

void reload_vector (const bool set_flag)

Private Attributes

std::string filename
Threads::ThreadMutex lock
bool data_is_preloaded


Detailed Description

template<typename number>
class SwappableVector< number >

This class is a wrapper to the Vector class which allows to swap out the data to a file and reload it later on. It handles the management of the name of the file where the data is to be stored temporarily and removes the file is necessary at the end of the lifetime of the vector.

There are functions to swap the data to a file, and to reload it. There is also a function alert that can be used to signal to an object of this class that the data will be needed shortly, so the object can initiate that the data be loaded already. While in non-multithreading mode, this function has no effect since reload has to be called afterwards anyway. On the other hand, in multithreading mode, the data is preloaded in the background using a thread on its own, and may already be available at the time when reload is called. If it is not available, reload waits until the detached thread has loaded the data.

Note:
Instantiations for this template are provided for <float> and <double>; others can be generated in application programs (see the section on Template instantiations in the manual).
Author:
Wolfgang Bangerth, 1999, 2000

Constructor & Destructor Documentation

template<typename number >
SwappableVector< number >::SwappableVector (  ) 

Constructor. Does nothing apart from calling the constructor of the underlying class.

template<typename number >
SwappableVector< number >::SwappableVector ( const SwappableVector< number > &  v  ) 

Copy constructor. Copies the data if v contains some, but does not do so if v is empty or has its data swapped out. In the latter case, warn about that. In particular do not take over ownership of any files that v might own (as, for example, C++'s auto_ptr objects would do).

template<typename number >
virtual SwappableVector< number >::~SwappableVector (  )  [virtual]

Destructor. If this class still owns a file to which temporary data was stored, then it is deleted.


Member Function Documentation

template<typename number >
SwappableVector& SwappableVector< number >::operator= ( const SwappableVector< number > &   ) 

Copy operator. Do mostly the same as the copy constructor does; if necessary, delete temporary files owned by this object at first.

template<typename number >
void SwappableVector< number >::swap_out ( const std::string &  filename  ) 

Swap out the data of this vector to the file of which the name is given. It is assumed that the file can be overwritten if it exists, and ownership of this file is assumed by this object. The file is deleted either upon calling kill_file, or on destruction of this object.

The content of the vector is cleared and it size is reset to zero.

If this object owns another file, for example when swap_out but no kill_file has previously been called, then that is deleted first.

template<typename number >
void SwappableVector< number >::reload (  ) 

Reload the data of this vector from the file to which it has been stored previously using swap_out. Since the file is not deleted after reloading, you can call reload multiple times, in between you may do everything with the vector, including changing its size.

This function resets the size of the vector to the number of elements there were upon calling swap_out before.

template<typename number >
void SwappableVector< number >::alert (  ) 

Calling this function can be used to alert this vector that it will need to reload its data soon. It has no effect if the data of the vector is already present, and it has no effect in single-thread mode as well, but in multithread mode, it spawns another thread that reads the data in parallel to the usual execution of the program, such that when reload is called, the data may eventually be available already. It might therefore be wirthwhile to call this function some time in advance, if you know that the data will be needed, and loading takes some time, for instance if the file to which the data was written is not in a local tmp directory.

Calling this function multiple times before calling reload is allowed and has no effect for subsequent calls. Calling this function while the data is still or already in memory is allowed and has no effect.

template<typename number >
void SwappableVector< number >::kill_file (  ) 

Remove the file to which the data has been stored the last time. After this, the object does not own any file any more, so of course you can't call reload no more.

If this object does not own a file, for example since swap_out was not called, or because kill_file has been called previously, then this function does nothing.

template<typename number >
const std::string& SwappableVector< number >::get_filename (  )  const

Return the name of the file to which the data was stored the last time you called swap_out. If swap_out was not called, or if in between kill_file was called, then the filename is an empty string.

template<typename number >
unsigned int SwappableVector< number >::memory_consumption (  )  const

Determine an estimate for the memory consumption (in bytes) of this object.

Reimplemented from Vector< number >.

template<typename number >
void SwappableVector< number >::reload_vector ( const bool  set_flag  )  [private]

Internal function that actually reloads the vector. Called from reload and alert.

The parameter specifies whether the function shall set data_is_preloaded or not. The calling functions can't sometimes do this themselves, since they call this function detached, so this function has to signal success itself if this is required.


Member Data Documentation

template<typename number >
std::string SwappableVector< number >::filename [private]

Name of the file to which data was swapped out. If no data is presently swapped out (i.e. before calling swap_out and after kill_file), the string is empty, indicating no ownership of files.

template<typename number >
Threads::ThreadMutex SwappableVector< number >::lock [private]

If in multithread mode, then the alert function has functionality, but needs to coordinate with the reload function. This is done through the following lock.

If not in MT mode, then the class used here is empty, and we can as well get away with it.

template<typename number >
bool SwappableVector< number >::data_is_preloaded [private]

Flag by which the alert function signifies that the data has been preloaded already. This flag is always false in non-MT mode.


The documentation for this class was generated from the following file:

deal.II documentation generated on Sat Aug 15 16:52:24 2009 by doxygen 1.5.9