KhronosGroup / KhronosGroup/SYCL-Docs
Clarifications for "sycl::exception_list"
- 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