mirror of
https://github.com/triqs/dft_tools
synced 2024-11-01 11:43:47 +01:00
106 lines
4.5 KiB
ReStructuredText
106 lines
4.5 KiB
ReStructuredText
.. highlight:: c
|
|
|
|
.. _partial_views:
|
|
|
|
Views
|
|
==============================================================
|
|
|
|
**Synopsis**:
|
|
|
|
.. code-block:: c
|
|
|
|
template <typename ValueType, int Rank, ull_t OptionsFlags=0, ull_t TraversalOrder=0 > class array_view;
|
|
template <typename ValueType, ull_t OptionsFlags=0, ull_t TraversalOrder=0 > class matrix_view;
|
|
template <typename ValueType, ull_t OptionsFlags=0> class vector_view;
|
|
|
|
where triqs::ull_t is the type defined by :
|
|
|
|
.. code-block:: c
|
|
|
|
typedef unsigned long long ull_t;
|
|
|
|
The view classes have the same template parameters to the regular type.
|
|
|
|
|
|
* A `view` is defined as a view of a restricted portion of the array, matrix or vector.
|
|
|
|
* The view type of X (= array, matrix, vector) is called X_view, with the same template parameters as the regular type.
|
|
|
|
* A partial view models the :ref:`MutableCuboidArray`, :ref:`MutableMatrix`, :ref:`MutableVector`, like the corresponding regular type.
|
|
|
|
* Basically X_view should be understood as a reference to the data of the viewed object,
|
|
dressed to model the "`MutableX`" concept.
|
|
|
|
* A view class behaves like the value class when called, put in expression, ...
|
|
but differs from it by its behaviour under copy and assignment.
|
|
It has a reference semantics : like a pointer or a reference, it does not make a deep copy of the data
|
|
when copied. See :ref:`view_vs_regular` for a detailed discussion of the difference between array and array_view.
|
|
|
|
|
|
|
|
====================================================================== =====================================================================================================
|
|
Constructors of array_view Comments
|
|
====================================================================== =====================================================================================================
|
|
array_view(const array_view &) Copy construction (makes a shallow copy)
|
|
array_view(const T & X) T is any type such that X.indexmap() and X.storage() can be used to construct a view.
|
|
REF to concept here ....
|
|
====================================================================== =====================================================================================================
|
|
|
|
|
|
Memory management
|
|
------------------------
|
|
|
|
View classes contains a reference counting system to the memory block they view
|
|
(like a std::shared_ptr, but more sophisticated to properly interface to Python numpy).
|
|
|
|
This guarantees that memory will not be dellocated before the destruction of the view.
|
|
|
|
The memory block will be dellocated when its array and all array_view
|
|
pointing to it or to a portion of it will be destroyed, and only at that moment.
|
|
|
|
Example::
|
|
|
|
array<int,2> *p = new array<int,2> (2,3); // create an array p
|
|
array_view<int,2> B = *p; // making a view
|
|
delete p; // p is gone...
|
|
B(0,0) = 314; cout<<B<<endl; // B (and the data) is still alive
|
|
|
|
|
|
.. warning::
|
|
|
|
TRIQS arrays, and in particular views are NOT thread-safe, contrary to std::shared_ptr.
|
|
This is a deliberate choice for optimisation.
|
|
|
|
|
|
Weak views [Advanced]
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Unfortunately this can not be the end of the story, at least on current C++11 compilers.
|
|
It turns out that, in very performance sensitive loops, increasing this tiny
|
|
reference counter can break a lot of optimisations in almost all compilers, including the most
|
|
recent ones (gcc 4.8, clang 3.3).
|
|
|
|
It was therefore decided to introduce `weak views`.
|
|
|
|
* Weak views are completely similar to "normal" views, except that they do `not` increase the memory
|
|
reference counter.
|
|
|
|
* Normal views are be implicitely constructed from weak view (the reverse is also true),
|
|
As soon as you store the weak view into a normal view (e.g. array_view<T,N>)
|
|
the reference counting is again incremented, and the memory guarantee holds.
|
|
|
|
* Explicit construction of weak views is intentionally not documented here.
|
|
It is designed to be (almost) an implementation detail.
|
|
|
|
* The () operator returns a weak view `on a modern C++11 compiler`,
|
|
allowing therefore for better performance on such compiler, in some loops.
|
|
(in particular, `rvalue reference for *this` must be implemented).
|
|
|
|
* It is however necessary for the advanced user to know about this implementation detail,
|
|
because in some convolved cases, the memory guarantee may not hold.
|
|
Example :
|
|
|
|
|
|
|
|
|