Add a new DPCTLExecState type to improve error handling.

  - A new DPCTLExecState type and associated constructors
    and destructors are added.
  - The error_handler_callback is depracated and is superseded
    by the new error_handler_callback_fn type. The new function
    type allows passing in both an error code and an error
    message.
  - A default error handler function is defined that will
    print out an error code and associated error message to
    std::cerr.

Author: Diptorup Deb

dpctl-capi/include/dpctl_error_handler_type.h

@@ -32,4 +32,14 @@
  * @param    err_code       Error code extracted from an SYCL asynchronous
  * error.
  */
-typedef void error_handler_callback(int err_code);
+typedef void error_handler_callback(int err_code) __attribute__((
+    deprecated("the function does not allow passing in an error string, use "
+               "'error_handler_callback_fn' instead!!!")));
+
+/*!
+ * @brief Type signature required for an error handler callback function.
+ *
+ * @param    err_code       My Param doc
+ * @param    err_msg        My Param doc
+ */
+typedef void (*error_handler_callback_fn)(int err_code, const char *err_msg);

dpctl-capi/include/dpctl_exec_state.h

@@ -0,0 +1,74 @@
+//===- dpctl_exec_state.h - C API for service functions          -*-C++-*- ===//
+//
+//                      Data Parallel Control (dpctl)
+//
+// Copyright 2020-2021 Intel Corporation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// The file declares a struct to store dpctl's error handler and other
+/// execution state configurations.
+///
+//===----------------------------------------------------------------------===//
+
+#pragma once
+
+#include "Support/DllExport.h"
+#include "Support/ExternC.h"
+#include "Support/MemOwnershipAttrs.h"
+#include "dpctl_error_handler_type.h"
+
+DPCTL_C_EXTERN_C_BEGIN
+
+/*!
+ * @brief An opaque type to represent an "execution state" for the dpctl
+ * sycl interface library.
+ *
+ * The execution state controls the behavior of functions exposed by
+ * libDPCTLSyclInterface. For now, only error handling is controlled by an
+ * execution state. Using a custom execution state, users can define how
+ * exceptions in the C++ code are handled and propagated to callers. A default
+ * execution state where all exceptions are caught and the error messages
+ * printed to ``std::cerr`` is included for convenience.
+ *
+ */
+typedef struct DpctlExecutionState *DPCTLExecState;
+
+/*!
+ * @brief Create a new ``DPCTLExecState`` object.
+ *
+ * @param    handler        An error handler function.
+ * @return   A ``DPCTLExecState`` opaque pointer.
+ */
+__dpctl_give DPCTLExecState
+dpctl_exec_state_create(const error_handler_callback_fn handler);
+
+/*!
+ * @brief Create a default execution state that prints the error message to
+ * ``std::cerr``.
+ *
+ * @return   A ``DPCTLExecState`` opaque pointer.
+ */
+__dpctl_give DPCTLExecState dpctl_exec_state_create_default();
+
+/*!
+ * @brief Delete an ``DPCTLExecState`` opaque pointer.
+ *
+ * @param    DPCTLExecState A ``DPCTLExecState`` opaque pointer to be freed.
+ */
+void dpctl_exec_state_delete(__dpctl_take DPCTLExecState state);
+
+DPCTL_C_EXTERN_C_END

dpctl-capi/include/dpctl_service.h

@@ -19,7 +19,7 @@
 //===----------------------------------------------------------------------===//
 ///
 /// \file
-/// This header defines dpctl service functions.
+/// This header declares dpctl service functions.
 ///
 //===----------------------------------------------------------------------===//
 

dpctl-capi/source/dpctl_exec_state.cpp

@@ -0,0 +1,113 @@
+//===- dpctl_exec_state.cpp - Implements C API for sycl::context         ---==//
+//
+//                      Data Parallel Control (dpctl)
+//
+// Copyright 2020-2021 Intel Corporation
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+//===----------------------------------------------------------------------===//
+///
+/// \file
+/// This file implements the data types and functions declared in
+/// dpctl_exec_state.h.
+///
+//===----------------------------------------------------------------------===//
+
+#include "dpctl_exec_state.h"
+#include "Support/CBindingWrapping.h"
+#include <iostream>
+
+namespace
+{
+
+/*!
+ * @brief A default error handler function that prints out the error code and
+ * the error message to ``std::cerr``.
+ *
+ * @param    err_code       My Param doc
+ * @param    err_msg        My Param doc
+ */
+void default_handler(int err_code, const char *err_msg)
+{
+    std::cerr << "DPCTL-ERROR (" << err_code << ") " << err_msg;
+}
+
+/*!
+ * @brief The execution state that is passed to every libDPCTLSyclInterface
+ * function.
+ *
+ * The ``ExecutionState`` class is a concrete implementation of the
+ * `DPCTLExecState`` opaque type.
+ *
+ */
+class ExecutionState
+{
+    const error_handler_callback_fn handler_;
+
+public:
+    /*!
+     * @brief Construct a new ``ExecutionState`` object using the default error
+     * handler object.
+     *
+     */
+    ExecutionState() : handler_(default_handler){};
+    /*!
+     * @brief Construct a new ``ExecutionState`` object with the provided error
+     * handler function.
+     *
+     * @param    handler        Error handler function to be used by the
+     * instance of ``ExecutionState``.
+     */
+    explicit ExecutionState(const error_handler_callback_fn handler)
+        : handler_(handler)
+    {
+    }
+
+    void operator()(int err_code, const char *err_msg) const
+    {
+        handler_(err_code, err_msg);
+    }
+};
+
+DEFINE_SIMPLE_CONVERSION_FUNCTIONS(ExecutionState, DPCTLExecState);
+
+} // namespace
+
+__dpctl_give DPCTLExecState
+dpctl_exec_state_create(const error_handler_callback_fn handler)
+{
+    try {
+        ExecutionState *state = new ExecutionState(handler);
+        return wrap(state);
+    } catch (std::bad_alloc const &ba) {
+        std::cerr << ba.what() << '\n';
+        std::terminate();
+    }
+}
+
+__dpctl_give DPCTLExecState dpctl_exec_state_create_default()
+{
+    try {
+        ExecutionState *state = new ExecutionState();
+        return wrap(state);
+    } catch (std::bad_alloc const &ba) {
+        std::cerr << ba.what() << '\n';
+        std::terminate();
+    }
+}
+
+void dpctl_exec_state_delete(__dpctl_take DPCTLExecState state)
+{
+    delete unwrap(state);
+}