Commit 0c0ab980 authored by thomas.forbriger's avatar thomas.forbriger Committed by thomas.forbriger
Browse files

adapted files for new libaff concept

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: 1176
SVN UUID:     67feda4a-a26e-11df-9d6e-31afc202ad0c
parent 15f0cfed
......@@ -3,35 +3,39 @@
*
* ----------------------------------------------------------------------------
*
* $Id: array.h,v 1.1 2002-12-06 19:08:18 forbrig Exp $
* $Id: array.h,v 1.2 2002-12-08 22:33:53 forbrig Exp $
* \author Thomas Forbriger
* \date 01/05/2002
* \since 08/12/2002
*
* full template array class headers (prototypes)
*
* \sa contxx
* \sa contxx::Array
* \sa aff
* \sa aff::Array
*
* \todo
* document when and how to use this header
*
* Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
*
* REVISIONS and CHANGES
* - 01/05/2002 V1.0 Thomas Forbriger
* - 08/12/2002 V1.0 copied from libcontxx
*
* ============================================================================
*/
// include guard
#ifndef TF_ARRAY_H_VERSION
#ifndef FF_ARRAY_H_VERSION
#define TF_ARRAY_H_VERSION \
"TF_ARRAY_H V1.0 "
#define TF_ARRAY_H_CVSID \
"$Id: array.h,v 1.1 2002-12-06 19:08:18 forbrig Exp $"
#define FF_ARRAY_H_VERSION \
"FF_ARRAY_H V1.0 "
#define FF_ARRAY_H_CVSID \
"$Id: array.h,v 1.2 2002-12-08 22:33:53 forbrig Exp $"
#define CONTXX_INLINE inline
//! May be used to define inlining levels (not used)
#define AFF_INLINE inline
#include<contxx/array_dec.h>
#include<aff/array_dec.h>
#endif // TF_ARRAY_H_VERSION (includeguard)
#endif // FF_ARRAY_H_VERSION (includeguard)
/* ----- END OF array.h ----- */
......@@ -3,51 +3,54 @@
*
* ----------------------------------------------------------------------------
*
* $Id: array_dec.h,v 1.1 2002-12-06 19:08:18 forbrig Exp $
* $Id: array_dec.h,v 1.2 2002-12-08 22:33:53 forbrig Exp $
* \author Thomas Forbriger
* \date 01/05/2002
* \since 08/12/2002
*
* array class declarations (prototypes)
*
* \note
* This should never be included directly. Use array.h or binarray.h instead.
*
* \todo
* Do we need the using directive?
*
* Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
*
* REVISIONS and CHANGES
* - 01/05/2002 V1.0 Thomas Forbriger
* - 22/11/2002 V1.1
* - use Strided as default
* - index-constructors are deprecated (use shapers)
* - 08/12/2002 V1.0 copied from libcontxx
*
* ============================================================================
*/
// include guard
#ifndef TF_ARRAY_DEC_H_VERSION
#ifndef AFF_ARRAY_DEC_H_VERSION
#define TF_ARRAY_DEC_H_VERSION \
"TF_ARRAY_DEC_H V1.1 "
#define TF_ARRAY_DEC_H_CVSID \
"$Id: array_dec.h,v 1.1 2002-12-06 19:08:18 forbrig Exp $"
#define AFF_ARRAY_DEC_H_VERSION \
"AFF_ARRAY_DEC_H V1.0 "
#define AFF_ARRAY_DEC_H_CVSID \
"$Id: array_dec.h,v 1.2 2002-12-08 22:33:53 forbrig Exp $"
#include <contxx/repr/sharedheap.h>
#include <contxx/shape/strided_repr.h>
#include <contxx/shape/range.h>
#include <aff/sharedheap.h>
#include <aff/strided.h>
#include <aff/range.h>
namespace contxx {
namespace aff {
#ifdef CONTXX_PREBUILT
#ifdef AFF_PREBUILT
namespace prebuilt {
#endif
#ifdef CONTXX_PREBUILT
using namespace contxx::prebuilt::util;
using namespace contxx::prebuilt::shape;
using contxx::prebuilt::representation::SharedHeap;
using contxx::prebuilt::subscriptor::StridedRepresentation;
using namespace aff::prebuilt::util;
using namespace aff::prebuilt::shape;
using aff::prebuilt::representation::SharedHeap;
using aff::prebuilt::subscriptor::StridedRepresentation;
#else
using namespace contxx::util;
using namespace contxx::shape;
using contxx::representation::SharedHeap;
using contxx::subscriptor::StridedRepresentation;
using namespace aff::util;
using namespace aff::shape;
using aff::representation::SharedHeap;
using aff::subscriptor::StridedRepresentation;
#endif
/*! \brief Full multi-dimensional array functionality.
......@@ -66,6 +69,15 @@ namespace prebuilt {
* \sa \ref page_representation
* \sa \ref sec_main_modules
* \sa tests/arraytest.cc
*
* \todo
* documentation of class Array must be reworked
*
* \todo
* class Array must be reworked itself entirely
*
* \todo
* Explain the new concept of multidimensional array indexing
*/
template<class T,
Tdim N=1,
......@@ -155,16 +167,16 @@ namespace prebuilt {
}; // class Array
#ifdef CONTXX_PREBUILT
} // namespace prebuild
#ifdef AFF_PREBUILT
} // namespace prebuilt
#endif
} // namespace contxx
} // namespace aff
#ifndef CONTXX_NO_DEFINITIONS
#include <contxx/array_def.h>
#ifndef AFF_NO_DEFINITIONS
#include <aff/array_def.h>
#endif
#endif // TF_ARRAY_DEC_H_VERSION (includeguard)
#endif // AFF_ARRAY_DEC_H_VERSION (includeguard)
/* ----- END OF array_dec.h ----- */
......@@ -3,46 +3,57 @@
*
* ----------------------------------------------------------------------------
*
* $Id: array_def.h,v 1.1 2002-12-06 19:08:18 forbrig Exp $
* $Id: array_def.h,v 1.2 2002-12-08 22:33:53 forbrig Exp $
* \author Thomas Forbriger
* \date 01/05/2002
* \since 08/12/2002
*
* array class definitions (definitions)
*
* \note
* This header containes definitions of functions of class aff::Array. They
* will be contained in a binary library. You must not include this header
* yourself. It is included via array.h if you use the full template evrsion
* of the library.
*
* \todo
* Do we need the using directive?
*
* \todo rework the whole aff::Array definitions
*
* Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
*
* REVISIONS and CHANGES
* - 01/05/2002 V1.0 Thomas Forbriger
* - 08/12/2002 V1.0 copied from libcontxx
*
* ============================================================================
*/
#ifndef TF_ARRAY_DEC_H_VERSION
#ifndef AFF_ARRAY_DEC_H_VERSION
#error "include this only through array_dec.h"
#endif
// include guard
#ifndef TF_ARRAY_DEF_H_VERSION
#ifndef AFF_ARRAY_DEF_H_VERSION
#define TF_ARRAY_DEF_H_VERSION \
"TF_ARRAY_DEF_H V1.0 "
#define TF_ARRAY_DEF_H_CVSID \
"$Id: array_def.h,v 1.1 2002-12-06 19:08:18 forbrig Exp $"
#define AFF_ARRAY_DEF_H_VERSION \
"AFF_ARRAY_DEF_H V1.0 "
#define AFF_ARRAY_DEF_H_CVSID \
"$Id: array_def.h,v 1.2 2002-12-08 22:33:53 forbrig Exp $"
namespace contxx {
namespace aff {
#ifdef CONTXX_PREBUILT
#ifdef AFF_PREBUILT
namespace prebuilt {
#endif
#ifdef CONTXX_PREBUILT
using namespace contxx::prebuilt::shape;
#ifdef AFF_PREBUILT
using namespace aff::prebuilt::shape;
#else
using namespace contxx::shape;
using namespace aff::shape;
#endif
#ifdef CONTXX_PREBUILT
#ifndef TF_COMPILING_LIBRARY
#ifdef AFF_PREBUILT
#ifndef FF_COMPILING_LIBRARY
#error "definition read in prebuilt mode and not during library compilation"
#endif
#endif
......@@ -128,12 +139,12 @@ namespace prebuilt {
return(*this);
}
#ifdef CONTXX_PREBUILT
#ifdef AFF_PREBUILT
} // namespace prebuilt
#endif
} // namespace contxx
} // namespace aff
#endif // TF_ARRAY_DEF_H_VERSION (includeguard)
#endif // AFF_ARRAY_DEF_H_VERSION (includeguard)
/* ----- END OF array_def.h ----- */
......@@ -3,36 +3,39 @@
*
* ----------------------------------------------------------------------------
*
* $Id: binarray.h,v 1.1 2002-12-06 19:08:18 forbrig Exp $
* $Id: binarray.h,v 1.2 2002-12-08 22:33:53 forbrig Exp $
* \author Thomas Forbriger
* \date 01/05/2002
* \since 08/12/2002
*
* just arrays class definitions (for binary libraray contents) (prototypes)
*
* \sa \ref sec_main_binary
* \sa contxx::Array
* \sa aff::Array
*
* \todo
* Explain the usage of this file.
*
* Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
*
* REVISIONS and CHANGES
* - 01/05/2002 V1.0 Thomas Forbriger
* - 08/12/2002 V1.0 copied from libcontxx
*
* ============================================================================
*/
// include guard
#ifndef TF_BINARRAY_H_VERSION
#ifndef AFF_BINARRAY_H_VERSION
#define TF_BINARRAY_H_VERSION \
"TF_BINARRAY_H V1.0 "
#define TF_BINARRAY_H_CVSID \
"$Id: binarray.h,v 1.1 2002-12-06 19:08:18 forbrig Exp $"
#define AFF_BINARRAY_H_VERSION \
"AFF_BINARRAY_H V1.0 "
#define AFF_BINARRAY_H_CVSID \
"$Id: binarray.h,v 1.2 2002-12-08 22:33:53 forbrig Exp $"
#ifndef TF_COMPILING_LIBRARY
#define CONTXX_NO_DEFINITIONS
#ifndef AFF_COMPILING_LIBRARY
#define AFF_NO_DEFINITIONS
#endif
/*! \def CONTXX_PREBUILT
/*! \def AFF_PREBUILT
*
* This preprocessor macro is set in contxx/binarray.h.
* It requests to place all declarations in contxx::prebuilt to match the
......@@ -41,11 +44,11 @@
* \sa \ref sec_using_include
*/
#ifndef DOXYGEN_MUST_SKIP_THIS
#define CONTXX_PREBUILT
#define AFF_PREBUILT
#endif // DOXYGEN_MUST_SKIP_THIS
#include<contxx/array_dec.h>
#include<aff/array_dec.h>
#endif // TF_BINARRAY_H_VERSION (includeguard)
#endif // AFF_BINARRAY_H_VERSION (includeguard)
/* ----- END OF binarray.h ----- */
......@@ -15,8 +15,8 @@ BRIEF_MEMBER_DESC = NO
REPEAT_BRIEF = NO
ALWAYS_DETAILED_SEC = NO
FULL_PATH_NAMES = YES
STRIP_FROM_PATH = /home/thof/work/src/libs/lib \
/home/theo1/forbrig/ffwork
STRIP_FROM_PATH = /home/thof/ffwork/ \
/home/theo1/forbrig/ffwork/
INTERNAL_DOCS = NO
CLASS_DIAGRAMS = YES
SOURCE_BROWSER = NO
......
......@@ -15,7 +15,8 @@ BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ALWAYS_DETAILED_SEC = YES
FULL_PATH_NAMES = YES
STRIP_FROM_PATH = /home/theo1/forbrig/ffwork
STRIP_FROM_PATH = /home/theo1/forbrig/ffwork/ \
/home/thof/ffwork/
INTERNAL_DOCS = YES
CLASS_DIAGRAMS = YES
SOURCE_BROWSER = YES
......
......@@ -3,32 +3,35 @@
*
* ----------------------------------------------------------------------------
*
* $Id: iterator.h,v 1.1 2002-12-06 19:08:18 forbrig Exp $
* $Id: iterator.h,v 1.2 2002-12-08 22:33:53 forbrig Exp $
* \author Thomas Forbriger
* \date 23/11/2002
* \since 08/12/2002
*
* Define the iterator class template (prototypes)
*
* \todo
* This file is still empty...
*
* Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
*
* REVISIONS and CHANGES
* - 23/11/2002 V1.0 Thomas Forbriger
* - 08/12/2002 V1.0 copied from libcontxx
*
* ============================================================================
*/
// include guard
#ifndef TF_ITERATOR_H_VERSION
#ifndef AFF_ITERATOR_H_VERSION
#define TF_ITERATOR_H_VERSION \
"TF_ITERATOR_H V1.0 "
#define TF_ITERATOR_H_CVSID \
"$Id: iterator.h,v 1.1 2002-12-06 19:08:18 forbrig Exp $"
#define AFF_ITERATOR_H_VERSION \
"AFF_ITERATOR_H V1.0 "
#define AFF_ITERATOR_H_CVSID \
"$Id: iterator.h,v 1.2 2002-12-08 22:33:53 forbrig Exp $"
namespace tf {
namespace aff {
}
} // namespace aff
#endif // TF_ITERATOR_H_VERSION (includeguard)
#endif // AFF_ITERATOR_H_VERSION (includeguard)
/* ----- END OF iterator.h ----- */
......@@ -3,65 +3,58 @@
*
* ----------------------------------------------------------------------------
*
* $Id: README,v 1.1 2002-12-06 19:27:39 forbrig Exp $
* $Id: README,v 1.2 2002-12-08 22:33:53 forbrig Exp $
*
* Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
*
* about the concept of memory representations
*
* \todo
* Explain namespace aff::util
*
* \todo
* Entirely rework this README
*
* This file contains documentation for
* - namespace contxx::representation
* - namespace aff::utl
* - \ref page_representation
* - The template parameter Representation
*
* REVISIONS and CHANGES
* - 04/05/2002 V1.0 Thomas Forbriger
* - 21/11/2002 V1.1 entirely reworked
* - 08/12/2002 V1.0 copied from libcontxx
*
* ============================================================================
*/
namespace contxx {
namespace aff {
/*! \brief Namespace contains all memory representations
*
* A comprehensive discussion is presented on page \ref page_representation.
/*! \brief ???
*
* 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
* \todo
* Explain namespace util
*/
namespace representation {
} // representation
} // contxx
namespace util {
} // util
} // aff
/*======================================================================*/
/*! \page page_representation The concept of represented memory
The array and iterator classes in this library shoulb be insulated from the
Contents of this page:
- \ref sec_representation_sharedheap
The array and iterator classes in this library should 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.
Also they should be able to share references to the same memory area.
Since returning an array from a function automatically invokes the copy
constructor, this should have reference semantics
\sa contxx::Array
\sa \ref sec_main_modules_representation
\sa \ref sec_design_copy
/*----------------------------------------------------------------------*/
\section sec_representation_types Types of memory representations
There are several design concepts for implemented or planned memory
representations.
\section sec_representation_sharedheap Shared heap
\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
......@@ -71,7 +64,6 @@ representation through the template parameter Representation.
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.
......@@ -82,14 +74,12 @@ representation through the template parameter Representation.
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
......@@ -99,213 +89,20 @@ representation through the template parameter Representation.
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.
This is implemented by class aff::SharedHeap.
It is presented in aff/lib/sharedheap.h
\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.
\todo
This a very old and possibly a bit out-dated part of the documentation. It
was copied several times and has definitely t be reviewed.
\par
This is implemented by class contxx::representation::Global.
It is presented in repr/global.h
\todo
Explain the need and mechanism for memory reference without reference
counting and automatic destruction.
\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".
\sa \ref sec_design_const
*/
/*======================================================================*/
/*! \brief Base class category "Representation"