Clarify that capture by ref host_task requires caution

[hdelan]

C++ lambdas if capturing by ref need to be aware of the lifetime of the referred-to objects. This adds this information here as well.

Motivation:

oneapi-src/oneDNN#1767

[gmlueck]

This seems too specific to a particular bug that you had, and the recommendation about reference counting is only one possible solution. I don't think we need to add any new formal requirements to the spec here. We already say that a host task's execution is deferred and that it executes asynchronously. A logical outcome of this is that you need to take care when using pointers or references inside the host task.

If we want to add something to the spec, I'd suggest a non-normative note like this:

[NOTE]
====
Care must be taken when using pointers or references inside a host task when the pointer
or reference refers to an object that is defined outside of the host task.  Because the host
task is executed asynchronously, applications should ensure that the referenced object's
lifetime lasts at least until the host task completes.
====

[psalz]

Is reference counting even a solution? This is still a bug:

void submit_host_task(sycl::queue& q, std::shared_ptr<int> /* by value */ something) {
  q.submit([&](sycl::handler& cgh) {
    cgh.host_task([&]() {
      printf("%d\n", *something); // oops, `something` went out of scope
    });
  });
}

A classic footgun is to capture host-task accessors by reference. Maybe it's worth pointing that out specifically.

[hdelan]

Thanks for comments. Have rephrased to advise caution

[keryell]

This seems like a normal caveat with any lambda not in an immediate invocation context.

[hdelan]

@keryell I agree. I think it is worth reiterating here, but can close this PR if you think it doesn't belong in the spec

[gmlueck]

Hi @hdelan, we have some new formatting requirements for the *.adoc files, and these are checked by our CI system. One of these checks failed for this PR. Can you do the following:

• Run: ./adoc/scripts/reflow.py -overwrite adoc/chapters/programming_interface.adoc
• This will make some formatting changes to "programming_interface.adoc". Check that nothing unexpected happened.
• Commit the new changes and push the commit to this PR.

Thanks.

[hdelan]

Hi @hdelan, we have some new formatting requirements for the *.adoc files, and these are checked by our CI system. One of these checks failed for this PR. Can you do the following:

* Run: `./adoc/scripts/reflow.py -overwrite adoc/chapters/programming_interface.adoc`

* This will make some formatting changes to "programming_interface.adoc".  Check that nothing unexpected happened.

* Commit the new changes and push the commit to this PR.

Thanks.

Thanks @gmlueck have done that

[hdelan]

@gmlueck should I add my name to acknowledgements.adoc?

[gmlueck]

@gmlueck should I add my name to acknowledgements.adoc?

Yes, if you like.

[hdelan]

@gmlueck thanks, done

[keryell]

Even for objects captured by copy you still need to unsure that it works under the hood with the program logic.
The trivial example is a std::ref or a pointer captured by copy. ;-)

[gmlueck]

WG approved