Fix the error handling and reporting

[diptorupd]

The current dpctl error handling broke once we transitioned from the C++ API to the C API. The error reporting and handling in dpctl needs complete redesign.

[diptorupd]

We have the except + added to all of our Cython functions. We will need to change all the Cython cdefs and most probably add checks inside the Cython calls whereever we call these functions.

[diptorupd]

@PokhodenkoSA @1e-to

There are two broad design goals for error handling for dpCtl:

1. dpCtl will never raise any exceptions and by design should return a "logical" value back to caller to notify error. E.g. Wherever a dpCtl function returns a pointer, the function should return a nullptr if a valid pointer cannot be returned. The caller needs to be aware of this behavior and add appropriate NULL checks. Possible patterns can be:

Return Type	Returned Value
Pointer	Nullptr
size_t/int	-1
boolean	?
void	?

• We should add needed try-catch blocks for Sycl functions that can throw.
• Add Null checks during unwrap operations.

2. Once basic error handling has been implemented, we need to design the error reporter. I can think of two options:

• Let callers pass in a error handler call back function (like Sycl’s asynchronous error handler) that can be invoked when dpCtl wants to report an error.
• Or, we use a global error variable that gets set by every dpCtl function. The error variable can store an error code and error message and can be queried by the caller.

Our solution can be a combination of both approaches?

[oleksandr-pavlyk]

All DPCTL C-api functions change to have result_t type argument err passed by reference.

It is set to 0 (OK enum) for normal execution, or to a error-signaling enum otherwise.

Additionally, the DPCLSyclInterface library has global thread-local function to pointer to void (*handler)(int code, const char * c_str) which default to &default_handler:

void default_handler(int code, const char *message) {
    std::cerr << message << std::endl;
    // or fprintf(stderr, "%s\n", message);
}

When used by Python, the handler can be used to call PyErr_SetObject or PyErr_SetString to raise an exception. For example, following IntelPython/dpnp#201:

void python_handler(int code, const char * message) {
   if (PyErr_Occurred()) // if Python error has already been raised, do nothing
         return;
   switch(code) {
   case STD_BAD_ALLOC:
        PyErr_SetString(PyExc_MemoryError, message);
        break;
   case STD_BAD_CAST:
        PyErr_SetString(PyExc_TypeError, message);
        break;
   case SYCL_RUNTIME_ERROR:
        // could use PyErr_SetObject to pass both code and message to the exception constructor
        PyErr_SetString(PyExc_SyclError, message);
        break;
   ....
   default:
        break;
   } 
  return;
}

Cython functions calling DPCTL library will check for err, and check Python error signaling to drill into the details.

Also, all Cython cdef functions should have signature cdef func(...) except *: body per Cython docs.

The error handler function pointer will be used from within SYCL asynchronous error handler, used by DPCTL in SYCL context and SYCL queue constructors.

@PokhodenkoSA @shssf @Alexander-Makaryev @diptorupd @reazulhoque

[oleksandr-pavlyk]

Since DPCTLSyclInterface is a shared library, it should not use global structures (such as global function pointers) to enable two different processes using it from stepping on each other's toes.

@diptorupd pointed out that MPI solves this problem by keeping/passing around a library state (communicator).

Translating this solution to dpctl amounts to modifying all function calls to take a struct representing such a state (which would store the error handler). In all the places where library handles errors, the error handler from the struct would be called).

[diptorupd]

As the error handling infrastructure has been totally overhauled in libsyclinterface, the issue is ready to be closed.