Error guarantees and error safety

Issue #548 made me think: From my reading of the OpenCL spec, the expected behavior of an OpenCL implementation in the presence of an error is generally not specified. I think this could be a problem that affects portability.

As an example of what I mean by specified: C++ has four generally recognized levels of exception safety. Given these levels, it is clear to the API implementer which guarantees (if any) must hold when an exception is thrown, and it is clear to the API user which guarantees (if any) can be relied upon to hold even after an exception. std::string::insert(), for example, has a strong exception guarantee, which means that if any exception is thrown, the string object must be rolled back to the state before insert() was called.

OpenCL doesn't make any such guarantees. Most reasonable users and implementers might expect, for example, that calling clSetKernelArg(NULL, 0, size, value); would not change any state within the OpenCL runtime, but would only return a CL_INVALID_KERNEL code. But is the implementation actually required to do this? What if instead, the implementation goes into an undefined state -- is that allowed?

clSetKernelArg() is a trivial example, but it's easy to imagine much more complicated sequences of API calls. When an error is encountered, it's not clear what the implementation is allowed to do, or what the API user is allowed to assume about the state of OpenCL objects or the OpenCL runtime.

I imagine that for every error code, one or more of the following statements could be made:

• The states of the function parameters are rolled back to their states just before the function call
• The state of the OpenCL runtime is rolled back to the state just before the function call
• Function parameter X is in a valid state, but the state may be different from the state just before the function call
• The OpenCL runtime is in a valid state, but it may be different from the state just before the function call
• Object X may be in an implementation-defined state
• Object X may be in an undefined state
• The OpenCL runtime may be in an undefined state

If I'm an OpenCL application developer, without guarantees like this, the only truly safe thing I can do is quit my application every time I see any error code. If guarantees like this were to exist, I could design my application to correctly handle various error codes, and I could have confidence that the way I handle the error codes is portable across implementations.

Start by reviewing issue #548 and the OpenCL specification passages relevant to error handling, then examine the clSetKernelArg example and the listed possible guarantees. Determine whether the specification should define portable post-error state guarantees and document the agreed behavior for API users and implementers.