diff --git a/docs/source/API/containers/DynRankView.rst b/docs/source/API/containers/DynRankView.rst index a712adcea..bcc3be880 100644 --- a/docs/source/API/containers/DynRankView.rst +++ b/docs/source/API/containers/DynRankView.rst @@ -1,405 +1,410 @@ ``DynRankView`` =============== -.. role:: cpp(code) - :language: cpp +.. role:: cppkokkos(code) + :language: cppkokkos -Header File: ``Kokkos_DynRankView.hpp`` +Header File: ```` Class Interface --------------- -.. cpp:class:: template DynRankView +.. cppkokkos:class:: template DynRankView - A potentially reference counted multidimensional array with compile time layouts and memory space. Its semantics are similar to that of :cpp:`std::shared_ptr`. The :cpp:`DynRankView` differs from the :cpp:`Kokkos::View` in that its rank is not provided with the :cpp:`DataType` template parameter; it is determined dynamically based on the number of extent arguments passed to the constructor. The rank has an upper bound of 7 dimensions. +.. cppkokkos:class:: template DynRankView - Template parameters other than :any:`DataType` are optional, but ordering is enforced. That means for example that :cpp:`LayoutType` can be omitted but if both :cpp:`MemorySpace` and :cpp:`MemoryTraits` are specified, :cpp:`MemorySpace` must come before :cpp:`MemoryTraits`. +.. cppkokkos:class:: template DynRankView - :tparam DataType: Defines the fundamental scalar type of the :cpp:`DynRankView`. The basic structure is :cpp:`ScalarType`. Examples: +.. cppkokkos:class:: template DynRankView - * :cpp:`double`: a :cpp:`DynRankView` of :cpp:`double` , dimensions are passed as arguments to the constructor, the number of which determine the rank. + A potentially reference counted multidimensional array with compile time layouts and memory space. Its semantics are similar to that of ``std::shared_ptr``. The ``DynRankView`` differs from the ``Kokkos::View`` in that its rank is not provided with the ``DataType`` template parameter; it is determined dynamically based on the number of extent arguments passed to the constructor. The rank has an upper bound of 7 dimensions. - :tparam LayoutType: Determines the mapping of indices into the underlying 1D memory storage. Custom Layouts can be implemented, but Kokkos comes with some built-in ones: + Template parameters other than ``DataType`` are optional, but ordering is enforced. That means for example that ``LayoutType`` can be omitted but if both ``MemorySpace`` and ``MemoryTraits`` are specified, ``MemorySpace`` must come before ``MemoryTraits``. - * :cpp:`LayoutRight`: Strides increase from the right most to the left most dimension. The last dimension has a stride of one. This corresponds to how C multi dimensional arrays (\ ``[][][]``\ ) are laid out in memory. - * :cpp:`LayoutLeft`: Strides increase from the left most to the right most dimension. The first dimension has a stride of one. This is the layout Fortran uses for its arrays. - * :cpp:`LayoutStride`: Strides can be arbitrary for each dimension. + :tparam DataType: Defines the fundamental scalar type of the ``DynRankView``. The basic structure is ``ScalarType``. Examples: - :tparam MemorySpace: Controls the storage location. If omitted, the default memory space of the default execution space is used (i.e. :cpp:`Kokkos::DefaultExecutionSpace::memory_space`) - :tparam MemoryTraits: Sets access properties via enum parameters for the templated :cpp:`Kokkos::MemoryTraits<>` class. Enums can be bit combined. Possible values: + * ``double``: a ``DynRankView`` of ``double``, dimensions are passed as arguments to the constructor, the number of which determine the rank. - * :cpp:`Unmanaged`: The DynRankView will not be reference counted. The allocation has to be provided to the constructor. - * :cpp:`Atomic`: All accesses to the view will use atomic operations. - * :cpp:`RandomAccess`: Hint that the view is used in a random access manner. If the view is also ``const``\ , this will trigger special load operations on GPUs (i.e. texture fetches). - * :cpp:`Restrict`: There is no aliasing of the view by other data structures in the current scope. + :tparam LayoutType: Determines the mapping of indices into the underlying 1D memory storage. Custom Layouts can be implemented, but Kokkos comes with some built-in ones: - .. rubric:: Public Member Variables + * ``LayoutRight``: Strides increase from the right most to the left most dimension. The last dimension has a stride of one. This corresponds to how C multi dimensional arrays (\ ``[][][]``\ ) are laid out in memory. + * ``LayoutLeft``: Strides increase from the left most to the right most dimension. The first dimension has a stride of one. This is the layout Fortran uses for its arrays. + * ``LayoutStride``: Strides can be arbitrary for each dimension. - .. cpp:member:: static constexpr unsigned rank + :tparam MemorySpace: Controls the storage location. If omitted, the default memory space of the default execution space is used (i.e. ``Kokkos::DefaultExecutionSpace::memory_space``) + :tparam MemoryTraits: Sets access properties via enum parameters for the templated ``Kokkos::MemoryTraits<>`` class. Enums can be bit combined. Possible values: - the rank of the view (i.e. the dimensionality). + * ``Unmanaged``: The DynRankView will not be reference counted. The allocation has to be provided to the constructor. + * ``Atomic``: All accesses to the view will use atomic operations. + * ``RandomAccess``: Hint that the view is used in a random access manner. If the view is also ``const``\ , this will trigger special load operations on GPUs (i.e. texture fetches). + * ``Restrict``: There is no aliasing of the view by other data structures in the current scope. - .. cpp:member:: static constexpr unsigned rank_dynamic + .. rubric:: Public Member Variables - the number of runtime determined dimensions. + .. cppkokkos:member:: static constexpr unsigned rank - .. cpp:member:: static constexpr bool reference_type_is_lvalue_reference + The rank of the view (i.e. the dimensionality). - whether the reference type is a C++ lvalue reference. + .. cppkokkos:member:: static constexpr unsigned rank_dynamic - .. rubric:: Data Types + The number of runtime determined dimensions. - .. cpp:type:: data_type + .. cppkokkos:member:: static constexpr bool reference_type_is_lvalue_reference - The :cpp:`DataType` of the DynRankView. + Whether the reference type is a C++ lvalue reference. - .. cpp:type:: const_data_type + .. rubric:: Data Types - The const version of :cpp:`DataType`, same as :cpp:`data_type` if that is already const. + .. cppkokkos:type:: data_type - .. cpp:type:: non_const_data_type + The ``DataType`` of the DynRankView. - The non-const version of :cpp:`DataType`, same as :cpp:`data_type` if that is already non-const. + .. cppkokkos:type:: const_data_type - .. cpp:type:: scalar_array_type + The const version of ``DataType``, same as ``data_type`` if that is already const. - If :cpp:`DataType` represents some properly specialised array data type such as Sacado FAD types, :cpp:`scalar_array_type` is the underlying fundamental scalar type. + .. cppkokkos:type:: non_const_data_type - .. cpp:type:: const_scalar_array_type + The non-const version of ``DataType``, same as ``data_type`` if that is already non-const. - The const version of :cpp:`scalar_array_type`, same as :cpp:`scalar_array_type` if that is already const + .. cppkokkos:type:: scalar_array_type - .. cpp:type:: non_const_scalar_array_type + If ``DataType`` represents some properly specialised array data type such as Sacado FAD types, ``scalar_array_type`` is the underlying fundamental scalar type. - The non-Const version of :cpp:`scalar_array_type`, same as :cpp:`scalar_array_type` if that is already non-const. + .. cppkokkos:type:: const_scalar_array_type - .. rubric:: Scalar Types + The const version of ``scalar_array_type``, same as ``scalar_array_type`` if that is already const - .. cpp:type:: value_type + .. cppkokkos:type:: non_const_scalar_array_type - The :cpp:`data_type` stripped of its array specifiers, i.e. the scalar type of the data the view is referencing (e.g. if :cpp:`data_type` is :cpp:`const int*******`, :cpp:`value_type` is :cpp:`const int`. + The non-Const version of ``scalar_array_type``, same as ``scalar_array_type`` if that is already non-const. - .. cpp:type:: const_value_type + .. rubric:: Scalar Types - The const version of :cpp:`value_type`. + .. cppkokkos:type:: value_type - .. cpp:type:: non_const_value_type + The ``data_type`` stripped of its array specifiers, i.e. the scalar type of the data the view is referencing (e.g. if ``data_type`` is ``const int*******``, ``value_type`` is ``const int``). - The non-const version of :cpp:`value_type`. + .. cppkokkos:type:: const_value_type - .. rubric:: Spaces + The const version of ``value_type``. - .. cpp:type:: execution_space + .. cppkokkos:type:: non_const_value_type - The Execution Space associated with the view, will be used for performing view initialization, and certain :cpp:`deep_copy` operations. + The non-const version of ``value_type``. - .. cpp:type:: memory_space + .. rubric:: Spaces - The data storage location type. + .. cppkokkos:type:: execution_space - .. cpp:type:: device_type + The Execution Space associated with the view, will be used for performing view initialization, and certain ``deep_copy`` operations. - The compound type defined by :cpp:`Device` + .. cppkokkos:type:: memory_space - .. cpp:type:: memory_traits + The data storage location type. - The memory traits of the view. + .. cppkokkos:type:: device_type - .. cpp:type:: host_mirror_space + The compound type defined by ``Device``. - The host accessible memory space used in :cpp:`HostMirror`. + .. cppkokkos:type:: memory_traits - .. rubric:: View Types + The memory traits of the view. - .. cpp:type:: non_const_type + .. cppkokkos:type:: host_mirror_space - The view type with all template parameters explicitly defined. + The host accessible memory space used in ``HostMirror``. - .. cpp:type:: const_type + .. rubric:: View Types - The view type with all template parameters explicitly defined using a :cpp:`const` data type. + .. cppkokkos:type:: non_const_type - .. cpp:type:: HostMirror + The view type with all template parameters explicitly defined. - A compatible view type with the same :cpp:`DataType` and :cpp:`LayoutType` stored in host accessible memory space. + .. cppkokkos:type:: const_type - .. rubric:: Data Handle Types + The view type with all template parameters explicitly defined using a ``const`` data type. - .. cpp:type:: reference_type + .. cppkokkos:type:: HostMirror - The return type of the view access operators. + A compatible view type with the same ``DataType`` and ``LayoutType`` stored in host accessible memory space. - .. cpp:type:: pointer_type + .. rubric:: Data Handle Types - The pointer to scalar type. + .. cppkokkos:type:: reference_type - .. rubric:: Other Types + The return type of the view access operators. - .. cpp:type:: array_layout + .. cppkokkos:type:: pointer_type - The layout of the :cpp:`DynRankView`. + The pointer to scalar type. - .. cpp:type:: size_type + .. rubric:: Other Types - The index type associated with the memory space of this view. + .. cppkokkos:type:: array_layout - .. cpp:type:: dimension + The layout of the ``DynRankView``. - An integer array like type, able to represent the extents of the view. + .. cppkokkos:type:: size_type - .. cpp:type:: specialize + The index type associated with the memory space of this view. - A specialization tag used for partial specialization of the mapping construct underlying a Kokkos :cpp:`DynRankView`. + .. cppkokkos:type:: dimension - .. rubric:: Constructors + An integer array like type, able to represent the extents of the view. - .. cpp:function:: DynRankView() + .. cppkokkos:type:: specialize - The default constructor. No allocations are made, no reference counting happens. All extents are zero and its data pointer is :cpp:`nullptr` and its rank is set to 0. + A specialization tag used for partial specialization of the mapping construct underlying a Kokkos ``DynRankView``. - .. cpp:function:: DynRankView(const DynRankView& rhs) + .. rubric:: Constructors - The copy constructor with compatible DynRankViews. Follows DynRankView assignment rules. + .. cppkokkos:function:: DynRankView() - .. cpp:function:: DynRankView(DynRankView&& rhs) + The default constructor. No allocations are made, no reference counting happens. All extents are zero and its data pointer is ``nullptr`` and its rank is set to 0. - The move constructor. + .. cppkokkos:function:: DynRankView(const DynRankView& rhs) - .. cpp:function:: DynRankView(const View & rhs ) + The copy constructor with compatible DynRankViews. Follows DynRankView assignment rules. - The copy constructor taking View as input. + .. cppkokkos:function:: DynRankView(DynRankView&& rhs) - .. cpp:function:: DynRankView(const std::string& name, const IntType& ... indices) + The move constructor. - *Requires:* :cpp:`array_layout::is_regular == true` + .. cppkokkos:function:: DynRankView(const View & rhs) - The standard allocating constructor. + The copy constructor taking View as input. - :param name: a user provided label, which is used for profiling and debugging purposes. Names are not required to be unique - :param indices: the runtime dimensions of the view + .. cppkokkos:function:: DynRankView(const std::string& name, const IntType& ... indices) - .. cpp:function:: DynRankView(const std::string& name, const array_layout& layout) + *Requires:* ``array_layout::is_regular == true`` - The standard allocating constructor. + The standard allocating constructor. - :param name: a user provided label, which is used for profiling and debugging purposes. Names are not required to be unique - :param layout: the instance of a layout class + :param name: a user provided label, which is used for profiling and debugging purposes. Names are not required to be unique + :param indices: the runtime dimensions of the view - .. cpp:function:: DynRankView(const AllocProperties& prop, , const IntType& ... indices) + .. cppkokkos:function:: DynRankView(const std::string& name, const array_layout& layout) - *Requires:* :cpp:`array_layout::is_regular == true` + The standard allocating constructor. - The allocating constructor with allocation properties. An allocation properties object is returned by the :cpp:`view_alloc` function. + :param name: a user provided label, which is used for profiling and debugging purposes. Names are not required to be unique + :param layout: the instance of a layout class - :param indices: the runtime dimensions of the view + .. cppkokkos:function:: DynRankView(const AllocProperties& prop, const IntType& ... indices) - .. cpp:function:: DynRankView(const AllocProperties& prop, const array_layout& layout) + *Requires:* ``array_layout::is_regular == true`` - The allocating constructor with allocation properties and a layout object. + The allocating constructor with allocation properties. An allocation properties object is returned by the ``view_alloc`` function. - :param layout: the instance of a layout class + :param indices: the runtime dimensions of the view - .. cpp:function:: DynRankView(const pointer_type& ptr, const IntType& ... indices) + .. cppkokkos:function:: DynRankView(const AllocProperties& prop, const array_layout& layout) - *Requires:* :cpp:`array_layout::is_regular == true` + The allocating constructor with allocation properties and a layout object. - The unmanaged data wrapping constructor. + :param layout: the instance of a layout class - :param ptr: pointer to a user provided memory allocation. Must provide storage of size :cpp:`DynRankView::required_allocation_size(n0,...,nR)` - :param indices: the runtime dimensions of the view + .. cppkokkos:function:: DynRankView(const pointer_type& ptr, const IntType& ... indices) - .. cpp:function:: DynRankView(const std::string& name, const array_layout& layout) + *Requires:* ``array_layout::is_regular == true`` - The unmanaged data wrapper constructor. + The unmanaged data wrapping constructor. - :param ptr: pointer to a user provided memory allocation. Must provide storage of size :cpp:`DynRankView::required_allocation_size(layout)` (\ *NEEDS TO BE IMPLEMENTED*\ ) - :param layout: the instance of a layout class + :param ptr: pointer to a user provided memory allocation. Must provide storage of size ``DynRankView::required_allocation_size(n0,...,nR)`` + :param indices: the runtime dimensions of the view - .. cpp:function:: DynRankView( const ScratchSpace& space, const IntType& ... indices) + .. cppkokkos:function:: DynRankView(const std::string& name, const array_layout& layout) - The constructor which acquires memory from a Scratch Memory handle. + The unmanaged data wrapper constructor. - *Requires:* :cpp:`sizeof(IntType...)==rank_dynamic()` *and* :cpp:`array_layout::is_regular == true`. + :param ptr: pointer to a user provided memory allocation. Must provide storage of size ``DynRankView::required_allocation_size(layout)`` (\ *NEEDS TO BE IMPLEMENTED*\ ) + :param layout: the instance of a layout class - :param space: scratch memory handle. Typically returned from ``team_handles`` in ``TeamPolicy`` kernels - :param indices: the runtime dimensions of the view + .. cppkokkos:function:: DynRankView( const ScratchSpace& space, const IntType& ... indices) - .. cpp:function:: DynRankView(const ScratchSpace& space, const array_layout& layout) + The constructor which acquires memory from a Scratch Memory handle. - The constructor which acquires memory from a Scratch Memory handle. + *Requires:* ``sizeof(IntType...)==rank_dynamic()`` *and* ``array_layout::is_regular == true``. - :param space: scratch memory handle. Typically returned from :cpp:`team_handles` in :cpp:`TeamPolicy` kernels. - :param layout: the instance of a layout class + :param space: scratch memory handle. Typically returned from ``team_handles`` in ``TeamPolicy`` kernels + :param indices: the runtime dimensions of the view - .. cpp:function:: DynRankView(const DynRankView& rhs, Args ... args) + .. cppkokkos:function:: DynRankView(const ScratchSpace& space, const array_layout& layout) - The subview constructor. See ``subview`` function for arguments. + The constructor which acquires memory from a Scratch Memory handle. - .. rubric:: Data Access Functions + :param space: scratch memory handle. Typically returned from ``team_handles`` in ``TeamPolicy`` kernels. + :param layout: the instance of a layout class - .. cpp:function:: reference_type operator() (const IntType& ... indices) const + .. cppkokkos:function:: DynRankView(const DynRankView& rhs, Args ... args) - :return: a value of :cpp:`reference_type` which may or not be reference itself. The number of index arguments must match the :any:`rank` of the view. See notes on :cpp:`reference_type` for properties of the return type. + The subview constructor. See ``subview`` function for arguments. - .. cpp:function:: reference_type access (const IntType& i0=0, ... , const IntType& i6=0) const + .. rubric:: Data Access Functions - :return: a value of :cpp:`reference_type` which may or not be reference itself. The number of index arguments must be equal or larger than the :any:`rank` of the view. Index arguments beyond :any:`rank` must be :cpp:`0` , which will be enforced if :cpp:`KOKKOS_DEBUG` is defined. See notes on :cpp:`reference_type` for properties of the return type. + .. cppkokkos:function:: reference_type operator() (const IntType& ... indices) const - .. rubric:: Data Layout, Dimensions, Strides + :return: a value of ``reference_type`` which may or not be reference itself. The number of index arguments must match the ``rank`` of the view. See notes on ``reference_type`` for properties of the return type. - .. cpp:function:: constexpr array_layout layout() const + .. code-block:: cpp + + reference_type access (const IntType& i0=0, ... , const IntType& i6=0) const + + \ + :return: a value of ``reference_type`` which may or not be reference itself. The number of index arguments must be equal or larger than the ``rank`` of the view. Index arguments beyond ``rank`` must be ``0`` , which will be enforced if ``KOKKOS_DEBUG`` is defined. See notes on ``reference_type`` for properties of the return type. - :return: the layout object. Can be used to to construct other views with the same dimensions. + .. rubric:: Data Layout, Dimensions, Strides - .. cpp:function:: template constexpr size_t extent( const iType& dim) const + .. cppkokkos:function:: constexpr array_layout layout() const - :return: the extent of the specified dimension. :any:`iType` must be an integral type, and :any:`dim` must be smaller than :any:`rank`. + :return: the layout object. Can be used to to construct other views with the same dimensions. - .. cpp:function:: template constexpr int extent_int( const iType& dim) const + .. cppkokkos:function:: template constexpr size_t extent( const iType& dim) const - :return: the extent of the specified dimension as an :any:`int`. :any:`iType` must be an integral type, and :any:`dim` must be smaller than :any:`rank`. Compared to :any:`extent` this function can be useful on architectures where :any:`int` operations are more efficient than :any:`size_t`. It also may eliminate the need for type casts in applications which otherwise perform all index operations with :any:`int`. + :return: the extent of the specified dimension. ``iType`` must be an integral type, and ``dim`` must be smaller than ``rank``. - .. cpp:function:: template constexpr size_t stride(const iType& dim) const + .. cppkokkos:function:: template constexpr int extent_int( const iType& dim) const - :return: the stride of the specified dimension. :any:`iType` must be an integral type, and :any:`dim` must be smaller than :any:`rank`. Example: :cpp:`a.stride(3) == (&a(i0,i1,i2,i3+1,i4)-&a(i0,i1,i2,i3,i4))` + :return: the extent of the specified dimension as an ``int``. ``iType`` must be an integral type, and ``dim`` must be smaller than ``rank``. Compared to ``extent`` this function can be useful on architectures where ``int`` operations are more efficient than ``size_t``. It also may eliminate the need for type casts in applications which otherwise perform all index operations with ``int``. - .. cpp:function:: constexpr size_t stride_0() const + .. cppkokkos:function:: template constexpr size_t stride(const iType& dim) const - :return: the stride of dimension 0. + :return: the stride of the specified dimension. ``iType`` must be an integral type, and ``dim`` must be smaller than ``rank``. Example: ``a.stride(3) == (&a(i0,i1,i2,i3+1,i4)-&a(i0,i1,i2,i3,i4))`` - .. cpp:function:: constexpr size_t stride_1() const + .. cppkokkos:function:: constexpr size_t stride_0() const - :return: the stride of dimension 1. + :return: the stride of dimension 0. - .. cpp:function:: constexpr size_t stride_2() const + .. cppkokkos:function:: constexpr size_t stride_1() const - :return: the stride of dimension 2. + :return: the stride of dimension 1. - .. cpp:function:: constexpr size_t stride_3() const + .. cppkokkos:function:: constexpr size_t stride_2() const - :return: the stride of dimension 3. + :return: the stride of dimension 2. - .. cpp:function:: constexpr size_t stride_4() const + .. cppkokkos:function:: constexpr size_t stride_3() const - :return: the stride of dimension 4. + :return: the stride of dimension 3. - .. cpp:function:: constexpr size_t stride_5() const + .. cppkokkos:function:: constexpr size_t stride_4() const - :return: the stride of dimension 5. + :return: the stride of dimension 4. - .. cpp:function:: constexpr size_t stride_6() const + .. cppkokkos:function:: constexpr size_t stride_5() const - :return: the stride of dimension 6. + :return: the stride of dimension 5. - .. cpp:function:: constexpr size_t stride_7() const + .. cppkokkos:function:: constexpr size_t stride_6() const - :return: the stride of dimension 7. + :return: the stride of dimension 6. - .. cpp:function:: constexpr size_t span() const + .. cppkokkos:function:: constexpr size_t stride_7() const - :return: the memory span in elements between the element with the lowest and the highest address. This can be larger than the product of extents due to padding, and or non-contiguous data layout as for example :cpp:`LayoutStride` allows. + :return: the stride of dimension 7. - .. cpp:function:: constexpr pointer_type data() const + .. cppkokkos:function:: constexpr size_t span() const - :return: the pointer to the underlying data allocation. + :return: the memory span in elements between the element with the lowest and the highest address. This can be larger than the product of extents due to padding, and or non-contiguous data layout as for example ``LayoutStride`` allows. - .. cpp:function:: bool span_is_contiguous() const + .. cppkokkos:function:: constexpr pointer_type data() const - :return: whether the span is contiguous (i.e. whether every memory location between in span belongs to the index space covered by the view). + :return: the pointer to the underlying data allocation. - .. cpp:function:: static constexpr size_t required_allocation_size(size_t N0 = 0, ..., size_t N8 = 0) + .. cppkokkos:function:: bool span_is_contiguous() const - :return: the number of bytes necessary for an unmanaged view of the provided dimensions. This function is only valid if :cpp:`array_layout::is_regular == true`. + :return: whether the span is contiguous (i.e. whether every memory location between in span belongs to the index space covered by the view). - .. cpp:function:: static constexpr size_t required_allocation_size(const array_layout& layout) + .. code-block:: cpp + + static constexpr size_t required_allocation_size(size_t N0 = 0, ..., size_t N8 = 0) + + \ + :return: the number of bytes necessary for an unmanaged view of the provided dimensions. This function is only valid if ``array_layout::is_regular == true``. - :return: the number of bytes necessary for an unmanaged view of the provided layout. + .. cppkokkos:function:: static constexpr size_t required_allocation_size(const array_layout& layout) - .. rubric:: Other + :return: the number of bytes necessary for an unmanaged view of the provided layout. - .. cpp:function:: int use_count() const + .. rubric:: Other - :return: the current reference count of the underlying allocation. + .. cppkokkos:function:: int use_count() const - .. cpp:function:: const char* label() const; + :return: the current reference count of the underlying allocation. - :return: the label of the :any:`DynRankView`. + .. cppkokkos:function:: const char* label() const; - .. cpp:function:: constexpr unsigned rank() const + :return: the label of the ``DynRankView``. - :return: the dynamic rank of the :any:`DynRankView` + .. cppkokkos:function:: constexpr unsigned rank() const - .. cpp:function:: constexpr bool is_allocated() const + :return: the dynamic rank of the ``DynRankView`` - :return: true if the view points to a valid memory location. This function works for both managed and unmanaged views. With the unmanaged view, there is no guarantee that referenced address is valid, only that it is a non-null pointer. + .. cppkokkos:function:: constexpr bool is_allocated() const + :return: true if the view points to a valid memory location. This function works for both managed and unmanaged views. With the unmanaged view, there is no guarantee that referenced address is valid, only that it is a non-null pointer. Assignment Rules ---------------- -Assignment rules cover the assignment operator as well as copy constructors. We aim at making all logically legal assignments possible, -while intercepting illegal assignments if possible at compile time, otherwise at runtime. -In the following, we use :cpp:`DstType` and :cpp:`SrcType` as the type of the destination view and source view respectively. -:cpp:`dst_view` and :cpp:`src_view` refer to the runtime instances of the destination and source views, i.e.: +Assignment rules cover the assignment operator as well as copy constructors. We aim at making all logically legal assignments possible, while intercepting illegal assignments if possible at compile time, otherwise at runtime. In the following, we use ``DstType`` and ``SrcType`` as the type of the destination view and source view respectively. ``dst_view`` and ``src_view`` refer to the runtime instances of the destination and source views, i.e.: .. code-block:: cpp - ScrType src_view(...); - DstType dst_view(src_view); - dst_view = src_view; + ScrType src_view(...); + DstType dst_view(src_view); + dst_view = src_view; The following conditions must be met at and are evaluated at compile time: -* :cpp:`DstType::rank == SrcType::rank` -* :cpp:`DstType::non_const_value_type` is the same as :cpp:`SrcType::non_const_value_type` -* If :cpp:`std::is_const::value == true` than :cpp:`std::is_const::value == true`. -* :cpp:`MemorySpaceAccess::assignable == true` +* ``DstType::rank == SrcType::rank`` +* ``DstType::non_const_value_type`` is the same as ``SrcType::non_const_value_type`` +* If ``std::is_const::value == true`` than ``std::is_const::value == true``. +* ``MemorySpaceAccess::assignable == true`` -Furthermore there are rules which must be met if :cpp:`DstType::array_layout` is not the same as :cpp:`SrcType::array_layout`. -These rules only cover cases where both layouts are one of :cpp:`LayoutLeft` , :cpp:`LayoutRight` or :cpp:`LayoutStride` +Furthermore there are rules which must be met if ``DstType::array_layout`` is not the same as ``SrcType::array_layout``. These rules only cover cases where both layouts are one of ``LayoutLeft`` , ``LayoutRight`` or ``LayoutStride`` -* If neither :cpp:`DstType::array_layout` nor :cpp:`SrcType::array_layout` is :cpp:`LayoutStride` : +* If neither ``DstType::array_layout`` nor ``SrcType::array_layout`` is ``LayoutStride``: + - If ``DstType::rank > 1`` than ``DstType::array_layout`` must be the same as ``SrcType::array_layout``. - * If :cpp:`DstType::rank > 1` than :cpp:`DstType::array_layout` must be the same as :cpp:`SrcType::array_layout`. - -* If either :cpp:`DstType::array_layout` or :cpp:`SrcType::array_layout` is :cpp:`LayoutStride` - - * For each dimension :cpp:`k` it must hold that :cpp:`dst_view.extent(k) == src_view.extent(k)` +* If either ``DstType::array_layout`` or ``SrcType::array_layout`` is ``LayoutStride`` + - For each dimension ``k`` it must hold that ``dst_view.extent(k) == src_view.extent(k)`` Examples -------- .. code-block:: cpp - #include - #include + #include + #include - int main(int argc, char* argv[]) { - Kokkos::initialize(argc,argv); + int main(int argc, char* argv[]) { + Kokkos::initialize(argc,argv); - int N0 = atoi(argv[1]); - int N1 = atoi(argv[2]); + int N0 = atoi(argv[1]); + int N1 = atoi(argv[2]); - Kokkos::DynRankView a("A",N0); - Kokkos::DynRankView b("B",N1); + Kokkos::DynRankView a("A",N0); + Kokkos::DynRankView b("B",N1); - Kokkos::parallel_for("InitA", N0, KOKKOS_LAMBDA (const int& i) { - a(i) = i; - }); - - Kokkos::parallel_for("InitB", N1, KOKKOS_LAMBDA (const int& i) { - b(i) = i; - }); + Kokkos::parallel_for("InitA", N0, KOKKOS_LAMBDA (const int& i) { + a(i) = i; + }); - Kokkos::DynRankView c("C",N0,N1); - { - Kokkos::DynRankView const_a(a); - Kokkos::DynRankView const_b(b); - Kokkos::parallel_for("SetC", Kokkos::MDRangePolicy>({0,0},{N0,N1}), - KOKKOS_LAMBDA (const int& i0, const int& i1) { - c(i0,i1) = a(i0) * b(i1); + Kokkos::parallel_for("InitB", N1, KOKKOS_LAMBDA (const int& i) { + b(i) = i; }); - } - Kokkos::finalize(); - } + Kokkos::DynRankView c("C",N0,N1); + { + Kokkos::DynRankView const_a(a); + Kokkos::DynRankView const_b(b); + Kokkos::parallel_for("SetC", Kokkos::MDRangePolicy>({0,0},{N0,N1}), + KOKKOS_LAMBDA (const int& i0, const int& i1) { + c(i0,i1) = a(i0) * b(i1); + }); + } + + Kokkos::finalize(); + }