KhronosGroup / KhronosGroup/SYCL-Docs

Description inconsistencies around `buffer` constructors and `buffer::set_final_data()`

Open
#535 2 comments 0 reactions 0 assignees View on GitHub
clarification
Dominant language
JavaScript
Stars
158
Forks
80
Avg merge
7d 6h
Merged PRs (30d)
5

Description

`buffer::set_final_data` is defined as follows (emphasis mine):

> `template void set_final_data(Destination finalData = nullptr)`
>
> The `finalData` points to where the outcome of all the buffer processing is going to be copied to at destruction time, if the buffer was involved with a write accessor.
>
> **Destination can be either an output iterator or a `std::weak_ptr`.**
>
> Note that a raw pointer is a special case of output iterator and thus defines the host memory to which the result is to be copied.
>
> In the case of a weak pointer, the output is not updated if the weak pointer has expired.
>
> If Destination is `std::nullptr_t`, then the copy back will not happen.

It is referenced from a number of constructors, but differently every time (emphasis mine):

> Data is not written back to the host on destruction of the buffer unless the buffer has a **valid non-null pointer** specified via the member function `set_final_data()`.

> Since the `hostData` is const, this buffer is only initialized with this memory and there is no write back after its destruction, unless the `buffer` has another **valid non-null final data address** specified via the member function `set_final_data()` after construction of the buffer.

> However, if the `buffer` has a **valid non-const iterator** specified via the member function `set_final_data()`, data will be copied back to that iterator.

I think it would be better if `set_final_data()` was referenced uniformly from all constructors. It also doesn't make sense to account for `const` iterators, because they are not output iterators and therefore can't be passed to `set_final_data()` at all.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start at the set_final_data() description and compare every buffer constructor reference quoted in the issue. Make the constructor wording consistent with the set_final_data() rules and remove the claim about const iterators, then review the affected documentation for consistent terminology.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.