Commit 2acd15c6 authored by thomas.forbriger's avatar thomas.forbriger Committed by thomas.forbriger
Browse files

reworked lib/README

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: 1225
SVN UUID:     67feda4a-a26e-11df-9d6e-31afc202ad0c
parent 1dfd6737
......@@ -3,7 +3,7 @@
*
* ----------------------------------------------------------------------------
*
* $Id: README.changelog,v 1.13 2002-12-20 12:21:04 forbrig Exp $
* $Id: README.changelog,v 1.14 2002-12-20 14:12:50 forbrig Exp $
*
* Copyright (c) 2002 by Thomas Forbriger (IMG Frankfurt)
*
......@@ -20,7 +20,7 @@
/*! \page page_changelog ChangeLog (AFF)
$Id: README.changelog,v 1.13 2002-12-20 12:21:04 forbrig Exp $
$Id: README.changelog,v 1.14 2002-12-20 14:12:50 forbrig Exp $
\sa \ref page_project_status
......@@ -37,6 +37,7 @@
declarations of stepper classes, because we do not like to include the
full stepper header if we don't use it).
- introduced aff::Iterator class template
- reworked lib/README
- \b 19/12/2002 (thof)
- \b !! aff::Array provides access to base classes through access
......@@ -72,7 +73,7 @@
/*! \page page_project_status Project status (AFF)
$Id: README.changelog,v 1.13 2002-12-20 12:21:04 forbrig Exp $
$Id: README.changelog,v 1.14 2002-12-20 14:12:50 forbrig Exp $
\sa \ref page_changelog
......@@ -120,7 +121,7 @@
<TD> </TD><TD> </TD><TD> </TD><TD> </TD>
</TR>
<TR><TD>libaff/lib/README</TD>
<TD>has no code</TD><TD> </TD><TD>has no code</TD><TD> </TD>
<TD>has no code</TD><TD>20/12/02</TD><TD>has no code</TD><TD> </TD>
</TR>
<TR><TD>libaff/lib/error.cc</TD>
<TD>16/12/02</TD><TD> </TD><TD>18/12/02</TD><TD> </TD>
......
......@@ -3,18 +3,12 @@
*
* ----------------------------------------------------------------------------
*
* $Id: README,v 1.2 2002-12-08 22:33:53 forbrig Exp $
* $Id: README,v 1.3 2002-12-20 14:12:51 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 aff::utl
* - \ref page_representation
......@@ -27,10 +21,10 @@
namespace aff {
/*! \brief ???
/*! \brief Internal utilities
*
* \todo
* Explain namespace util
* In this namespace we collect modules that need not necessarily be exposed
* to the user.
*/
namespace util {
} // util
......@@ -42,12 +36,23 @@ namespace util {
Contents of this page:
- \ref sec_representation_sharedheap
- \ref sec_representation_introduction
\section sec_representation_introduction Introduction
The array and iterator classes in this library should be insulated from the
representation of the handled data in memory.
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
constructor, this representation should have reference semantics.
Using the same representation class (here aff::SharedHeap) as a basis for all
containers (like aff::Array and aff::Series) and iterators, we may easily
convert an aff::Series into an aff::Array without copying the data. Both
objects just provide a different access interface to the data in memory.
To use memory representations with reference semantics has some implications
for the definition of the assignment operator. We have to decide between a
deep copy (elementwise copy) and a shallow copy (copying the representation).
\sa \ref sec_design_copy
......@@ -55,8 +60,8 @@ constructor, this should have reference semantics
\section sec_representation_sharedheap Shared heap
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
This type of memory access
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
......@@ -64,15 +69,21 @@ constructor, this should have reference semantics
destruction of the last of these instances, the free store location is
freed.
Additionally aff::SharedHeap offers a facility to take a global memory
pointer on creation. In this case, memory management lies outside the
representation class and the underlying aff::SHeap object will \em never
call the delete operator in the destructor. This is usefull when interfacing
arrays allocated trhough Fortran code subroutines.
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.
changes applied to the array elements through the projection imediately
affects the full array, in fact data of all array copies are affected by
"write"-operations to the instances.
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
......@@ -82,24 +93,21 @@ constructor, this should have reference semantics
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
For example, we may hold a complete set of earth model 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.
The same memory data may even be shared by objects of different class types.
In this way an aff::Array may interface the same data in memory as a
simultaneous aff::Series object.
This is implemented by class aff::SharedHeap.
It is presented in aff/lib/sharedheap.h
\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.
\todo
Explain the need and mechanism for memory reference without reference
counting and automatic destruction.
\sa \ref sec_design_const
*/
......
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