conventions for `int` return values

Open
#2,276 0 comments 1 reaction 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
25/100
Issue type
Refactor
Clarity
Needs clarification
Activity status
Stale
Tech stack
cpp
Domain
testing-qa

Research direction

Start by examining the CTS test harness and the existing test_error and test_error_fail paths. Map where int returns represent OpenCL error codes versus test statuses, then compare the proposed conventions. Done means the project has selected and consistently applied one documented approach.

Written by the indexing model from the issue text.

Description

Throughout the CTS, many functions return int, but for different purposes. Sometimes, the int is an OpenCL error code. In other places, the int is the test status, such as whether the test passed, failed or was skipped.

It is very difficult to keep the different meanings of the int return value correct, and is is very common to unintentionally return an OpenCL error code instead of a test status. Because both CL_SUCCESS and TEST_PASS both have the value (zero), this mistake does usually does not cause an issue in practice, though there are no guarantees this is the case now or in the future.

Is this something we want to fix? I think this could take one of two forms:

  1. Embrace that the test status and OpenCL errors can be intermixed and stop trying to differentiate between the two.
    • The value zero will always indicate that the test passed, regardless whether it is CL_SUCCESS or TEST_PASS.
    • If we switched TEST_FAIL to be a negative value, a negative value could always indicate that the test failed, regardless whether it is an OpenCL error code or TEST_FAIL.
    • If we switched TEST_SKIPPED_ITSELF to be a positive value, a positive value coudl always indicate that the test was skipped.
    • Note, if we did this, we could clean up parts of the harness; for example, we wouldn't need both test_error and test_error_fail.
  2. Use a strongly typed test status instead, which would make it impossible to mix the two.
Dominant language
C++
Stars
234
Forks
240
Avg merge
6d 12h
Merged PRs (30d)
15

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from KhronosGroup/OpenCL-CTS

All issues in KhronosGroup/OpenCL-CTS

Similar issues

More C++ issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.