Initial stubs for the error handling overhaul.

dpctl-capi/helper/include/dpctl_async_error_handler.h → dpctl-capi/helper/include/dpctl_error_handlers.h

@@ -44,3 +44,28 @@ class DPCTL_API DPCTL_AsyncErrorHandler
 
     void operator()(const cl::sycl::exception_list &exceptions);
 };
+
+/*!
+ * @brief Provides a static error handling function that prints an error code
+ * and message to the standard error stream.
+ *
+ */
+class DPCTL_API DefaultErrorHandler
+{
+public:
+    /*!
+     * @brief A default error handler function that prints out the error code
+     * and optionally the error message to ``std::cerr``.
+     *
+     * @param    err_code       An integer error code.
+     * @param    err_msg        A C string corresponding to an error message.
+     * @param    file_name      The file where the error occurred.
+     * @param    func_name      The function name where the error occurred.
+     * @param    line_num       The line number where the error occurred.
+     */
+    static void handler(int err_code,
+                        const char *err_msg,
+                        const char *file_name,
+                        const char *func_name,
+                        int line_num);
+};

dpctl-capi/helper/source/dpctl_async_error_handler.cpp → dpctl-capi/helper/source/dpctl_error_handlers.cpp

@@ -23,7 +23,9 @@
 /// context and queue contructors.
 //===----------------------------------------------------------------------===//
 
-#include "dpctl_async_error_handler.h"
+#include "dpctl_error_handlers.h"
+#include <iomanip>
+#include <iostream>
 
 void DPCTL_AsyncErrorHandler::operator()(
     const cl::sycl::exception_list &exceptions)
@@ -40,3 +42,29 @@ void DPCTL_AsyncErrorHandler::operator()(
         }
     }
 }
+
+void DefaultErrorHandler::handler(int err_code,
+                                  const char *err_msg,
+                                  const char *file_name,
+                                  const char *func_name,
+                                  int line_num)
+{
+    std::stringstream ss;
+
+    ss << "Dpctl-Error ";
+    if (file_name)
+        ss << "on " << file_name << " ";
+
+    if (func_name)
+        ss << "at " << func_name << " ";
+
+    if (line_num)
+        ss << "on line " << line_num << ".";
+
+    ss << " (" << err_code << ")";
+
+    if (err_msg)
+        ss << " " << err_msg << '\n';
+
+    std::cerr << ss.str();
+}

dpctl-capi/include/dpctl_error_handler_type.h

@@ -32,4 +32,21 @@
  * @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       An integer error code.
+ * @param    err_msg        A C string corresponding to an error message.
+ * @param    file_name      The file where the error occurred.
+ * @param    func_name      The function name where the error occurred.
+ * @param    line_num       The line number where the error occurred.
+ */
+typedef void (*error_handler_callback_fn)(int err_code,
+                                          const char *err_msg,
+                                          const char *file_name,
+                                          const char *func_name,
+                                          int line_num);

dpctl-capi/include/dpctl_exec_state.h

@@ -0,0 +1,101 @@
+//===- 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(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);
+
+/*!
+ * @brief Get the error handler defined in the ``DpctlExecState`` object.
+ *
+ * @param    state          An ``DpctlExecState`` object.
+ * @return A error_handler_callback_fn function pointer that was stored inside
+ * the DpctlExecState object.
+ */
+error_handler_callback_fn
+dpctl_exec_state_get_error_handler(__dpctl_keep DpctlExecState state);
+
+/*!
+ * @brief Call the error handler defined in the ``DpctlExecState`` object.
+ *
+ * @param    state          An ``DpctlExecState`` object.
+ * @param    err_code       An integer error code.
+ * @param    err_msg        A C string corresponding to an error message.
+ * @param    file_name      The file where the error occurred.
+ * @param    func_name      The function name where the error occurred.
+ * @param    line_num       The line number where the error occurred.
+ */
+void dpctl_exec_state_handle_error(__dpctl_keep DpctlExecState state,
+                                   int err_code,
+                                   __dpctl_keep const char *err_msg,
+                                   __dpctl_keep const char *file_name,
+                                   __dpctl_keep const char *func_name,
+                                   int line_num);
+
+DPCTL_C_EXTERN_C_END

dpctl-capi/include/dpctl_sycl_device_interface.h

@@ -31,12 +31,18 @@
 #include "Support/ExternC.h"
 #include "Support/MemOwnershipAttrs.h"
 #include "dpctl_data_types.h"
+#include "dpctl_exec_state.h"
 #include "dpctl_sycl_device_manager.h"
 #include "dpctl_sycl_enum_types.h"
 #include "dpctl_sycl_types.h"
 
 DPCTL_C_EXTERN_C_BEGIN
 
+#define DEPRACATION_NOTICE                                                     \
+    "The function is deprecated to change the naming convention and "          \
+    "support the new DpctlExecState argument to improve error "                \
+    "handling and reporting."
+
 /**
  * @defgroup DeviceInterface Device class C wrapper
  */
@@ -49,20 +55,33 @@ DPCTL_C_EXTERN_C_BEGIN
  * DPCTLSyclDeviceRef object.
  * @ingroup DeviceInterface
  */
+DPCTL_API __dpctl_give DPCTLSyclDeviceRef
+DPCTLDevice_Copy(__dpctl_keep const DPCTLSyclDeviceRef DRef)
+    __attribute__((deprecated(DEPRACATION_NOTICE, "dpctl_device_copy")));
+
+/*!
+ * @brief Returns a copy of the DPCTLSyclDeviceRef object.
+ *
+ * @param    ES             The execution state object used for error handling.
+ * @param    DRef           DPCTLSyclDeviceRef object to be copied.
+ * @return   A new DPCTLSyclDeviceRef created by copying the passed in
+ * DPCTLSyclDeviceRef object.
+ * @ingroup DeviceInterface
+ */
 DPCTL_API
 __dpctl_give DPCTLSyclDeviceRef
-DPCTLDevice_Copy(__dpctl_keep const DPCTLSyclDeviceRef DRef);
+dpctl_device_copy(__dpctl_keep const DPCTLSyclDeviceRef DRef,
+                  __dpctl_keep const DpctlExecState ES);
 
 /*!
- * @brief Returns a new DPCTLSyclDeviceRef opaque object wrapping a SYCL device
- * instance as a host device.
+ * @brief Returns a new DPCTLSyclDeviceRef opaque object wrapping a SYCL
+ * device instance as a host device.
  *
- * @return   An opaque pointer to a ``sycl::device`` created as an instance of
- * the host device.
+ * @return   An opaque pointer to a ``sycl::device`` created as an instance
+ * of the host device.
  * @ingroup DeviceInterface
  */
-DPCTL_API
-__dpctl_give DPCTLSyclDeviceRef DPCTLDevice_Create(void);
+DPCTL_API __dpctl_give DPCTLSyclDeviceRef DPCTLDevice_Create(void);
 
 /*!
  * @brief Returns a new DPCTLSyclDeviceRef opaque object created using the

dpctl-capi/source/dpctl_exec_state.cpp

@@ -0,0 +1,140 @@
+//===- 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 "../helper/include/dpctl_error_handlers.h"
+#include "Support/CBindingWrapping.h"
+#include <iomanip>
+#include <iostream>
+
+namespace
+{
+
+/*!
+ * @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
+{
+    error_handler_callback_fn handler_;
+
+public:
+    /*!
+     * @brief Construct a new ``ExecutionState`` object using the default error
+     * handler object.
+     *
+     */
+    ExecutionState() : handler_(DefaultErrorHandler::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(error_handler_callback_fn handler)
+        : handler_(handler)
+    {
+    }
+
+    void operator()(int err_code,
+                    const char *err_msg,
+                    const char *file_name,
+                    const char *func_name,
+                    int line_num) const
+    {
+        handler_(err_code, err_msg, file_name, func_name, line_num);
+    }
+
+    error_handler_callback_fn get_handler() const
+    {
+        return handler_;
+    }
+};
+
+DEFINE_SIMPLE_CONVERSION_FUNCTIONS(ExecutionState, DpctlExecState);
+
+} // namespace
+
+__dpctl_give DpctlExecState
+dpctl_exec_state_create(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);
+}
+
+error_handler_callback_fn
+dpctl_exec_state_get_error_handler(__dpctl_keep DpctlExecState state)
+{
+    auto ES = unwrap(state);
+    if (!ES) {
+        std::cerr << "Execution state is corrupted. Abort!\n";
+        std::terminate();
+    }
+
+    return ES->get_handler();
+}
+
+void dpctl_exec_state_handle_error(__dpctl_keep DpctlExecState state,
+                                   int err_code,
+                                   __dpctl_keep const char *err_msg,
+                                   __dpctl_keep const char *file_name,
+                                   __dpctl_keep const char *func_name,
+                                   int line_num)
+{
+    auto ES = unwrap(state);
+    if (!ES) {
+        std::cerr << "Execution state is corrupted. Abort!\n";
+        std::terminate();
+    }
+
+    (*ES)(err_code, err_msg, file_name, func_name, line_num);
+}