Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add documentation for realloc and resize possibly not modifying argument #235

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Add documentation for realloc and resize possibly not modifying argument #235

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions docs/source/API/core/view/realloc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe a native speaker can chime in but I feel like "may not" is unfortunate because it could be interpreted as "[presumably the implementation] is not allowed"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, that is a reasonable mis-interpretation. The intended meaning would be conveyed (with more explicit precision) by "Might not modify the view, if its extents match those requested"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@PhilMiller , @dalg24 - regarding line 12 above; why not be definitive, and say "if sizes already match, the View will not be modified." Here, "may" suggests other possible outcomes, and there are none, if the requested sizes are the same as the current sizes , correct?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is reaching back to very old discussion, but I believe the intention was to avoid committing the implementation to any particular outcome. Once it's documented to definitely do something, that's a nearly-eternal promise.


## Synopsis

Expand Down Expand Up @@ -77,6 +78,7 @@ void realloc(const Impl::ViewCtorProp<ViewCtorArgs...>& 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.

Expand All @@ -96,6 +98,7 @@ void realloc(const Impl::ViewCtorProp<ViewCtorArgs...>& 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`.
Expand All @@ -117,6 +120,7 @@ void realloc(const Impl::ViewCtorProp<ViewCtorArgs...>& 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)`.
Expand All @@ -131,6 +135,7 @@ void realloc(const Impl::ViewCtorProp<ViewCtorArgs...>& arg_prop,
const typename Kokkos::View<T, P...>::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.

Expand All @@ -140,6 +145,7 @@ void realloc(const Impl::ViewCtorProp<ViewCtorArgs...>& arg_prop,
const typename Kokkos::View<T, P...>::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`.
Expand All @@ -151,13 +157,23 @@ void realloc(const Impl::ViewCtorProp<ViewCtorArgs...>& arg_prop,
const typename Kokkos::View<T, P...>::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)`.

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`.
Comment on lines +168 to +175
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you consider having a code snippet to illustrate how this may have potentially surprising behavior?
Also should we spell out that it is best to think of if as what std::realloc is to raw pointers, that is the original view is "invalidated" and that keep using another object that aliases that same original view is a bad idea.


## Example:
* ```c++
Kokkos::realloc(v, 2, 3);
Expand Down
16 changes: 16 additions & 0 deletions docs/source/API/core/view/resize.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -76,6 +77,7 @@ void resize(const Impl::ViewCtorProp<ViewCtorArgs...>& 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.

Expand All @@ -95,6 +97,7 @@ void resize(const Impl::ViewCtorProp<ViewCtorArgs...>& 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`.
Expand All @@ -116,6 +119,7 @@ void resize(const Impl::ViewCtorProp<ViewCtorArgs...>& 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)`.
Expand All @@ -130,6 +134,7 @@ void resize(const Impl::ViewCtorProp<ViewCtorArgs...>& arg_prop,
const typename Kokkos::View<T, P...>::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.

Expand All @@ -139,6 +144,7 @@ void resize(const Impl::ViewCtorProp<ViewCtorArgs...>& arg_prop,
const typename Kokkos::View<T, P...>::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`.
Expand All @@ -150,13 +156,23 @@ void resize(const Impl::ViewCtorProp<ViewCtorArgs...>& arg_prop,
const typename Kokkos::View<T, P...>::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)`.

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);
Expand Down