Commit 45f4e5a0 authored by thomas.forbriger's avatar thomas.forbriger Committed by thomas.forbriger
Browse files

just copied

This is a legacy commit from before 2015-03-01.
It may be incomplete as well as inconsistent.
See COPYING.legacy and README.history for details.


SVN Path:     http://gpitrsvn.gpi.uni-karlsruhe.de/repos/TFSoftware/trunk
SVN Revision: 1172
SVN UUID:     67feda4a-a26e-11df-9d6e-31afc202ad0c
parent 2f3ea8f4
/*! \file repr/README
* \brief about the concept of memory representations
*
* ----------------------------------------------------------------------------
*
* $Id: README,v 1.1 2002-12-06 19:27:39 forbrig Exp $
*
* Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
*
* about the concept of memory representations
*
* This file contains documentation for
* - namespace contxx::representation
* - \ref page_representation
* - The template parameter Representation
*
* REVISIONS and CHANGES
* - 04/05/2002 V1.0 Thomas Forbriger
* - 21/11/2002 V1.1 entirely reworked
*
* ============================================================================
*/
namespace contxx {
/*! \brief Namespace contains all memory representations
*
* A comprehensive discussion is presented on page \ref page_representation.
*
* A representation class for the contxx::Array is selected through the
* template parameter Representation.
* Defined representation classes are
* -# contxx::representation::SharedHeap
* -# contxx::representation::NormalHeap
* -# contxx::representation::Global
* -# contxx::representation::Rigid
*/
namespace representation {
} // representation
} // contxx
/*======================================================================*/
/*! \page page_representation The concept of represented memory
The array and iterator classes in this library shoulb be insulated from the
representation of the handled data in memory.
All topics of memory allocation and array representation copying is delegated
to representation classes that are collected in namespace
contxx:representation.
When using the array class definition, the user may select a certain
representation through the template parameter Representation.
\sa contxx::Array
\sa \ref sec_main_modules_representation
/*----------------------------------------------------------------------*/
\section sec_representation_types Types of memory representations
There are several design concepts for implemented or planned memory
representations.
\par Shared heap (implemented):
This type of memory access was the main reason to implement this array class
module from scratch. It implements array handle semantics. On creation this
class allocates memory on the free store (heap) to be used for the array
elements. On a copy only a reference to the free store location is copied.
Thus always a shallow copy is performed. The represenation itself takes care
about the number of instances referencing the free store location. On
destruction of the last of these instances, the free store location is
freed.
\par
Creating an array projection may be
done by copying the representation (reference to free store) with an array
instance that only accesses a subset of the elements in the heap location.
Thus projections may be created as true arrays (you don't have do
distinguish between projections and true arrays in your code - like the
sliced arrays in the STL must). However,
changes applied to the array alements through the projection imediately
affects the full array, in fact all array copies are affected by any
"write"-operation to the array.
\par
This way of memory access allows easy and cheap copying of arrays. We may
pass them freely to functions or receive them as return values. It doesn't
matter where the array is actually created. Itself takes care about memory
allocation. And it always does a shallow copy, with almost no overhead to
passing a reference.
\par
By this mechanism, we may hold different projections to the same data, which
are all full qualified arrays (even with possibly different dimensionality).
For example, we may hold a complete set of earth parameters. We may like to
address them either in the sense of inversion parameters as a full set or in
the sense of there physical meaning. In the latter case we may like to
address the p-velocities as a subset. However, when any of the (anonymous)
inversion parameters are changed, the change should immediatly be reflected
by the projection that represents the physical parameters and vice versa.
\par
This is implemented by class contxx::representation::SharedHeap.
It is presented in repr/sharedheap.h
\par Normal heap (implemented):
This is almost the same as "shared heap". However, in this case each
instance allocates its own area in the free store. Thus copy is always a
deep copy. And you don't have shared access to the arrays element values.
This might only be of interest in cases where it is explicitly desireable
that every instance holds it's own copy, since the runtime overhead is
significant.
\par
This is implemented by class contxx::representation::NormalHeap.
It is presented in repr/normalheap.h
\par Elementary stack (implemented):
This implementation is comparable to the "normal heap" approach. It also
does a deep copy. But it does not allocate free store. It uses fixed size
build in arrays. Thus the size of the array has to be known at compile-time
and must be passed as a template parameter.
\par
This is implemented by class contxx::representation::Rigid.
It is presented in repr/rigid.h
\par External (global) heap (implemented):
This approach is used to access global free store that is allocated outside
of the scope of the C++ modules. This is the case if you use Fortran code
together with C++, when the Fortran module holds data in arrays, that are
made global through common blocks. In this case it might be helpful to
access this data from C++ code through standard array interfaces.
\par
The memory representation will behave exactly the same as the "shared heap"
representation. In particular only shallow copies are provided. But it does
not apply reference counting, since the global data is assumed to be
persistent. Changes applied to the arrays data affect the Fortran common
blocks immediatly. Instances of this type may only be created from special
code that has pointer-access to the global persitent store.
\par
This is implemented by class contxx::representation::Global.
It is presented in repr/global.h
\par Collectable shared heap:
This is an extension to "shared heap". While shared heap memory may be
subdivided into pieces by the means of arrays projections, it is not
possible to combine independently allocated chunks of shared heap. To allow
concatenation of previously independent heap memory to make it accessible
through one array instance (while all preexisting array instances still
point to their data), a special mechanism of double referencing must be
implemented. The use of this may be rather limited and the involved overhead
may be significant.
Any of these memory representations may be selected by passing an appropriate
class definition to the contxx::Array classes through the Representation
template parameter.
The default value for the Representation parameter is
contxx::representation::SharedHeap.
/*----------------------------------------------------------------------*/
\section sec_representation_const Notes on the const-correctness of arrays
Arrays using the shared heap representation have reference semantics.
Different instances will access the same data in memory. Copying an array
instance just copies a reference to the data. This mechanism is not obvious to
the compiler. The array instances are values in the sense of C++ types and not
references.
Generally it has to be defined, what is meant by declaring an array instance
to be \c const. In the first place this means constness of the container to
the compiler. The compiler will ensure, that the container (array class) is
not changed, thus no data member of the array is changed. This means that the
array will keep the reference to the same data and that the index-mapping
defined by the array shape may not be changed. However, the compiler will not
prevent to change any data, the array refers to.
We may define access operators that have a non-const version that returns a
reference to the data, allowing to change the data values together with a const
version that returns a value of const reference, thus preventing the data from
being changed through an instance that is declared const. However, the
compiler will always allow to create a non-const copy of a const array
instance. In the sense of const-ness of C++ data, this does not violate the
const-ness of the source of the copy. the shape of the original array may not
be changed. Only the shape of the copy may be changed. But the data of the
original array may now be changed through the copied instance, since our array
classes implicitly have reference semantic. Thus we have to distinguish
between const-ness of the container (array class instance) and the contained
data (values in memory the arrays refers to).
In this library we will not provide a const and a non-const version of the
array classes. With templated code it is more convenient to use an array with
element type \c const \c T as the const version of an array with element type
\c T. To allow copying of an instance with element type \c T to an instance of
type \c const \c T, we have to provide explicit conversion operators. A
special class Qualified allows automatic specialization of array classes and
representations to use the correct element type conversion in the class
conversion operators.
- The need of const-correctness is discussed in "Chapter 1 Introduction, C++
Conventions, Implementation of Vector and Matrix Classes" of "Numerical
Recipes in C++". A link to a PDF file of this chapter is provided at
"http://www.nr.com/cpp-blurb.html".
- The "C++ FAQ Lite" discusses many aspects of const-correctness in
Chapter 18, which you find at
"http://www.inf.uni-konstanz.de/~kuehl/cpp/cppfaq.htm/const-correctness.html".
- You may find my thoughts about const-correctness with containers that have
reference semantics at
"http://www.geophysik.uni-frankfurt.de/~forbrig/txt/cxx/tutorial/consthandle.doc/doc/html/index.html".
*/
/*======================================================================*/
/*! \brief Base class category "Representation"
This template parameter is passed to contxx::Array. It selects one of the
available representation classes that are presented in namespace
contxx::representation.
contxx::Array passes the template argument Representation to Subscriptor,
which again uses it to select the correct representation. Inheritance from
the representation classes is typically public.
A comprehensive discussion of represented memory is
presented on page \ref page_representation.
\param T type of array elements
Classes of this category are
-# contxx::representation::SharedHeap
-# contxx::representation::NormalHeap
-# contxx::representation::Global
-# contxx::representation::Rigid
\sa \ref page_representation
\sa \ref sec_main_modules_representation
\sa \ref sec_arrays_represented
\par Interface specification
The full set of constructors (default, size and, copy), the copy operator,
the const and non-const index operator, the size() query function, and the
conversion operator Tcontainer_of_const() are mandatory. In particular the
typedef interface is mandatory, because it ensures meaningful conversions
to const element types (remember that the template parameter T may already
by a const type).
\sa \ref sec_main_constness
\sa \ref sec_representation_const
*/
template<class T>
class Representation {
public:
//! Element type
typedef typename Qualified<T>::Tvalue Tvalue;
//! Type of pointer to element
typedef typename Qualified<T>::Tpointer Tpointer;
//! Type of reference to element
typedef typename Qualified<T>::Treference Treference;
//! Type of const reference to element
typedef typename Qualified<T>::Tconst_reference Tconst_reference;
//! Type to be used as data representation
typedef typename Qualified<T>::Tmutable_value Tmutable_value;
//! Type to be used as element for const version
typedef typename Qualified<T>::Tconst_value Tconst_value;
//! Type of Representation for container of const elements
typedef Representation<Tconst_value> Tcontainer_of_const;
//! Create from nothing.
Representation();
//! Allocate new heap memory.
Representation(const Tsize& size);
//! Copy constructor
Representation(const Representation& sharedheap);
//! Destructor
~Representation();
//! Copy operator
Representation& operator=(const Representation& representation);
/*! Return size (always inline).
* \retval size of array on heap.
*/
inline
const Tsize& size() const;
/*! Return array access.
* \return pointer to array on heap
*/
Tpointer array();
//! Index operator (always inline).
inline
Treference operator[](const Tsubscript& i) ;
//! Index operator (always inline).
inline
Tconst_reference operator[](const Tsubscript& i) const;
//! conversion operator
operator Tcontainer_of_const() const;
}; // Representation
// ----- END OF README -----
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment