.. SPDX-FileCopyrightText: 2021 Intel Corporation
..
.. SPDX-License-Identifier: CC-BY-4.0

.. _onedtl_api_design:

API Design
-----------

This section describes the design of the oneDTL API. 
It will cover the use of namespaces and data types from C++, from DPC++, and new data types introduced for oneDTL API.

.. _onedtl_namespaces:

oneDTL Namespaces
++++++++++++++++++

The oneDTL library uses the ``oneapi::dtl`` C++ namespace. 
All oneDTL objects and routines must be contained within this namespace.
Non-public APIs and headers must be enclosed by the ``detail`` namespace and corresponding folder.

.. _onedtl_cpp_datatypes:

Standard C++ Data Types
+++++++++++++++++++++++++++

oneDTL uses C++ STL data types for scalars where applicable:

* Integer scalars must be C++ fixed-size integer types (``std::intN_t``, ``std::uintN_t``).
* Standard floating point types must be ``float``, ``double``.

.. _onedtl_dpcpp_datatypes:

DPC++ Data Type Usage
++++++++++++++++++++++

oneDTL uses the following DPC++ data types:

* ``sycl::half`` - SYCL standard floating point type for fp16.
* ``sycl::buffer`` - SYCL buffer for buffer-based memory access.
* ``sycl::range`` - SYCL range for description of number of elements.
* ``sycl::queue`` - SYCL queue for scheduling kernels on a SYCL device.
* ``sycl::event`` - SYCL event for explicit control of scheduling of kernels, and querying status of a running kernel.