Merge pull request #437 from AerialMantis/SYCL-2020/multi-ptr-fixes

Add minor fixes to accessor/multi_ptr wording.

Some minor issues were raised in #432 after the PR was merged, so this is a follow-up PR to address those.

This PR adds a restriction for accessor::get_multi_ptr that it's only available when AccessTarget is target::device as it can't be used in a host task.

It adds the value_type alias to the decorated::legacy specialization of multi_ptr and adds the get_raw and get_decorated member functions to the void/decorated::legacy specializations of multi_ptr.

It also changes the alias used in multi_ptr::get_raw in the decorated::legacy specialization to ElementType as value_type is not defined.

adoc/chapters/programming_interface.adoc

@@ -6996,10 +6996,12 @@ a@
 template <access::decorated IsDecorated>
 accessor_ptr<IsDecorated> get_multi_ptr() const noexcept
 ----
-   a@ Returns a [code]#multi_ptr# to the start of this accessor's underlying
-      buffer, even if this is a <<ranged-accessor>> whose range does not start
-      at the beginning of the buffer.  The return value is unspecified if the
-      accessor is empty.
+   a@ Available only when [code]#(AccessTarget == target::device)#.
+
+Returns a [code]#multi_ptr# to the start of this accessor's underlying buffer,
+even if this is a <<ranged-accessor>> whose range does not start at the
+beginning of the buffer.  The return value is unspecified if the accessor is
+empty.
 
 This function may only be called from within a <<command>>.
 

adoc/headers/accessorBuffer.h

@@ -188,9 +188,10 @@ class accessor {
   Available only when: (AccessTarget == target::device) */
   global_ptr<DataT> get_pointer() const noexcept;
 
-  /* Available only when (AccessTarget == target::host_task) */
+  /* Available only when: (AccessTarget == target::host_task) */
   std::add_pointer_t<value_type> get_pointer() const noexcept;
 
+  /* Available only when: (AccessTarget == target::device) */
   template <access::decorated IsDecorated>
   accessor_ptr<IsDecorated> get_multi_ptr() const noexcept;
 

adoc/headers/multipointerlegacy.h

@@ -8,6 +8,7 @@ namespace sycl {
 template <typename ElementType, access::address_space Space>
 class [[deprecated]] multi_ptr<ElementType, Space, access::decorated::legacy> {
  public:
+  using value_type = ElementType;
   using element_type = ElementType;
   using difference_type = std::ptrdiff_t;
 
@@ -167,6 +168,7 @@ class [[deprecated]] multi_ptr<ElementType, Space, access::decorated::legacy> {
 template <access::address_space Space>
 class [[deprecated]] multi_ptr<VoidType, Space, access::decorated::legacy> {
  public:
+  using value_type = VoidType;
   using element_type = VoidType;
   using difference_type = std::ptrdiff_t;
 
@@ -224,6 +226,10 @@ class [[deprecated]] multi_ptr<VoidType, Space, access::decorated::legacy> {
   // Returns the underlying OpenCL C pointer
   pointer_t get() const;
 
+  std::add_pointer_t<value_type> get_raw() const;
+
+  pointer_t get_decorated() const;
+
   // Implicit conversion to the underlying pointer type
   operator VoidType*() const;