diff --git a/docs/source/API/core/view/realloc.md b/docs/source/API/core/view/realloc.md index c16899849..8d421ec24 100644 --- a/docs/source/API/core/view/realloc.md +++ b/docs/source/API/core/view/realloc.md @@ -9,6 +9,7 @@ Usage: ``` Reallocates a view to have the new dimensions. Can grow or shrink, and will not preserve content. +May not modify the view, if sizes already match. ## Synopsis @@ -77,6 +78,7 @@ void realloc(const Impl::ViewCtorProp& arg_prop, const size_t n7 = KOKKOS_IMPL_CTOR_DEFAULT_ARG); ``` Resizes `v` to have the new dimensions without preserving its contents. + May not modify `v` if the dimensions already match. * `v`: existing view, can be a default constructed one. * `n[X]`: new length for extent X. @@ -96,6 +98,7 @@ void realloc(const Impl::ViewCtorProp& arg_prop, const size_t n7 = KOKKOS_IMPL_CTOR_DEFAULT_ARG); ``` Resizes `v` to have the new dimensions without preserving its contents. The new `Kokkos::View` is constructed using the View constructor property `arg_prop`, e.g., Kokkos::WithoutInitializing. + May not modify `v` if the dimensions already match. * `v`: existing view, can be a default constructed one. * `n[X]`: new length for extent X. * `arg_prop`: View constructor property, e.g., `Kokkos::WithoutInitializing`. @@ -117,6 +120,7 @@ void realloc(const Impl::ViewCtorProp& arg_prop, const size_t n7 = KOKKOS_IMPL_CTOR_DEFAULT_ARG); ``` Resizes `v` to have the new dimensions without preserving its contents. The new `Kokkos::View` is constructed using the View constructor properties `arg_prop`, e.g., `Kokkos::view_alloc(Kokkos::WithoutInitializing)`. + May not modify `v` if the dimensions already match. * `v`: existing view, can be a default constructed one. * `n[X]`: new length for extent X. * `arg_prop`: View constructor properties, e.g., `Kokkos::view_alloc(Kokkos::WithoutInitializing)`. @@ -131,6 +135,7 @@ void realloc(const Impl::ViewCtorProp& arg_prop, const typename Kokkos::View::array_layout& layout); ``` Resizes `v` to have the new dimensions without preserving its contents. + May not modify `v` if the dimensions already match. * `v`: existing view, can be a default constructed one. * `layout`: a layout instance containing the new dimensions. @@ -140,6 +145,7 @@ void realloc(const Impl::ViewCtorProp& arg_prop, const typename Kokkos::View::array_layout& layout); ``` Resizes `v` to have the new dimensions without preserving its contents. The new `Kokkos::View` is constructed using the View constructor property `arg_prop`, e.g., Kokkos::WithoutInitializing. + May not modify `v` if the dimensions already match. * `v`: existing view, can be a default constructed one. * `layout`: a layout instance containing the new dimensions. * `arg_prop`: View constructor property, e.g., `Kokkos::WithoutInitializing`. @@ -151,6 +157,7 @@ void realloc(const Impl::ViewCtorProp& arg_prop, const typename Kokkos::View::array_layout& layout); ``` Resizes `v` to have the new dimensions without preserving its contents. The new `Kokkos::View` is constructed using the View constructor properties `arg_prop`, e.g., `Kokkos::view_alloc(Kokkos::WithoutInitializing)`. + May not modify `v` if the dimensions already match. * `v`: existing view, can be a default constructed one. * `layout`: a layout instance containing the new dimensions. * `arg_prop`: View constructor properties, e.g., `Kokkos::view_alloc(Kokkos::WithoutInitializing)`. @@ -158,6 +165,15 @@ void realloc(const Impl::ViewCtorProp& arg_prop, Restrictions: * `arg_prop` must not include a pointer to memory, a label, or a memory space. +## Possibly Unexpected Behavior Warning + +`realloc` will only modify the specific `View` instance passed to it. +Any other `View` which aliases the same allocation will be unmodified. +Consequently, if the `use_count()` of the `View` is larger than 1, the +old allocation will not be deleted. +Note that if the size arguments already match the extents of the `View` +argument, that `realloc` may not create a new `View`. + ## Example: * ```c++ Kokkos::realloc(v, 2, 3); diff --git a/docs/source/API/core/view/resize.md b/docs/source/API/core/view/resize.md index e667e8f5f..4cb55acb8 100644 --- a/docs/source/API/core/view/resize.md +++ b/docs/source/API/core/view/resize.md @@ -9,6 +9,7 @@ resize(view,layout); ``` Reallocates a view to have the new dimensions. Can grow or shrink, and will preserve content of the common subextents. +May not modify the view, if sizes already match. ## Synopsis @@ -76,6 +77,7 @@ void resize(const Impl::ViewCtorProp& arg_prop, const size_t n7 = KOKKOS_IMPL_CTOR_DEFAULT_ARG); ``` Resizes `v` to have the new dimensions while preserving the contents for the common subview of the old and new view. + May not modify the view, if sizes already match. * `v`: existing view, can be a default constructed one. * `n[X]`: new length for extent X. @@ -95,6 +97,7 @@ void resize(const Impl::ViewCtorProp& arg_prop, const size_t n7 = KOKKOS_IMPL_CTOR_DEFAULT_ARG); ``` Resizes `v` to have the new dimensions while preserving the contents for the common subview of the old and new view. The new `Kokkos::View` is constructed using the View constructor property `arg_prop`, e.g., Kokkos::WithoutInitializing. + May not modify the view, if sizes already match. * `v`: existing view, can be a default constructed one. * `n[X]`: new length for extent X. * `arg_prop`: View constructor property, e.g., `Kokkos::WithoutInitializing`. @@ -116,6 +119,7 @@ void resize(const Impl::ViewCtorProp& arg_prop, const size_t n7 = KOKKOS_IMPL_CTOR_DEFAULT_ARG); ``` Resizes `v` to have the new dimensions while preserving the contents for the common subview of the old and new view. The new `Kokkos::View` is constructed using the View constructor properties `arg_prop`, e.g., `Kokkos::view_alloc(Kokkos::WithoutInitializing)`. If `arg_prop` includes an execution space, it is used for allocating memory and for copying elements without using a final fence. + May not modify the view, if sizes already match. * `v`: existing view, can be a default constructed one. * `n[X]`: new length for extent X. * `arg_prop`: View constructor properties, e.g., `Kokkos::view_alloc(Kokkos::WithoutInitializing)`. @@ -130,6 +134,7 @@ void resize(const Impl::ViewCtorProp& arg_prop, const typename Kokkos::View::array_layout& layout); ``` Resizes `v` to have the new dimensions while preserving the contents for the common subview of the old and new view. + May not modify the view, if sizes already match. * `v`: existing view, can be a default constructed one. * `layout`: a layout instance containing the new dimensions. @@ -139,6 +144,7 @@ void resize(const Impl::ViewCtorProp& arg_prop, const typename Kokkos::View::array_layout& layout); ``` Resizes `v` to have the new dimensions while preserving the contents for the common subview of the old and new view. The new `Kokkos::View` is constructed using the View constructor property `arg_prop`, e.g., Kokkos::WithoutInitializing. + May not modify the view, if sizes already match. * `v`: existing view, can be a default constructed one. * `layout`: a layout instance containing the new dimensions. * `arg_prop`: View constructor property, e.g., `Kokkos::WithoutInitializing`. @@ -150,6 +156,7 @@ void resize(const Impl::ViewCtorProp& arg_prop, const typename Kokkos::View::array_layout& layout); ``` Resizes `v` to have the new dimensions while preserving the contents for the common subview of the old and new view. The new `Kokkos::View` is constructed using the View constructor properties `arg_prop`, e.g., `Kokkos::view_alloc(Kokkos::WithoutInitializing)`. If `arg_prop` includes an execution space, it is used for allocating memory and for copying elements without using a final fence. + May not modify the view, if sizes already match. * `v`: existing view, can be a default constructed one. * `layout`: a layout instance containing the new dimensions. * `arg_prop`: View constructor properties, e.g., `Kokkos::view_alloc(Kokkos::WithoutInitializing)`. @@ -157,6 +164,15 @@ void resize(const Impl::ViewCtorProp& arg_prop, Restrictions: * `arg_prop` must not include a pointer to memory, a label, or a memory space. +## Possibly Unexpected Behavior Warning + +`resize` will only modify the specific `View` instance passed to it. +Any other `View` which aliases the same allocation will be unmodified. +Consequently, if the `use_count()` of the `View` is larger than 1, the +old allocation will not be deleted. +Note that if the size arguments already match the extents of the `View` +argument, that `resize` may not create a new `View`. + ## Example: * ```c++ Kokkos::resize(v, 2, 3);