Dpctl c api constructors added, dpctl/include restructured

[oleksandr-pavlyk]

Refactored dpctl/include layout. Instead of containing all files from libsyclinterface/include it introduces substructure:

   dpctl/
      include/
         syclinterface/
              *.h   # all the files that used to be in dpctl/include
         syclinterface.h   
         dpctl_capi.h
         dpctl4pybind11.hpp

The newly added files are residing in new folder dpctl/apis/include from which build_backend.py copies then into dpctl/include

Modified _backend.pxd to include "syclinterface/" in the path.

Modified build_backend.py to reassemble dpctl/include from install/include and dpctl/apis/include.

Added make_Sycl* C-API functions to create SyclDevice, SyclQueue, SyclContext and SyclEvent from corresponding opaque reference. Used get_device_ref and make_SyclDevice to construct pybind11 type caster directly mapping dpctl.SyclDevice Python object to sycl::device in pybind11.

Modified examples files to use new headers, and use casters.

Verified that all Cython extensions and Pybind11 extensions are building and are running as expected.

[github-actions]

View rendered docs @ https://intelpython.github.io/dpctl/pulls/685/index.html

[coveralls]

Coverage increased (+0.06%) to 81.192% when pulling d42e403 on dpctl_c_api-constructors into 6fb23a3 on master.

[oleksandr-pavlyk]

@densmirn @Alexander-Makaryev Most likely dpnp is going to be affected by this change. Once this PR is merged, the downstream (relative to dpctl) libraries will need to #include "dpctl_sycl_interface.h" instead of including individual headers, such as dpctl_sycl_types.h and dpctl_sycl_queue_manager.h.

@napetrov Please forward this to relevant people working on scikit-learn-intelex.

[oleksandr-pavlyk]

@diptorupd This change is going to cause some disruption in downstream code:

1. https://github.com/IntelPython/numba-dppy/blob/main/numba_dppy/dpctl_iface/usm_shared_allocator_ext.c#L30
2. https://github.com/IntelPython/dpnp/blob/master/dpnp/backend/src/queue_sycl.hpp#L44
3. https://github.com/intel/scikit-learn-intelex/blob/master/src/dpctl_interop/daal_context_service.cpp#L20

I am not sure what DPPLQueueMgr_GetCurrentQueue is in scikit-learn-intelex, and I did not see it defined anywhere in the project. Perhaps @napetrov could clarify.

But perhaps to minimize the disruption, we could temporarily add symbolic links in dpctl/include/ for some commonly used header files?

[diptorupd]

But perhaps to minimize the disruption, we could temporarily add symbolic links in dpctl/include/ for some commonly used header files?

No please. It is a minimal change that we have enough time to fix in downstream. I will suggest that we keep the change out of 0.12 and then fix it.

[oleksandr-pavlyk]

I will suggest that we keep the change out of 0.12 and then fix it.

I am afraid I need parts of this PR (support for dpctl4pybind11) in 0.12.

How about we add a header file (`dpctl/include/dpctl_sycl_queue_manager.h` that contains `#error` with the text explaining what to do.

This header is to be removed before 0.12 tag is created.

Update

Downstream projects can use __has_include("name.h") preprocessor check:

#if defined __has_include
#   if __has_include("dpctl_sycl_interface.h")
#       include "dpctl_sycl_interface.h"
#   else
#       include "dpctl_sycl_queue_manager.h"    // include one or more explicit dpctl_sycl* headers
#   endif
#else
#   include "dpctl_sycl_interface.h"
#endif

for a transition period.

I would therefore merge this to master once this change is added to downstream projects.

[oleksandr-pavlyk]

I would therefore merge this to master once this change is added to downstream projects.

Actually, testing locally, there are no conflicts between this branch and the work in #683

[github-actions]

Deleted rendered PR docs from intelpython.github.com/dpctl, latest should be updated shortly. 🤞