From b1f4476d6ca5e896d1d05cc972c4f7b6268d6a3d Mon Sep 17 00:00:00 2001 From: RL-S Date: Tue, 11 Jun 2024 15:17:54 +0200 Subject: [PATCH 1/4] create_mirror and create_mirror_view: clarified difference Added a paragraph to "Usage", before the code example, and added comments to the code example. I was thinking about changing the variable names in the second half of the code example from `host_mirror_space*` to `space_mirror*`, as now they don't *have* to be in host space, if another space is provided. Though I'm not yet familiar enough with Kokkos to know whether `ExecName()` is pseudo code or evaluates to the default execution space or something like that. --- docs/source/API/core/view/create_mirror.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/source/API/core/view/create_mirror.rst b/docs/source/API/core/view/create_mirror.rst index 4c7eece9a..fe9d745ab 100644 --- a/docs/source/API/core/view/create_mirror.rst +++ b/docs/source/API/core/view/create_mirror.rst @@ -15,14 +15,22 @@ A common desired use case is to have a memory allocation in GPU memory and an id Usage ----- +The key difference between ``create_mirror`` and ``create_mirror_view`` is the following: ``create_mirror`` `always` allocates new memory in the specified space (shown below for host space), while ``create_mirror_view`` only allocates memory if the View to be mirrored (``a_view``) is not already accessible from the specified space, and otherwise simply returns ``a_view``. +Use ``create_mirror_view`` when you want to skip the memory allocation and copy within the same execution space, and use ``create_mirror`` if you need the data to be independent, e.g. for overlapping computation and I/O. + .. code-block:: cpp + // Both host_mirror and host_mirror_view have the correct properties for deepCopy from/to a_view + // host_mirror is guaranteed to have separately allocated memory from a_view auto host_mirror = create_mirror(a_view); + // host_mirror_view may point to the same memory as a_view, if a_view is host-accessible auto host_mirror_view = create_mirror_view(a_view); + // You can specify the execution space from which the mirror view must be accessible auto host_mirror_space = create_mirror(ExecSpace(),a_view); auto host_mirror_view_space = create_mirror_view(ExecSpace(),a_view); + Description ----------- From 76165ed11bf361fa272ee4ed443ca53237f45a99 Mon Sep 17 00:00:00 2001 From: RL-S Date: Tue, 11 Jun 2024 15:58:19 +0200 Subject: [PATCH 2/4] Update docs/source/API/core/view/create_mirror.rst Co-authored-by: Daniel Arndt --- docs/source/API/core/view/create_mirror.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/API/core/view/create_mirror.rst b/docs/source/API/core/view/create_mirror.rst index fe9d745ab..0d3ad1075 100644 --- a/docs/source/API/core/view/create_mirror.rst +++ b/docs/source/API/core/view/create_mirror.rst @@ -26,9 +26,9 @@ Use ``create_mirror_view`` when you want to skip the memory allocation and copy // host_mirror_view may point to the same memory as a_view, if a_view is host-accessible auto host_mirror_view = create_mirror_view(a_view); - // You can specify the execution space from which the mirror view must be accessible - auto host_mirror_space = create_mirror(ExecSpace(),a_view); - auto host_mirror_view_space = create_mirror_view(ExecSpace(),a_view); + // You can specify the space from which the mirror view must be accessible + auto mirror = create_mirror(memory_space_instance, a_view); + auto mirror_view = create_mirror_view(memory_space_instance, a_view); Description From a33567f0450202001ca136c00fce32498a9129ae Mon Sep 17 00:00:00 2001 From: Christian Trott Date: Tue, 18 Jun 2024 10:47:30 -0600 Subject: [PATCH 3/4] Apply suggestions from code review --- docs/source/API/core/view/create_mirror.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/API/core/view/create_mirror.rst b/docs/source/API/core/view/create_mirror.rst index 0d3ad1075..abbcb5fe3 100644 --- a/docs/source/API/core/view/create_mirror.rst +++ b/docs/source/API/core/view/create_mirror.rst @@ -16,11 +16,11 @@ Usage ----- The key difference between ``create_mirror`` and ``create_mirror_view`` is the following: ``create_mirror`` `always` allocates new memory in the specified space (shown below for host space), while ``create_mirror_view`` only allocates memory if the View to be mirrored (``a_view``) is not already accessible from the specified space, and otherwise simply returns ``a_view``. -Use ``create_mirror_view`` when you want to skip the memory allocation and copy within the same execution space, and use ``create_mirror`` if you need the data to be independent, e.g. for overlapping computation and I/O. +Use ``create_mirror_view`` when the mirror is solely used for providing access in different execution spaces, and use ``create_mirror`` if you need the data to be independent, e.g. for having an previous and a updated version of the data. .. code-block:: cpp - // Both host_mirror and host_mirror_view have the correct properties for deepCopy from/to a_view + // Both host_mirror and host_mirror_view have the correct properties for deep_copy from/to a_view // host_mirror is guaranteed to have separately allocated memory from a_view auto host_mirror = create_mirror(a_view); // host_mirror_view may point to the same memory as a_view, if a_view is host-accessible From 63aa8cdad9746bdcba29844c33b8eaf2065d94d1 Mon Sep 17 00:00:00 2001 From: Christian Trott Date: Tue, 18 Jun 2024 10:59:39 -0600 Subject: [PATCH 4/4] Update docs/source/API/core/view/create_mirror.rst Co-authored-by: Dong Hun Lee <59181952+ldh4@users.noreply.github.com> --- docs/source/API/core/view/create_mirror.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/API/core/view/create_mirror.rst b/docs/source/API/core/view/create_mirror.rst index abbcb5fe3..f46332434 100644 --- a/docs/source/API/core/view/create_mirror.rst +++ b/docs/source/API/core/view/create_mirror.rst @@ -16,7 +16,7 @@ Usage ----- The key difference between ``create_mirror`` and ``create_mirror_view`` is the following: ``create_mirror`` `always` allocates new memory in the specified space (shown below for host space), while ``create_mirror_view`` only allocates memory if the View to be mirrored (``a_view``) is not already accessible from the specified space, and otherwise simply returns ``a_view``. -Use ``create_mirror_view`` when the mirror is solely used for providing access in different execution spaces, and use ``create_mirror`` if you need the data to be independent, e.g. for having an previous and a updated version of the data. +Use ``create_mirror_view`` when the mirror is solely used for providing access in different execution spaces, and use ``create_mirror`` if you need the data to be independent, e.g. for having a previous and an updated version of the data. .. code-block:: cpp