KhronosGroup / KhronosGroup/SYCL-Docs

Clarifications for "sycl::exception_list"

Open
#167 5 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

This issue captures a number of problems with the definition of `sycl::exception_list`.

* We do not specify the kind of iterator for `exception_list::iterator`. Assuming we want to follow the exception list in the [C++ draft parallelism specification](https://isocpp.org/files/papers/N4352.html#parallel.exceptions.synopsis), we should define it to be `LegacyForwardIterator`. If we want `exception_list` to be a read-only container, then we should further clarify that the `iterator` type is a "LegacyForwardIterator to const value_type".

* It's unclear (to me) whether the spec requires an implementation to have a default constructor, a copy constructor / operator, or a move constructor / operator. Rather than relying on C++ rules for implicitly declared constructors / operators, I think we should explicitly list these in the synopsis and describe them.

Here is a proposed synopsis which addresses these issues:

```
class exception_list {
public:
using value_type = std::exception_ptr;
using reference = value_type&;
using const_reference = const value_type&;
using size_type = std::size_t;
using iterator = /* LegacyForwardIterator to const value_type */;
using const_iterator = /* LegacyForwardIterator to const value_type */;

exception_list();
exception_list(const exception_list &other);
exception_list(exception_list &&other);
~exception_list();

exception_list &operator=(const exception_list &other);
exception_list &operator=(exception_list &&other) noexcept;

size_type size() const;
iterator begin() const;
iterator end() const;
};
```

Note that I retain the class types `const_iterator`, `reference`, and `const_reference` mostly for compatibility with SYCL 1.2.1, which defined these types. Nothing in the API actually uses them.

Possibly, we do not want to support a default constructor since the SYCL runtime always creates `exception_list` objects. In that case, we should show the default constructor as deleted in the synopsis (or maybe just omit it).

Alternatively, we might decide that `exception_list` should meet all the requirements of `Container`. In order to do this, we would need to define additional types and member functions.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the specification definition of sycl::exception_list and the linked C++ draft parallelism specification. Resolve the iterator, special member, and container-requirement alternatives, then update the synopsis and requirements so the supported interface is unambiguous.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.