Clarified the condition of buffer write back.

[bso-intel]

The current spec is ambiguous about when the data is written back to the original vector/array.
In section 4.7.2.3, the rule #4 says "A buffer can be constructed from a pair of iterator values. In this case, ..... The destructor will not copy back any data and does not need to block"

This patch clarifies the condition when data is written back for the buffer constructor with a pair of iterators.

Signed-off-by: Byoungro So byoungro.so@intel.com

[CLAassistant]

All committers have signed the CLA.

[keryell]

Thanks for the clarification.

[bso-intel]

@AerialMantis Could you review this PR? Thanks.

[bso-intel]

@AerialMantis Please review this PR. Thanks.

[AerialMantis]

This suggests that the data is copied back to the original iterator set if a new destination is set via set_final_data, should this be is not called?

[bso-intel]

@AerialMantis
By default, the buffer created from a pair of iterators will not write back to the host memory.
Only when the user calls set_finaL_data(), the buffer is written back to host.
Here is the full sentence after my patch.

Data is written back to the same iterator set if the iterator is not a const iterator and the member function set_final_data() is called with a valid non-null pointer.

[keryell]

It depends on the level of detail in the wording document...
Technically

set_final_data(valid);
set_final_data(nullptr);

cannot trigger the copy back even if set_final_data() is called with a valid non-null pointer... :-)

So perhaps it has to be clarified in term of whether the final data it set to something or not instead of detailing calls to set_final_data()`...

[bso-intel]

@keryell
Yes, there could be two calls to set_final_data(), first call with a valid pointer and then later change it to nullptr.
In fact, most of buffer constructors in Table 4.31 already mentioned the condition of write-back as follows:

Unless the member function set_final_data() is called with a valid non-null pointer there will be no write back on destruction.

However, the spec of set_final_data() in Table 4.32 is clear enough to clarify your case.

If Destination is std::nullptr_t, then the copy back will not happen.

[AerialMantis]

By default, the buffer created from a pair of iterators will not write back to the host memory.

Thanks for the clarification, though this wording doesn't seem quite right to me. It also suggests that the data is copied back to the original iterator the buffer is constructed with only if you specify a new final data iterator. So I would interpret this as:

{
  buffer b(begin(dataA), end(dataA);
  b.set_final_data(begin(dataB));
  /* do something with b */
} // copies back to dataA on destruction

The original wording also suggests that data will be copied back if the iterator set is non-const. So if we want the iterators to be treated as input iterators and not copy back by default, then we should also clarify this such that it's never copied back, unless set_final_data is called with a valid destination.

I agree with Ronan, we should have the wording reflect the state of the buffer rather than a specific call to set_final_data.

I would alter the wording to something like:

Data is not written back to the iterator set provided. 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.

[bso-intel]

@AerialMantis
Thanks. I will try to use your wording for this buffer constructor and other buffer constructors.

[bso-intel]

@AerialMantis @keryell
I fixed wording as you requested.

[AerialMantis]

Looks good thanks 👍

[keryell]

That looks even better. Thanks!