python: add wrapper code for ITT-NERSC implementation to ensure compatibility

python/MANIFEST.in

@@ -4,6 +4,7 @@ include pyproject.toml
 include setup.py
 recursive-include ittapi *.py
 recursive-include ittapi.native *.cpp *.hpp
+recursive-include itt_NERSC *.py
 recursive-include ../include *.h
 recursive-include ../LICENSES *
 recursive-include ../src *

python/itt_NERSC/__init__.py

@@ -0,0 +1,8 @@
+"""
+Python binding to NERSC implementation of Intel Instrumentation and Tracing Technology (ITT) API.
+"""
+from ittapi.native import pt_region_begin, pt_region_end
+from .collection_control import resume, pause, detach
+from .domain import domain_create
+from .task import task_begin, task_end
+from .pt_region import pt_region_create

python/itt_NERSC/collection_control.py

@@ -0,0 +1,19 @@
+from ittapi.native import detach as _detach, pause as _pause, resume as _resume
+
+def detach():
+    """
+    Detach collection of profiling data.
+    """
+    _detach()
+
+def resume():
+    """
+    Resume collection of profiling data.
+    """
+    _resume()
+
+def pause():
+    """
+    Pause collection of profiling data.
+    """
+    _pause()

python/itt_NERSC/domain.py

@@ -0,0 +1,10 @@
+from ittapi.native import Domain as _Domain
+
+def domain_create(name=None):
+    """
+    Creates a domain with the given name.
+    :param name: a name of the domain
+    :return: a handle to the created domain with given name if the `name` is not None,
+    otherwise, returns handle to default domain.
+    """
+    return _Domain(name)

python/itt_NERSC/pt_region.py

@@ -0,0 +1,13 @@
+"""
+pt_region.py - Python module wrapper for process trace control region(PT_Region)
+"""
+
+from ittapi.native import PT_Region as _PT_Region
+
+def pt_region_create(name):
+    """
+    This function saves a region name marked with Intel PT API and returns a handle for the created region with the given name.
+    :param name: a name for the region, this name can't be empty
+    :return: a handle for the created region with the given name
+    """
+    return _PT_Region(name)

python/itt_NERSC/task.py

@@ -0,0 +1,15 @@
+from ittapi.native import task_begin as _task_begin, task_end as _task_end
+
+from ittapi.native import StringHandle as _StringHandle
+
+def task_begin(domain, task_name:str):
+    """
+    Marks the beginning of a task.
+    """
+    _task_begin(domain, _StringHandle(task_name))
+
+def task_end(domain):
+    """
+    Marks the ending of task.
+    """
+    _task_end(domain)

python/ittapi.native/ittapi.cpp

@@ -8,6 +8,7 @@
 #include "string_handle.hpp"
 #include "task.hpp"
 #include "thread_naming.hpp"
+#include "pt_region.hpp"
 
 
 namespace ittapi
@@ -32,6 +33,8 @@ static int exec_ittapi_module(PyObject* module)
         {"task_end",              task_end,              METH_VARARGS, "Marks the end of a task."},
         {"task_begin_overlapped", task_begin_overlapped, METH_VARARGS, "Marks the beginning of an overlapped task."},
         {"task_end_overlapped",   task_end_overlapped,   METH_VARARGS, "Marks the end of an overlapped task."},
+        {"pt_region_begin", itt_NERSC::pt_region_begin, METH_VARARGS, "Marks the begining of a processor trace control region"},
+        {"pt_region_end", itt_NERSC::pt_region_end, METH_VARARGS, "Marks the ending of a processor trace control region"},
         /* marks end of array */
         { nullptr },
     };
@@ -61,6 +64,7 @@ PyMODINIT_FUNC PyInit_native()
         { Py_mod_exec, reinterpret_cast<void*>(exec_event) },
         { Py_mod_exec, reinterpret_cast<void*>(exec_id) },
         { Py_mod_exec, reinterpret_cast<void*>(exec_string_handle) },
+        { Py_mod_exec, reinterpret_cast<void*>(itt_NERSC::exec_pt_region) },
         { 0, nullptr }
     };
 

python/ittapi.native/pt_region.cpp

@@ -0,0 +1,272 @@
+#include "pt_region.hpp"
+
+#include <structmember.h>
+
+#include "string_handle.hpp"
+#include "extensions/string.hpp"
+
+namespace ittapi
+{
+namespace itt_NERSC
+{
+
+template<typename T>
+T* pt_region_cast(PT_Region* self);
+
+template <>
+PyObject* pt_region_cast(PT_Region* self)
+{
+    return reinterpret_cast<PyObject*>(self);
+}
+
+static PyObject* pt_region_new(PyTypeObject* type, PyObject* args, PyObject* kwargs);
+static void pt_region_dealloc(PyObject* self);
+
+static PyObject* pt_region_repr(PyObject* self);
+static PyObject* pt_region_str(PyObject* self);
+
+static PyMemberDef pt_region_attrs[] =
+{
+    {"name",  T_OBJECT, offsetof(PT_Region, name), READONLY, "a pt_region name"},
+    {nullptr},
+};
+
+PyTypeObject PT_RegionType =
+{
+    .ob_base              = PyVarObject_HEAD_INIT(nullptr, 0)
+    .tp_name              = "ittapi.native.PT_Region",
+    .tp_basicsize         = sizeof(PT_Region),
+    .tp_itemsize          = 0,
+
+    /* Methods to implement standard operations */
+    .tp_dealloc           = pt_region_dealloc,
+    .tp_vectorcall_offset = 0,
+    .tp_getattr           = nullptr,
+    .tp_setattr           = nullptr,
+    .tp_as_async          = nullptr,
+    .tp_repr              = pt_region_repr,
+
+    /* Method suites for standard classes */
+    .tp_as_number         = nullptr,
+    .tp_as_sequence       = nullptr,
+    .tp_as_mapping        = nullptr,
+
+    /* More standard operations (here for binary compatibility) */
+    .tp_hash              = nullptr,
+    .tp_call              = nullptr,
+    .tp_str               = pt_region_str,
+    .tp_getattro          = nullptr,
+    .tp_setattro          = nullptr,
+
+    /* Functions to access object as input/output buffer */
+    .tp_as_buffer         = nullptr,
+
+    /* Flags to define presence of optional/expanded features */
+    .tp_flags             = Py_TPFLAGS_DEFAULT,
+
+    /* Documentation string */
+    .tp_doc               = "A class that represents a __itt_pt_region(__itt_pt_region -> unsigned char)",
+
+    /* Assigned meaning in release 2.0 call function for all accessible objects */
+    .tp_traverse          = nullptr,
+
+    /* Delete references to contained objects */
+    .tp_clear             = nullptr,
+
+    /* Assigned meaning in release 2.1 rich comparisons */
+    .tp_richcompare       = nullptr,
+
+    /* weak reference enabler */
+    .tp_weaklistoffset    = 0,
+
+    /* Iterators */
+    .tp_iter              = nullptr,
+    .tp_iternext          = nullptr,
+
+    /* Attribute descriptor and subclassing stuff */
+    .tp_methods           = nullptr,
+    .tp_members           = pt_region_attrs,
+    .tp_getset            = nullptr,
+
+    /* Strong reference on a heap type, borrowed reference on a static type */
+    .tp_base              = nullptr,
+    .tp_dict              = nullptr,
+    .tp_descr_get         = nullptr,
+    .tp_descr_set         = nullptr,
+    .tp_dictoffset        = 0,
+    .tp_init              = nullptr,
+    .tp_alloc             = nullptr,
+    .tp_new               = pt_region_new,
+
+    /* Low-level free-memory routine */
+    .tp_free              = nullptr,
+
+    /* For PyObject_IS_GC */
+    .tp_is_gc             = nullptr,
+    .tp_bases             = nullptr,
+
+    /* method resolution order */
+    .tp_mro               = nullptr,
+    .tp_cache             = nullptr,
+    .tp_subclasses        = nullptr,
+    .tp_weaklist          = nullptr,
+    .tp_del               = nullptr,
+
+    /* Type attribute cache version tag. Added in version 2.6 */
+    .tp_version_tag       = 0,
+
+    .tp_finalize          = nullptr,
+    .tp_vectorcall        = nullptr,
+};
+
+static PyObject* pt_region_new(PyTypeObject* type, PyObject* args, PyObject* kwargs)
+{
+    PT_Region* self = pt_region_obj(type->tp_alloc(type,0));
+    if (self == nullptr)
+    {
+        return nullptr;
+    }
+
+    char name_key[] = { "name" };
+    char* kwlist[] = { name_key, nullptr };
+
+    PyObject* name = nullptr;
+
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs, "O", kwlist, &name))
+    {
+        return nullptr;
+    }
+
+    if (name && PyUnicode_Check(name))
+    {
+        self->name = pyext::new_ref(name);
+    }
+    else if (name && Py_TYPE(name) == &StringHandleType)
+    {
+        self->name = pyext::new_ref(string_handle_obj(name)->str);
+    }
+    else
+    {
+        Py_DecRef(pt_region_cast<PyObject>(self));
+
+        PyErr_SetString(PyExc_TypeError, "The passed string to create pt_region is not a valid instance of neither str nor StringHandle");
+        return nullptr;
+    }
+
+    pyext::string name_str = pyext::string::from_unicode(self->name);
+    if (name_str.c_str() == nullptr)
+    {
+        Py_DecRef(pt_region_cast<PyObject>(self));
+        return nullptr;
+    }
+
+#if defined(_WIN32)
+    self->handle=__itt_pt_region_createW(name_str.c_str());
+#else
+    self->handle=__itt_pt_region_create(name_str.c_str());
+#endif
+
+    return pt_region_cast<PyObject>(self);
+}
+
+static void pt_region_dealloc(PyObject* self)
+{
+    if (self == nullptr)
+    {
+        return;
+    }
+
+    PT_Region* obj = pt_region_obj(self);
+    Py_XDECREF(obj->name);
+}
+
+static PyObject* pt_region_repr(PyObject* self)
+{
+    PT_Region* obj = pt_region_check(self);
+    if (obj == nullptr)
+    {
+        return nullptr;
+    }
+
+    if (obj->name == nullptr)
+    {
+        PyErr_SetString(PyExc_AttributeError, "The name attribute has not been initialized.");
+        return nullptr;
+    }
+
+    return PyUnicode_FromFormat("%s('%U')", PT_RegionType.tp_name, obj->name);
+}
+
+static PyObject* pt_region_str(PyObject* self)
+{
+    PT_Region* obj = pt_region_check(self);
+    if (obj == nullptr)
+    {
+        return nullptr;
+    }
+
+    if (obj->name == nullptr)
+    {
+        PyErr_SetString(PyExc_AttributeError, "The name attribute has not been initialized.");
+        return nullptr;
+    }
+
+    return pyext::new_ref(obj->name);
+}
+
+PT_Region* pt_region_check(PyObject* self)
+{
+    if (self == nullptr || Py_TYPE(self) != &PT_RegionType)
+    {
+        PyErr_SetString(PyExc_TypeError, "The passed pt_region is not a valid instance of PT_Region type.");
+        return nullptr;
+    }
+
+    return pt_region_obj(self);
+}
+
+int exec_pt_region(PyObject* module)
+{
+    return pyext::add_type(module, &PT_RegionType);
+}
+
+PyObject* pt_region_begin(PyObject* self, PyObject* args)
+{
+    PyObject* pt_region = nullptr;
+    if (!PyArg_ParseTuple(args, "O", &pt_region))
+    {
+        return nullptr;
+    }
+
+    PT_Region *pt_region_obj = pt_region_check(pt_region);
+    if (pt_region_obj == nullptr)
+    {
+        return nullptr;
+    }
+
+    __itt_mark_pt_region_begin(pt_region_obj->handle);
+
+    Py_RETURN_NONE;
+}
+
+PyObject* pt_region_end(PyObject* self, PyObject* args)
+{
+    PyObject* pt_region = nullptr;
+    if (!PyArg_ParseTuple(args, "O", &pt_region))
+    {
+        return nullptr;
+    }
+
+    PT_Region *pt_region_obj = pt_region_check(pt_region);
+    if (pt_region_obj == nullptr)
+    {
+        return nullptr;
+    }
+
+    __itt_mark_pt_region_end(pt_region_obj->handle);
+
+    Py_RETURN_NONE;
+}
+
+} // namespace itt_NERSC
+} // namespace ittapi