Reference documentation for deal.II version Git cb0bd54b52 2019-09-21 16:31:22 -0400
SwappableVector< number > Class Template Reference

#include <deal.II/lac/swappable_vector.h>

Inheritance diagram for SwappableVector< number >:
[legend]

## Public Member Functions

SwappableVector ()

SwappableVector (const SwappableVector &v)

virtual ~SwappableVector () override

SwappableVectoroperator= (const SwappableVector &)

void swap_out (const std::string &filename)

void kill_file ()

const std::string & get_filename () const

std::size_t memory_consumption () const

Public Member Functions inherited from Vector< number >
Vector ()

Vector (const Vector< number > &v)

Vector (Vector< number > &&v) noexcept=default

Vector (const Vector< OtherNumber > &v)

Vector (const std::initializer_list< OtherNumber > &v)

Vector (const PETScWrappers::VectorBase &v)

Vector (const TrilinosWrappers::MPI::Vector &v)

Vector (const size_type n)

Vector (const InputIterator first, const InputIterator last)

virtual ~Vector () override=default

void compress (::VectorOperation::values operation=::VectorOperation::unknown) const

virtual void reinit (const size_type N, const bool omit_zeroing_entries=false)

void reinit (const Vector< Number2 > &V, const bool omit_zeroing_entries=false)

void grow_or_shrink (const size_type N)

void apply_givens_rotation (const std::array< number, 3 > &csr, const size_type i, const size_type k)

virtual void swap (Vector< number > &v)

Vector< number > & operator= (const number s)

Vector< number > & operator= (const Vector< number > &v)

Vector< number > & operator= (Vector< number > &&v) noexcept=default

Vector< number > & operator= (const Vector< Number2 > &v)

Vector< number > & operator= (const BlockVector< number > &v)

Vector< number > & operator= (const PETScWrappers::VectorBase &v)

Vector< number > & operator= (const TrilinosWrappers::MPI::Vector &v)

bool operator== (const Vector< Number2 > &v) const

bool operator!= (const Vector< Number2 > &v) const

number operator* (const Vector< Number2 > &V) const

real_type norm_sqr () const

number mean_value () const

real_type l1_norm () const

real_type l2_norm () const

real_type lp_norm (const real_type p) const

real_type linfty_norm () const

number add_and_dot (const number a, const Vector< number > &V, const Vector< number > &W)

pointer data ()

const_pointer data () const

iterator begin ()

const_iterator begin () const

iterator end ()

const_iterator end () const

number operator() (const size_type i) const

number & operator() (const size_type i)

number operator[] (const size_type i) const

number & operator[] (const size_type i)

void extract_subvector_to (const std::vector< size_type > &indices, std::vector< OtherNumber > &values) const

void extract_subvector_to (ForwardIterator indices_begin, const ForwardIterator indices_end, OutputIterator values_begin) const

Vector< number > & operator+= (const Vector< number > &V)

Vector< number > & operator-= (const Vector< number > &V)

void add (const std::vector< size_type > &indices, const std::vector< OtherNumber > &values)

void add (const std::vector< size_type > &indices, const Vector< OtherNumber > &values)

void add (const size_type n_elements, const size_type *indices, const OtherNumber *values)

void add (const number a, const Vector< number > &V, const number b, const Vector< number > &W)

void add (const number a, const Vector< number > &V)

void sadd (const number s, const Vector< number > &V)

void sadd (const number s, const number a, const Vector< number > &V)

Vector< number > & operator*= (const number factor)

Vector< number > & operator/= (const number factor)

void scale (const Vector< number > &scaling_factors)

void scale (const Vector< Number2 > &scaling_factors)

void equ (const number a, const Vector< number > &u)

void equ (const number a, const Vector< Number2 > &u)

void ratio (const Vector< number > &a, const Vector< number > &b)

void update_ghost_values () const

void print (const char *format=nullptr) const

void print (std::ostream &out, const unsigned int precision=3, const bool scientific=true, const bool across=true) const

void print (LogStream &out, const unsigned int width=6, const bool across=true) const

void block_write (std::ostream &out) const

void save (Archive &ar, const unsigned int version) const

void load (Archive &ar, const unsigned int version)

bool in_local_range (const size_type global_index) const

IndexSet locally_owned_elements () const

size_type size () const

bool all_zero () const

bool is_non_negative () const

std::size_t memory_consumption () const

Public Member Functions inherited from Subscriptor
Subscriptor ()

Subscriptor (const Subscriptor &)

Subscriptor (Subscriptor &&) noexcept

virtual ~Subscriptor ()

Subscriptoroperator= (const Subscriptor &)

Subscriptoroperator= (Subscriptor &&) noexcept

void subscribe (std::atomic< bool > *const validity, const std::string &identifier="") const

void unsubscribe (std::atomic< bool > *const validity, const std::string &identifier="") const

unsigned int n_subscriptions () const

template<typename StreamType >
void list_subscribers (StreamType &stream) const

void list_subscribers () const

template<class Archive >
void serialize (Archive &ar, const unsigned int version)

## Static Public Member Functions

static ::ExceptionBaseExcSizeZero ()

static ::ExceptionBaseExcSizeNonzero ()

static ::ExceptionBaseExcInvalidFilename (std::string arg1)

static ::ExceptionBaseExcInvalidCopyOperation ()

Static Public Member Functions inherited from Subscriptor
static ::ExceptionBaseExcInUse (int arg1, std::string arg2, std::string arg3)

static ::ExceptionBaseExcNoSubscriber (std::string arg1, std::string arg2)

## Private Attributes

std::string filename

Public Types inherited from Vector< number >
using value_type = number

using real_type = typename numbers::NumberTraits< number >::real_type

## 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).
Deprecated:
The usage of this class is deprecated.

Definition at line 61 of file swappable_vector.h.

## ◆ SwappableVector() [1/2]

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

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

## ◆ SwappableVector() [2/2]

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.

## ◆ ~SwappableVector()

template<typename number >
 virtual SwappableVector< number >::~SwappableVector ( )
overridevirtual

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

## ◆ operator=()

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.

## ◆ swap_out()

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 worthwhile 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.

## ◆ kill_file()

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 again.

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.

This throws a ExcIO exception if, for any reason, deleting the file failed.

## ◆ get_filename()

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.

## ◆ memory_consumption()

template<typename number >
 std::size_t SwappableVector< number >::memory_consumption ( ) const

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

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.

## ◆ filename

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.

Definition at line 196 of file swappable_vector.h.

## ◆ lock

template<typename number >
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.

Definition at line 206 of file swappable_vector.h.

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