KhronosGroup / KhronosGroup/SYCL-Docs
Description inconsistencies around `buffer` constructors and `buffer::set_final_data()`
- 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