Views

View

Kokkos.Views.View — Type

View{T, D, Layout, MemSpace} <: AbstractArray{T, D}

Wrapper around a Kokkos::View of D dimensions of type T, stored in MemSpace using the Layout.

Behaves like a normal Array. Indexing is done by calling the Kokkos::View::operator() function of the view, and is therefore not highly performant. The best performance with Kokkos views is achieved by calling Kokkos kernels compiled from C++.

It is supposed that all view accesses are done from the default host execution space. Since the view may be stored in a memory space different from the host, it may be invalid to access its elements: if accessible(MemSpace) is false, then all view accesses will throw an error.

Views are created through CxxWrap.jl, which adds automatically a finalizer to all objects which calls the view's destructor when the Julia object is deleted by the garbage collector.

It is important to understand that for a view to be properly disposed of, there is two requirements:

the library containing its destructor is still loaded. Views created by the Kokkos.jl library will always meet this requirement.
finalize wasn't called.

Kokkos.accessible — Method

accessible(::View)
accessible(::Type{<:View})

Return true if the view is accessible from the default host execution space.

Kokkos.memory_space — Method

memory_space(::View)
memory_space(::Type{<:View})

The memory space type in which the view data is stored.

julia> my_cuda_space = Kokkos.CudaSpace()
 ...

julia> v = View{Float64}(undef, 10; mem_space=my_cuda_space)
 ...

julia> memory_space(v)
Kokkos.CudaSpace

Kokkos.array_layout — Method

array_layout(::View)
array_layout(::Type{<:View})

Return the Layout type of the view.

Kokkos.Views.label — Function

label(::View)

Return the label of the View.

This function relies on Dynamic Compilation.

Kokkos.Views.view_data — Function

view_data(::View)

The pointer to the data of the View. Using Base.pointer(view) is preferred over this method.

Equivalent to view.data().

This function relies on Dynamic Compilation.

Kokkos.Views.memory_span — Function

memory_span(::View)

Total size of the view data in memory, in bytes.

Equivalent to view.impl_map().memory_span().

This function relies on Dynamic Compilation.

Kokkos.Views.span_is_contiguous — Function

span_is_contiguous(::View)

true if the view stores all its elements contiguously in memory.

Equivalent to view.span_is_contiguous().

This function relies on Dynamic Compilation.

Kokkos.Views.subview — Function

subview(v::View, indexes...)
subview(v::View, indexes::Tuple{Vararg{Union{Int, Colon, AbstractUnitRange}}})

Return a new Kokkos.view which will be a subview into the region specified by indexes of v, with the same memory space (but maybe not the same layout).

Unspecified dimensions are completed by :, e.g. if v is a 3D view (1,) and (1, :, :) will return the same subview.

If v is tracked to be automatically finalized, then the subview will be as well.

Equivalent to Kokkos::subview.

Kokkos::ALL is equivalent to :.

Example

julia> v = Kokkos.View{Float64}(undef, 4, 4);

julia> v[:] .= collect(1:length(v));

julia> v
4×4 Kokkos.Views.View{Float64, 2, Kokkos.LayoutRight, Kokkos.HostSpace}:
 1.0  5.0   9.0  13.0
 2.0  6.0  10.0  14.0
 3.0  7.0  11.0  15.0
 4.0  8.0  12.0  16.0

julia> Kokkos.subview(v, (2:3, 2:3))
2×2 Kokkos.Views.View{Float64, 2, Kokkos.LayoutRight, Kokkos.HostSpace}:
 6.0  10.0
 7.0  11.0

julia> Kokkos.subview(v, (:, 1))  # The subview may change its layout to `LayoutStride` 
4-element Kokkos.Views.View{Float64, 1, Kokkos.LayoutStride, Kokkos.HostSpace}:
 1.0
 2.0
 3.0
 4.0

julia> Kokkos.subview(v, (1,))  # Equivalent to `(1, :)`
4-element Kokkos.Views.View{Float64, 1, Kokkos.LayoutRight, Kokkos.HostSpace}:
  1.0
  5.0
  9.0
 13.0

Warning

Kokkos.subview is not equivalent to Base.view, as it returns a new Kokkos.View object, while Base.view returns a SubArray, which cannot be passed to a ccall.

This function relies on Dynamic Compilation.

Kokkos.Views.view_wrap — Function

view_wrap(array::AbstractArray{T, D})
view_wrap(array::DenseArray{T, D})
view_wrap(array::SubArray{T, D})
view_wrap(::Type{View{T, D, L, S}}, d::NTuple{D, Int}, p::Ptr{T}; layout = nothing)

Construct a new View from the data of a Julia-allocated array (or from any valid array or pointer). The returned view does not own the data: no copy is made.

The memory space S is HostSpace when array is a DenseArray or AbstractArray, and the layout L is LayoutLeft for DenseArray and LayoutStride for AbstractArray.

If L is LayoutStride, then the kwarg layout should be an instance of a LayoutStride which specifies the stride of each dimension.

Warning

Julia arrays have a column-major layout by default. This correspond to a LayoutLeft, while Kokkos prefers LayoutRight for CPU allocated arrays. If strides(array) ≠ strides(view_wrap(array)) then it might lead to segfaults. This only concerns 2D arrays and above.

Warning

The returned view does not hold a reference to the original array. It is the responsibility of the user to make sure the original array is kept alive as long as the view should be accessed.

Note

Overloads for CuArrays of CUDA.jl as well as for CUDA.StridedSubCuArray (using a LayoutStride), and ROCArrays of AMDGPU.jl are also available.

This function relies on Dynamic Compilation.

Kokkos.Views.deep_copy — Function

deep_copy(dest::View, src::View)
deep_copy(space::ExecutionSpace, dest::View, src::View)

Performs a copy of all data from src to dest.

In order for the copy to be possible, both views must have the same dimension, and either have the same layout or are both accessible from space.

If a space is given, the copy may be asynchronous. If not the copy will be synchronous.

Equivalent to Kokkos::deep_copy(dest, src) or Kokkos::deep_copy(space, dest, src). See the Kokkos docs about Kokkos::deep_copy

This function relies on Dynamic Compilation.

Kokkos.Views.host_mirror — Function

host_mirror(view_t::Type{<:View})
host_mirror(view::View)

The view type which mirrors the given view on host space.

Not rigorously equivalent to Kokkos::View<...>::HostMirror, since view hooks are not supported, but apart from this, it should be exactly equivalent.

Kokkos.Views.host_mirror_space — Function

host_mirror_space(view_t::Type{<:View})
host_mirror_space(view::View)

The type of the host execution space which mirrors this view's space.

Equivalent to Kokkos::View<...>::traits::host_mirror_space.

This function relies on Dynamic Compilation.

Kokkos.Views.create_mirror — Function

create_mirror(src::View; mem_space = nothing, zero_fill = false, track = true)

Create a new View in the same way as similar(src), with the same layout and padding as src.

If mem_space is nothing the new view will be in a memory space accessible by the host, otherwise it must be a memory space instance where the new view will be allocated.

If zero_fill is true, the new view will have all of its elements set to their default value.

See the Kokkos docs about Kokkos::create_mirror

This function relies on Dynamic Compilation.

Kokkos.Views.create_mirror_view — Function

create_mirror_view(src::View; mem_space = nothing, zero_fill = false, track = true)

Equivalent to create_mirror, but if src is already accessible by the host, src is returned and no view is created.

This function relies on Dynamic Compilation.

Kokkos.Views.impl_view_type — Function

impl_view_type(::Type{View{T, D, L, S}})

Returns the internal View type for the given complete View type.

The opposite of main_view_type.

julia> view_t = Kokkos.View{Float64, 2, Kokkos.LayoutRight, Kokkos.HostSpace}
Kokkos.Views.View{Float64, 2, Kokkos.Views.LayoutRight, Kokkos.HostSpace}

julia> view_impl_t = Kokkos.impl_view_type(view_t)
Kokkos.Wrapper.Impl.View2D_R_HostAllocated{Float64}

julia> supertype(supertype(view_impl_t))
Kokkos.Views.View{Float64, 2, Kokkos.Views.LayoutRight, Kokkos.Wrapper.Impl.HostSpaceImplAllocated}

julia> view_impl_t <: view_t  # Julia types are contra-variant
false

This function relies on Dynamic Compilation.

Kokkos.Views.main_view_type — Function

main_view_type(::View)
main_view_type(::Type{<:View})

The "main type" of the view: converts Type{View1D_S_HostAllocated{Float64}} into Type{View{Float64, 1, LayoutStride, HostSpace}}, which is easier to understand.

The opposite of impl_view_type.

Kokkos.Views.cxx_type_name — Function

cxx_type_name(::Type{<:View}, mangled::Bool = false)
cxx_type_name(::View, mangled::Bool = false)

Return as a String the name of the exact C++ type wrapped by the given view type.

If mangled is true, then the mangled type name is returned. This name is compiler-dependant.

julia> view_t = Kokkos.View{Float64, 2, Kokkos.LayoutRight, Kokkos.HostSpace}
Kokkos.Views.View{Float64, 2, Kokkos.Views.LayoutRight, Kokkos.HostSpace}

julia> Kokkos.Views.cxx_type_name(view_t)
"Kokkos::View<double**, Kokkos::LayoutRight, Kokkos::Device<Kokkos::OpenMP, Kokkos::HostSpace>, Kokkos::MemoryTraits<0> >"

julia> Kokkos.Views.cxx_type_name(view_t, true)
"N6Kokkos4ViewIPPdJNS_11LayoutRightENS_6DeviceINS_6OpenMPENS_9HostSpaceEEENS_12MemoryTraitsILj0EEEEEE"

This function relies on Dynamic Compilation.

Layouts

Kokkos.Layout — Type

Layout

Abstract super-type of all view layouts.

Sub-types:

LayoutLeft
LayoutRight
LayoutStride

Kokkos.LayoutLeft — Type

LayoutLeft

Fortran-style column major array layout. This is also the layout of Julia arrays.

While indexing, the first index is the contiguous one: v[i0, i1, i2].

Equivalent to Kokkos::LayoutLeft.

Kokkos.LayoutRight — Type

LayoutRight

C-style row major array layout.

While indexing, the last index is the contiguous one: v[i2, i1, i0].

Equivalent to Kokkos::LayoutRight.

Kokkos.LayoutStride — Type

LayoutStride

Arbitrary array layout, mostly used for sub-views.

Equivalent to Kokkos::LayoutStride.

When building a new view with a LayoutStride, the strides of each dimension must be given to the view constructor:

# A 7×11 matrix with column-major layout
v = Kokkos.View{Float64}(undef, 7, 11; layout=LayoutStride(1, 11))

# A 7×11 matrix with row-major layout
v = Kokkos.View{Float64}(undef, 7, 11; layout=LayoutStride(7, 1))

This differs slightly from the C++ Kokkos constructor, where dimensions and strides are interleaved.

Constants

Kokkos.Idx — Constant

Idx::Type{<:Integer}

Integer type used by views for indexing on the default execution space. Usually either Cint or Clonglong: a 32bit or 64bit signed integer.

Equivalent to Kokkos::RangePolicy<>::index_type.

nothing if Kokkos is not yet loaded.