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/Support/elementary_macros.h

@@ -0,0 +1,69 @@
+//===--------- dpctl_elementary_macros.h - Defines helper macros -*-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
+/// Several helper C preprocessor macros used elsewhere in our code are defined
+/// here.
+///
+//===----------------------------------------------------------------------===//
+
+#pragma once
+
+/*!
+ * @brief defines a "__declspec(dllexport)" wrapper for windows.
+ *
+ */
+#ifdef _WIN32
+#ifdef DPCTLSyclInterface_EXPORTS
+#define DPCTL_API __declspec(dllexport)
+#else
+#define DPCTL_API __declspec(dllimport)
+#endif
+#else
+#define DPCTL_API
+#endif
+
+/*!
+ * @brief Convenience macros to add "extern C {" statements to headers.
+ *
+ */
+#ifdef __cplusplus
+#define DPCTL_C_EXTERN_C_BEGIN                                                 \
+    extern "C"                                                                 \
+    {
+#define DPCTL_C_EXTERN_C_END }
+#else
+#define DPCTL_C_EXTERN_C_BEGIN
+#define DPCTL_C_EXTERN_C_END
+#endif
+
+/*!
+ * @brief Convenience macro to add deprecation attributes to functions.
+ *
+ */
+#define DEPRACATION_NOTICE(notice, FN) notice " " #FN
+
+#if defined(__GNUC__) && !defined(__clang__)
+#define DPCTL_DEPRECATE(msg, repl_fn_name)                                     \
+    __attribute__((deprecated(DEPRACATION_NOTICE(msg, Use repl_fn_name))))
+#elif defined(__clang__)
+#define DPCTL_DEPRECATE(msg, repl_fn_name)                                     \
+    __attribute__((deprecated(msg, repl_fn_name)))
+#endif

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