.. index:: single: Views .. _views: Views ----- .. cpp:namespace:: zfp |zfp| |viewsrelease| adds array views. Much like how :ref:`references ` allow indirect access to single array elements, *views* provide indirect access to whole arrays, or more generally to rectangular subsets of arrays. A view of an array does not allocate any storage for the array elements. Rather, the view accesses shared storage managed by the underlying array. This allows for multiple entries into an array without the need for expensive deep copies. In a sense, views can be thought of as *shallow copies* of arrays. When a view exposes a whole array :code:`array`, it provides similar functionality to a C++ reference :code:`array&` or pointer :code:`array*` to the array. However, views are more general in that they also allow restricting access to a user-specified subset of the array, and unlike pointers also provide for the same syntax when accessing the array, e.g., :code:`array_view(i, j)` instead of :code:`(*array_ptr)(i, j)`. |zfp|'s *nested views* further provide for multidimensional array access analogous to the C/C++ nested array syntax :code:`array[i][j]`. Finally, |zfp|'s *private views* can be used to ensure thread-safe access to its compressed arrays. Access to array elements through a view is via inspectors and mutators that return a :code:`const_reference` or :code:`reference`, respectively (see :ref:`references`). As of |zfp| |crpirelease|, it is also possible to obtain pointers to array elements through views and to iterate over them. View pointers and iterators allow referencing only the elements visible through the view, e.g., a rectangular subset of an array (see :numref:`view-indexing`). Those elements are indexed as if the view were a contiguous array, and pointer arithmetic assumes that the possibly smaller view and not the underlying array is flattened. :ref:`Private views ` maintain their own cache and therefore implement their own proxy references, pointers, and iterators. .. _view-indexing: .. figure:: view-indexing.pdf :figwidth: 90 % :align: center :alt: "2D view indexing" An 11 |times| 9 element view of a 2D array of dimensions 16 |times| 12. The numbered elements indicate the order in which the view is traversed using pointers and iterators. We have :code:`view(10, 7) == (&view(0, 0))[87] == view.begin()[97] == view.end()[-2]`. With the |zfp| |carrrelease| release of :ref:`read-only arrays `, such arrays also support the two kinds of immutable views (:code:`const_view` and :code:`private_const_view`). The documentation below applies to views into read-only arrays as well. .. note:: Like iterators and proxy references and pointers, a view is valid only during the lifetime of the array that it references. **No reference counting** is done to keep the array alive. It is up to the user to ensure that the referenced array object is valid when accessed through a view. There are several types of views distinguished by these attributes: * Read-only vs. read-write access. * Shared vs. private access. * Flat vs. nested indexing. Each of these attributes is discussed in detail below in these sections: * :ref:`immutable_view` * :ref:`mutable_view` * :ref:`flat_view` * :ref:`nested_view` * :ref:`slicing` * :ref:`private_immutable_view` * :ref:`private_mutable_view` .. _immutable_view: Immutable view ^^^^^^^^^^^^^^ The most basic view is the immutable :code:`const_view`, which supports read-only access to the array elements it references. This view serves primarily as a base class for more specialized views. Its constructors allow establishing access to a whole array or to a rectangular subset of an array. Note that like references, pointers, and iterators, views are types nested within the arrays that they reference. .. .. cpp:class:: template array1::const_view .. cpp:class:: template array2::const_view .. cpp:class:: template array3::const_view .. cpp:class:: template array4::const_view .. cpp:class:: array1::const_view .. cpp:class:: array2::const_view .. cpp:class:: array3::const_view .. cpp:class:: array4::const_view Immutable view into 1D, 2D, 3D, and 4D array. ---- .. _view_ctor: .. cpp:function:: array1::const_view::const_view(array1* array) .. cpp:function:: array2::const_view::const_view(array2* array) .. cpp:function:: array3::const_view::const_view(array3* array) .. cpp:function:: array4::const_view::const_view(array4* array) Constructor for read-only access to a whole array. As already mentioned, these views are valid only during the lifetime of the underlying array object. ---- .. cpp:function:: array1::const_view::const_view(array1* array, size_t x, size_t nx) .. cpp:function:: array2::const_view::const_view(array2* array, size_t x, size_t y, size_t nx, size_t ny) .. cpp:function:: array3::const_view::const_view(array3* array, size_t x, size_t y, size_t z, size_t nx, size_t ny, size_t nz) .. cpp:function:: array4::const_view::const_view(array4* array, size_t x, size_t y, size_t z, size_t w, size_t nx, size_t ny, size_t nz, size_t nw) Constructors for read-only access to a rectangular subset of an array. The subset is specified by an offset, e.g., (*x*, *y*, *z*) for a 3D array, and dimensions, e.g., (*nx*, *ny*, *nz*) for a 3D array. The rectangle must fit within the surrounding array. ---- .. cpp:function:: size_t array1::const_view::global_x(size_t i) const .. cpp:function:: size_t array2::const_view::global_x(size_t i) const .. cpp:function:: size_t array2::const_view::global_y(size_t j) const .. cpp:function:: size_t array3::const_view::global_x(size_t i) const .. cpp:function:: size_t array3::const_view::global_y(size_t j) const .. cpp:function:: size_t array3::const_view::global_z(size_t k) const .. cpp:function:: size_t array4::const_view::global_x(size_t i) const .. cpp:function:: size_t array4::const_view::global_y(size_t j) const .. cpp:function:: size_t array4::const_view::global_z(size_t k) const .. cpp:function:: size_t array4::const_view::global_w(size_t l) const Return global array index associated with local view index. For instance, if a 1D view has been constructed with offset *x*, then :code:`global_x(i)` returns *x* + *i*. ---- .. cpp:function:: size_t array1::const_view::size_x() const .. cpp:function:: size_t array2::const_view::size_x() const .. cpp:function:: size_t array2::const_view::size_y() const .. cpp:function:: size_t array3::const_view::size_x() const .. cpp:function:: size_t array3::const_view::size_y() const .. cpp:function:: size_t array3::const_view::size_z() const .. cpp:function:: size_t array4::const_view::size_x() const .. cpp:function:: size_t array4::const_view::size_y() const .. cpp:function:: size_t array4::const_view::size_z() const .. cpp:function:: size_t array4::const_view::size_w() const Return dimensions of view. ---- .. _view_accessor: .. cpp:function:: const_reference array1::const_view::operator()(size_t i) const .. cpp:function:: const_reference array2::const_view::operator()(size_t i, size_t j) const .. cpp:function:: const_reference array3::const_view::operator()(size_t i, size_t j, size_t k) const .. cpp:function:: const_reference array4::const_view::operator()(size_t i, size_t j, size_t k, size_t l) const Return reference to scalar stored at multi-dimensional index given by *x* + *i*, *y* + *j*, *z* + *k*, and *w* + *l*, where *x*, *y*, *z*, and *w* specify the offset into the array. ---- .. cpp:function:: const_reference array1::const_view::operator[](size_t index) const Alternative inspector for 1D arrays identical to :cpp:func:`array1::const_view::operator()`. ---- .. cpp:function:: array1::const_view::const_iterator array1::const_view::begin() const .. cpp:function:: array2::const_view::const_iterator array2::const_view::begin() const .. cpp:function:: array3::const_view::const_iterator array3::const_view::begin() const .. cpp:function:: array4::const_view::const_iterator array4::const_view::begin() const .. cpp:function:: array1::const_view::const_iterator array1::const_view::cbegin() const .. cpp:function:: array2::const_view::const_iterator array2::const_view::cbegin() const .. cpp:function:: array3::const_view::const_iterator array3::const_view::cbegin() const .. cpp:function:: array4::const_view::const_iterator array4::const_view::cbegin() const Random-access const iterator to first element of view. ---- .. cpp:function:: array1::const_view::const_iterator array1::const_view::end() const .. cpp:function:: array2::const_view::const_iterator array2::const_view::end() const .. cpp:function:: array3::const_view::const_iterator array3::const_view::end() const .. cpp:function:: array4::const_view::const_iterator array4::const_view::end() const .. cpp:function:: array1::const_view::const_iterator array1::const_view::cend() const .. cpp:function:: array2::const_view::const_iterator array2::const_view::cend() const .. cpp:function:: array3::const_view::const_iterator array3::const_view::cend() const .. cpp:function:: array4::const_view::const_iterator array4::const_view::cend() const Random-access const iterator to end of view. There are a number of common methods inherited from a base class, :code:`preview`, further up the class hierarchy. .. cpp:function:: double arrayANY::const_view::rate() const Return rate in bits per value. Same as :cpp:func:`array::rate`. ---- .. cpp:function:: size_t arrayANY::const_view::size() const Total number of elements in view, e.g., *nx* |times| *ny* |times| *nz* for 3D views. With the above definitions, the following example shows how a 2D view is constructed and accessed:: zfp::array2d a(200, 100, rate); // define 200x100 array of doubles zfp::array2d::const_view v(&a, 10, 5, 20, 20); // v is a 20x20 view into array a assert(v(2, 1) == a(12, 6)); // v(2, 1) == a(10 + 2, 5 + 1) == a(12, 6) assert(v.size() == 400); // 20x20 == 400 .. _mutable_view: Mutable view ^^^^^^^^^^^^ The basic mutable :code:`view` derives from the :code:`const_view` but adds operators for write-access. Its constructors are similar to those for the :code:`const_view`. .. .. cpp:class:: template array1::view .. cpp:class:: template array2::view .. cpp:class:: template array3::view .. cpp:class:: template array4::view .. cpp:class:: array1::view : public array1::const_view .. cpp:class:: array2::view : public array2::const_view .. cpp:class:: array3::view : public array3::const_view .. cpp:class:: array4::view : public array4::const_view Mutable view into 1D, 2D, 3D, and 4D array. ---- .. cpp:function:: array1::view::view(array1* array) .. cpp:function:: array2::view::view(array2* array) .. cpp:function:: array3::view::view(array3* array) .. cpp:function:: array4::view::view(array4* array) .. cpp:function:: array1::view::view(array1* array, size_t x, size_t nx) .. cpp:function:: array2::view::view(array2* array, size_t x, size_t y, size_t nx, size_t ny) .. cpp:function:: array3::view::view(array3* array, size_t x, size_t y, size_t z, size_t nx, size_t ny, size_t nz) .. cpp:function:: array4::view::view(array4* array, size_t x, size_t y, size_t z, size_t w, size_t nx, size_t ny, size_t nz, size_t nw) Whole-array and sub-array mutable view constructors. See :ref:`const_view constructors ` for details. ---- .. cpp:function:: reference array1::view::operator()(size_t i) .. cpp:function:: reference array2::view::operator()(size_t i, size_t j) .. cpp:function:: reference array3::view::operator()(size_t i, size_t j, size_t k) .. cpp:function:: reference array4::view::operator()(size_t i, size_t j, size_t k, size_t l) These operators, whose arguments have the same meaning as in the :ref:`array accessors `, return :ref:`proxy references ` to individual array elements for write access. .. _flat_view: Flat view ^^^^^^^^^ The views discussed so far require multidimensional indexing, e.g., (*i*, *j*, *k*) for 3D views. Some applications prefer one-dimensional linear indexing, which is provided by the specialized flat view. For example, in a 3D view with dimensions (*nx*, *ny*, *nz*), a multidimensional index (*i*, *j*, *k*) corresponds to the flat view index :: index = i + nx * (j + ny * k) This is true regardless of the view offset (*x*, *y*, *z*). The flat view derives from the mutable view and adds :code:`operator[]` for flat indexing. This operator is essentially equivalent to :cpp:func:`array::operator[]` defined for 2D, 3D, and 4D arrays. Flat views also provide functions for converting between multidimensional and flat indices. Flat views are available only for 2D, 3D, and 4D arrays. The basic mutable view, :cpp:class:`array1::view`, for 1D arrays can be thought of as either a flat or a nested view. .. .. cpp:class:: template array2::flat_view .. cpp:class:: template array3::flat_view .. cpp:class:: template array4::flat_view .. cpp:class:: array2::flat_view : public array2::view .. cpp:class:: array3::flat_view : public array3::view .. cpp:class:: array4::flat_view : public array4::view Flat, mutable views for 2D, 3D, and 4D arrays. ---- .. cpp:function:: array2::flat_view::flat_view(array2* array) .. cpp:function:: array3::flat_view::flat_view(array3* array) .. cpp:function:: array4::flat_view::flat_view(array4* array) .. cpp:function:: array2::flat_view::flat_view(array2* array, size_t x, size_t y, size_t nx, size_t ny) .. cpp:function:: array3::flat_view::flat_view(array3* array, size_t x, size_t y, size_t z, size_t nx, size_t ny, size_t nz) .. cpp:function:: array4::flat_view::flat_view(array4* array, size_t x, size_t y, size_t z, size_t w, size_t nx, size_t ny, size_t nz, size_t nw) Whole-array and sub-array flat view constructors. See :ref:`const_view constructors ` for details. ---- .. cpp:function:: size_t array2::flat_view::index(size_t i, size_t j) const .. cpp:function:: size_t array3::flat_view::index(size_t i, size_t j, size_t k) const .. cpp:function:: size_t array4::flat_view::index(size_t i, size_t j, size_t k, size_t l) const Return flat index associated with multidimensional index. ---- .. cpp:function:: void array2::flat_view::ij(size_t& i, size_t& j, size_t index) const .. cpp:function:: void array3::flat_view::ijk(size_t& i, size_t& j, size_t& k, size_t index) const .. cpp:function:: void array4::flat_view::ijkl(size_t& i, size_t& j, size_t& k, size_t& l, size_t index) const Convert flat index to multidimensional index. ---- .. cpp:function:: const_reference array2::flat_view::operator[](size_t index) const .. cpp:function:: const_reference array3::flat_view::operator[](size_t index) const .. cpp:function:: const_reference array4::flat_view::operator[](size_t index) const Return array element associated with given flat index. ---- .. cpp:function:: reference array2::flat_view::operator[](size_t index) .. cpp:function:: reference array3::flat_view::operator[](size_t index) .. cpp:function:: reference array4::flat_view::operator[](size_t index) Return reference to array element associated with given flat index. .. _nested_view: Nested view ^^^^^^^^^^^ C and C++ support nested arrays (arrays of arrays), e.g., :code:`double a[10][20][30]`, which are usually accessed via nested indexing :code:`a[i][j][k]`. Here :code:`a` is a 3D array, :code:`a[i]` is a 2D array, and :code:`a[i][j]` is a 1D array. This 3D array can also be accessed via flat indexing, e.g., :: a[i][j][k] == (&a[0][0][0])[600 * i + 30 * j + k] Nested views provide a mechanism to access array elements through nested indexing and to extract lower-dimensional "slices" of multidimensional arrays. Nested views are mutable. Nested views are associated with a dimensionality. For instance, if :code:`v` is a 3D nested view of a 3D array, then :code:`v[i]` is a 2D nested view (of a 3D array), :code:`v[i][j]` is a 1D nested view (of a 3D array), and :code:`v[i][j][k]` is a (reference to a) scalar array element. Note that the order of indices is reversed when using nested indexing compared to multidimensional indexing, e.g., :code:`v(i, j, k) == v[k][j][i]`. Whereas :code:`operator[]` on an array object accesses an element through flat indexing, the same array can be accessed through a nested view to in effect provide nested array indexing:: zfp::array3d a(30, 20, 10, rate); // define 30x20x10 3D array assert(a[32] == a(2, 1, 0)); // OK: flat and multidimensional indexing assert(a[32] == a[0][1][2]); // ERROR: a does not support nested indexing zfp::array3d::nested_view v(&a); // define a nested view of a assert(a[32] == v[0][1][2]); // OK: v supports nested indexing zfp::array2d b(v[5]); // define and deep copy 30x20 2D slice of a assert(a(2, 1, 5) == b(2, 1)); // OK: multidimensional indexing .. .. cpp:class:: template array2::nested_view1 .. cpp:class:: array2::nested_view1 View of a 1D slice of a 2D array. ---- .. .. cpp:class:: template array2::nested_view2 .. cpp:class:: array2::nested_view2 2D view of a 2D (sub)array. ---- .. .. cpp:class:: template array3::nested_view1 .. cpp:class:: array3::nested_view1 View of a 1D slice of a 3D array. ---- .. .. cpp:class:: template array3::nested_view2 .. cpp:class:: array3::nested_view2 View of a 2D slice of a 3D array. ---- .. .. cpp:class:: template array3::nested_view3 .. cpp:class:: array3::nested_view3 3D view of a 3D (sub)array. ---- .. .. cpp:class:: template array4::nested_view1 .. cpp:class:: array4::nested_view1 View of a 1D slice of a 4D array. ---- .. .. cpp:class:: template array4::nested_view2 .. cpp:class:: array4::nested_view2 View of a 2D slice of a 4D array. ---- .. .. cpp:class:: template array4::nested_view3 .. cpp:class:: array4::nested_view3 View of a 3D slice of a 4D array. ---- .. .. cpp:class:: template array4::nested_view4 .. cpp:class:: array4::nested_view4 4D view of a 4D (sub)array. ---- .. cpp:function:: array2::nested_view2::nested_view2(array2* array) .. cpp:function:: array3::nested_view3::nested_view3(array3* array) .. cpp:function:: array4::nested_view4::nested_view4(array4* array) .. cpp:function:: array2::nested_view2::nested_view2(array2* array, size_t x, size_t y, size_t nx, size_t ny) .. cpp:function:: array3::nested_view3::nested_view3(array3* array, size_t x, size_t y, size_t z, size_t nx, size_t ny, size_t nz) .. cpp:function:: array4::nested_view4::nested_view4(array4* array, size_t x, size_t y, size_t z, size_t w, size_t nx, size_t ny, size_t nz, size_t nw) Whole-array and sub-array nested view constructors. See :ref:`const_view ` constructors for details. Lower-dimensional view constructors are not accessible to the user but are invoked when accessing views via nested indexing. ---- .. cpp:function:: size_t array2::nested_view1::size_x() const .. cpp:function:: size_t array2::nested_view2::size_x() const .. cpp:function:: size_t array2::nested_view2::size_y() const .. cpp:function:: size_t array3::nested_view1::size_x() const .. cpp:function:: size_t array3::nested_view2::size_x() const .. cpp:function:: size_t array3::nested_view2::size_y() const .. cpp:function:: size_t array3::nested_view3::size_x() const .. cpp:function:: size_t array3::nested_view3::size_y() const .. cpp:function:: size_t array3::nested_view3::size_z() const .. cpp:function:: size_t array4::nested_view1::size_x() const .. cpp:function:: size_t array4::nested_view2::size_x() const .. cpp:function:: size_t array4::nested_view2::size_y() const .. cpp:function:: size_t array4::nested_view3::size_x() const .. cpp:function:: size_t array4::nested_view3::size_y() const .. cpp:function:: size_t array4::nested_view3::size_z() const .. cpp:function:: size_t array4::nested_view4::size_x() const .. cpp:function:: size_t array4::nested_view4::size_y() const .. cpp:function:: size_t array4::nested_view4::size_z() const .. cpp:function:: size_t array4::nested_view4::size_w() const View dimensions. ---- .. cpp:function:: array4::nested_view3 array4::nested_view4::operator[](size_t index) const Return view to a 3D slice of 4D array. ---- .. cpp:function:: array3::nested_view2 array3::nested_view3::operator[](size_t index) const .. cpp:function:: array4::nested_view2 array4::nested_view3::operator[](size_t index) const Return view to a 2D slice of a 3D or 4D array. ---- .. cpp:function:: array2::nested_view1 array2::nested_view2::operator[](size_t index) const .. cpp:function:: array3::nested_view1 array3::nested_view2::operator[](size_t index) const .. cpp:function:: array4::nested_view1 array4::nested_view2::operator[](size_t index) const Return view to a 1D slice of a 2D, 3D, or 4D array. ---- .. cpp:function:: const_reference array2::nested_view1::operator[](size_t index) const .. cpp:function:: const_reference array3::nested_view1::operator[](size_t index) const .. cpp:function:: const_reference array4::nested_view1::operator[](size_t index) const Return scalar element of a 2D, 3D, or 4D array. ---- .. cpp:function:: reference array2::nested_view1::operator[](size_t index) .. cpp:function:: reference array3::nested_view1::operator[](size_t index) .. cpp:function:: reference array4::nested_view1::operator[](size_t index) Return reference to a scalar element of a 2D, 3D, or 4D array. ---- .. cpp:function:: const_reference array2::nested_view1::operator()(size_t i) const .. cpp:function:: const_reference array2::nested_view2::operator()(size_t i, size_t j) const .. cpp:function:: const_reference array3::nested_view1::operator()(size_t i) const .. cpp:function:: const_reference array3::nested_view2::operator()(size_t i, size_t j) const .. cpp:function:: const_reference array3::nested_view3::operator()(size_t i, size_t j, size_t k) const .. cpp:function:: const_reference array4::nested_view1::operator()(size_t i) const .. cpp:function:: const_reference array4::nested_view2::operator()(size_t i, size_t j) const .. cpp:function:: const_reference array4::nested_view3::operator()(size_t i, size_t j, size_t k) const .. cpp:function:: const_reference array4::nested_view4::operator()(size_t i, size_t j, size_t k, size_t l) const Return const reference to a scalar element of a 2D, 3D, or 4D array. ---- .. cpp:function:: reference array2::nested_view1::operator()(size_t i) .. cpp:function:: reference array2::nested_view2::operator()(size_t i, size_t j) .. cpp:function:: reference array3::nested_view1::operator()(size_t i) .. cpp:function:: reference array3::nested_view2::operator()(size_t i, size_t j) .. cpp:function:: reference array3::nested_view3::operator()(size_t i, size_t j, size_t k) .. cpp:function:: reference array4::nested_view1::operator()(size_t i) .. cpp:function:: reference array4::nested_view2::operator()(size_t i, size_t j) .. cpp:function:: reference array4::nested_view3::operator()(size_t i, size_t j, size_t k) .. cpp:function:: reference array4::nested_view4::operator()(size_t i, size_t j, size_t k, size_t l) Return reference to a scalar element of a 2D, 3D, or 4D array. .. _slicing: Slicing ^^^^^^^ Arrays can be constructed as deep copies of slices of higher-dimensional arrays, as the code example above shows (i.e., :code:`zfp::array2d b(v[5]);`). Unlike views, which have reference semantics, such array *slicing* has value semantics. In this example, 2D array *b* is initialized as a (deep) copy of a slice of 3D array *a* via nested view *v*. Subsequent modifications of *b* have no effect on *a*. Slicing is implemented as array constructors templated on views. Upon initialization, elements are copied one at a time from the view via multidimensional indexing, e.g., :code:`v(i, j, k)`. Note that view and array dimensionalities must match, but aside from this an array may be constructed from any view. Slicing needs not change the dimensionality, but can be used to copy an equidimensional subset of one array to another array, as in this example:: zfp::array3d a(30, 20, 10, rate); zfp::array3d::const_view v(&a, 1, 2, 3, 4, 5, 6); zfp::array3d b(v); assert(b(0, 0, 0) == a(1, 2, 3)); assert(b.size_x() == 4); assert(b.size_y() == 5); assert(b.size_z() == 6); Slicing adds the following templated array constructors. .. cpp:function:: template array1::array1(const View& v) .. cpp:function:: template array2::array2(const View& v) .. cpp:function:: template array3::array3(const View& v) .. cpp:function:: template array4::array4(const View& v) Construct array from a view via a deep copy. The view, *v*, must support :ref:`multidimensional indexing `. The rate for the constructed array is initialized to the rate of the array associated with the view. Note that the actual rate may differ if the constructed array is a lower-dimensional slice of a higher-dimensional array due to lower rate granularity (see FAQ :ref:`#12 `). The cache size of the constructed array is set to the default size. .. _private_immutable_view: Private immutable view ^^^^^^^^^^^^^^^^^^^^^^ |zfp|'s compressed arrays are in general not thread-safe. The main reason for this is that each array maintains its own cache of uncompressed blocks. Race conditions on the cache would occur unless it were locked upon each and every array access, which would have a prohibitive performance cost. To ensure thread-safe access, |zfp| provides private mutable and immutable views of arrays that maintain their own private caches. The :code:`private_const_view` immutable view provides read-only access to the underlying array. It is similar to a :ref:`const_view ` in this sense, but differs in that it maintains its own private cache rather than sharing the cache owned by the array. Multiple threads may thus access the same array in parallel through their own private views. .. note:: Thread safety is ensured only for OpenMP threads, and the |zfp| views must be compiled by an OpenMP compliant compiler. As the |zfp| compressed-array class implementation is defined in headers, the application code using |zfp| must also be compiled with OpenMP enabled if multithreaded access to |zfp| arrays is desired. .. note:: Private views **do not guarantee cache coherence**. If, for example, the array is modified, then already cached data in a private view is not automatically updated. It is up to the user to ensure cache coherence by flushing (compressing modified blocks) or clearing (emptying) caches when appropriate. The cache associated with a private view can be manipulated in the same way an array's cache can. For instance, the user may set the cache size on a per-view basis. Unlike with :ref:`private mutable views `, private immutable views may freely access any element in the array visible through the view, i.e., multiple threads may read the same array element simultaneously. For an example of how to use private views for both read and write multithreaded access, see the :ref:`diffusion ` code example. Private views support only multidimensional indexing, i.e., they are neither flat nor nested. .. .. cpp:class:: template array1::private_const_view .. cpp:class:: template array2::private_const_view .. cpp:class:: template array3::private_const_view .. cpp:class:: template array4::private_const_view .. _private_const_view: .. cpp:class:: array1::private_const_view .. cpp:class:: array2::private_const_view .. cpp:class:: array3::private_const_view .. cpp:class:: array4::private_const_view Immutable views of 1D, 2D, 3D, and 4D arrays with private caches. ---- .. cpp:function:: array1::private_const_view::private_const_view(array1* array) .. cpp:function:: array2::private_const_view::private_const_view(array2* array) .. cpp:function:: array3::private_const_view::private_const_view(array3* array) .. cpp:function:: array4::private_const_view::private_const_view(array4* array) .. cpp:function:: array1::private_const_view::private_const_view(array1* array, size_t x, size_t nx) .. cpp:function:: array2::private_const_view::private_const_view(array2* array, size_t x, size_t y, size_t nx, size_t ny) .. cpp:function:: array3::private_const_view::private_const_view(array3* array, size_t x, size_t y, size_t z, size_t nx, size_t ny, size_t nz) .. cpp:function:: array4::private_const_view::private_const_view(array4* array, size_t x, size_t y, size_t z, size_t w, size_t nx, size_t ny, size_t nz, size_t nw) Whole-array and sub-array private immutable view constructors. See :ref:`const_view constructors ` for details. ---- .. cpp:function:: size_t array1::private_const_view::size_x() const .. cpp:function:: size_t array2::private_const_view::size_x() const .. cpp:function:: size_t array2::private_const_view::size_y() const .. cpp:function:: size_t array3::private_const_view::size_x() const .. cpp:function:: size_t array3::private_const_view::size_y() const .. cpp:function:: size_t array3::private_const_view::size_z() const .. cpp:function:: size_t array4::private_const_view::size_x() const .. cpp:function:: size_t array4::private_const_view::size_y() const .. cpp:function:: size_t array4::private_const_view::size_z() const .. cpp:function:: size_t array4::private_const_view::size_w() const View dimensions. ---- .. cpp:function:: const_reference array1::private_const_view::operator()(size_t i) const .. cpp:function:: const_reference array2::private_const_view::operator()(size_t i, size_t j) const .. cpp:function:: const_reference array3::private_const_view::operator()(size_t i, size_t j, size_t k) const .. cpp:function:: const_reference array4::private_const_view::operator()(size_t i, size_t j, size_t k, size_t l) const Return const reference to scalar element of a 1D, 2D, 3D, or 4D array. The following functions are common among all dimensionalities: .. cpp:function:: size_t arrayANY::private_const_view::cache_size() const .. cpp:function:: void arrayANY::private_const_view::set_cache_size(size_t csize) .. cpp:function:: void arrayANY::private_const_view::clear_cache() const Cache manipulation. See :ref:`caching` for details. .. _private_mutable_view: Private mutable view ^^^^^^^^^^^^^^^^^^^^ The mutable :code:`private_view` supports both read and write access and is backed by a private cache. Because block compression, as needed to support write access, is not an atomic operation, mutable views and multithreading imply potential race conditions on the compressed blocks stored by an array. Although locking the array or individual blocks upon compression would be a potential solution, this would either serialize compression, thus hurting performance, or add a possibly large memory overhead by maintaining a lock with each block. .. note:: To avoid multiple threads simultaneously compressing the same block, **private mutable views of an array must reference disjoint, block-aligned subarrays** for thread-safe access. Each block of |4powd| array elements must be associated with at most one private mutable view, and therefore these views must reference non-overlapping rectangular subsets that are aligned on block boundaries, except possibly for partial blocks on the array boundary. (Expert users may alternatively ensure serialization of block compression calls and cache coherence in other ways, in which case overlapping private views may be permitted.) Aside from this requirement, the user may partition the array into disjoint views in whatever manner is suitable for the application. The :code:`private_view` API supplies a very basic partitioner to facilitate this task, but may not result in optimal partitions or good load balance. When multithreaded write access is desired, any direct accesses to the array itself (i.e., not through a view) could invoke compression. Even a read access may trigger compression if a modified block is evicted from the cache. Hence, such direct array accesses should be confined to serial code sections when private views are used. As with private immutable views, **cache coherence is not enforced**. Although this is less of an issue for private mutable views due to the requirement that views may not overlap, each private mutable view overlaps an index space with the underlying array whose cache is not automatically synchronized with the view's private cache. See the :ref:`diffusion ` for an example of how to enforce cache coherence with mutable and immutable private views. The :code:`private_view` class inherits all public functions from :code:`private_const_view`. .. .. cpp:class:: template array1::private_view .. cpp:class:: template array2::private_view .. cpp:class:: template array3::private_view .. cpp:class:: template array4::private_view .. cpp:class:: array1::private_view : public array1::private_const_view .. cpp:class:: array2::private_view : public array2::private_const_view .. cpp:class:: array3::private_view : public array3::private_const_view .. cpp:class:: array4::private_view : public array4::private_const_view Mutable views of 1D, 2D, 3D, and 4D arrays with private caches. ---- .. .. cpp:class:: template array1::private_view::view_reference .. cpp:class:: template array2::private_view::view_reference .. cpp:class:: template array3::private_view::view_reference .. cpp:class:: template array4::private_view::view_reference .. cpp:class:: array1::private_view::view_reference .. cpp:class:: array2::private_view::view_reference .. cpp:class:: array3::private_view::view_reference .. cpp:class:: array4::private_view::view_reference Proxy references to array elements specialized for mutable private views. ---- .. cpp:function:: array1::private_view::private_view(array1* array) .. cpp:function:: array2::private_view::private_view(array2* array) .. cpp:function:: array3::private_view::private_view(array3* array) .. cpp:function:: array4::private_view::private_view(array4* array) .. cpp:function:: array1::private_view::private_view(array1* array, size_t x, size_t nx) .. cpp:function:: array2::private_view::private_view(array2* array, size_t x, size_t y, size_t nx, size_t ny) .. cpp:function:: array3::private_view::private_view(array3* array, size_t x, size_t y, size_t z, size_t nx, size_t ny, size_t nz) .. cpp:function:: array4::private_view::private_view(array4* array, size_t x, size_t y, size_t z, size_t w, size_t nx, size_t ny, size_t nz, size_t nw) Whole-array and sub-array private mutable view constructors. See :ref:`const_view constructors ` for details. ---- .. cpp:function:: array1::private_view::view_reference array1::private_view::operator()(size_t i) const .. cpp:function:: array2::private_view::view_reference array2::private_view::operator()(size_t i, size_t j) const .. cpp:function:: array3::private_view::view_reference array3::private_view::operator()(size_t i, size_t j, size_t k) const .. cpp:function:: array4::private_view::view_reference array4::private_view::operator()(size_t i, size_t j, size_t k, size_t l) const Return reference to a scalar element of a 1D, 2D, 3D, or 4D array. The following functions are common among all dimensionalities: .. cpp:function:: void arrayANY::private_view::partition(size_t index, size_t count) Partition the current view into *count* roughly equal-size pieces along the view's longest dimension and modify the view's extents to match the piece indexed by *index*, with 0 |leq| *index* < *count*. These functions may be called multiple times, e.g., to recursively partition along different dimensions. The partitioner does not generate new views; it merely modifies the current values of the view's offsets and dimensions. Note that this may result in empty views whose dimensions are zero, e.g., if there are more pieces than blocks along a dimension. ---- .. cpp:function:: void arrayANY::private_view::flush_cache() const Flush cache by compressing any modified blocks and emptying the cache.