From 10722d4f359a9dbb0e07007b28d5b6b47af50ecd Mon Sep 17 00:00:00 2001
From: Oleksandr Pavlyk <oleksandr.pavlyk@intel.com>
Date: Thu, 5 Oct 2023 15:51:59 -0500
Subject: [PATCH] SyclTimer.dt return object with named accessors

The object can unpack into a tuple, like before, but it prints
with annotation of what each number means, and provides names
getters.

  with timer(q):
      code

  dur = timer.dt
  print(dur)     # outputs (host_dt=..., device_dt=...)
  dur.host_dt    # get host-timer delta
  dur.device_dt  # get device-timer delta
  hdt, ddt = dur # unpack into a tuple
---
 dpctl/_sycl_timer.py           | 37 +++++++++++++++++++++++++++-------
 dpctl/tests/test_sycl_event.py |  7 ++++++-
 2 files changed, 36 insertions(+), 8 deletions(-)

diff --git a/dpctl/_sycl_timer.py b/dpctl/_sycl_timer.py
index 33c4c2995f..66dd4f9340 100644
--- a/dpctl/_sycl_timer.py
+++ b/dpctl/_sycl_timer.py
@@ -14,7 +14,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-
 import timeit
 
 from . import SyclQueue
@@ -22,6 +21,29 @@
 __doc__ = "This module implements :class:`dpctl.SyclTimer`."
 
 
+class HostDeviceDuration:
+    def __init__(self, host_dt, device_dt):
+        self._host_dt = host_dt
+        self._device_dt = device_dt
+
+    def __repr__(self):
+        return f"(host_dt={self._host_dt}, device_dt={self._device_dt})"
+
+    def __str__(self):
+        return f"(host_dt={self._host_dt}, device_dt={self._device_dt})"
+
+    def __iter__(self):
+        yield from [self._host_dt, self._device_dt]
+
+    @property
+    def host_dt(self):
+        return self._host_dt
+
+    @property
+    def device_dt(self):
+        return self._device_dt
+
+
 class SyclTimer:
     """
     SyclTimer(host_timer=timeit.default_timer, time_scale=1)
@@ -45,7 +67,7 @@ class SyclTimer:
                 code_block
 
             # retrieve elapsed times in milliseconds
-            sycl_dt, wall_dt = timer.dt
+            wall_dt, device_dt = timer.dt
 
     Remark:
         The timer submits barriers to the queue at the entrance and the
@@ -101,10 +123,11 @@ def __exit__(self, *args):
 
     @property
     def dt(self):
-        """Returns a tuple of elapsed times where first
-        element is the duration as measured by the host timer,
-        while the second element is the duration as measured by
-        the device timer and encoded in profiling events"""
+        """Returns a pair of elapsed times (host_dt, device_dt).
+
+        The host_dt is the duration as measured by the host
+        timer, while the device_dt is the duration as measured by
+        the device timer and encoded in profiling events."""
         for es, ef in self.bracketing_events:
             es.wait()
             ef.wait()
@@ -113,4 +136,4 @@ def dt(self):
             ef.profiling_info_start - es.profiling_info_end
             for es, ef in self.bracketing_events
         ) * (1e-9 * self.time_scale)
-        return (host_dt, dev_dt)
+        return HostDeviceDuration(host_dt, dev_dt)
diff --git a/dpctl/tests/test_sycl_event.py b/dpctl/tests/test_sycl_event.py
index fa496d1bb8..7f0db07539 100644
--- a/dpctl/tests/test_sycl_event.py
+++ b/dpctl/tests/test_sycl_event.py
@@ -202,7 +202,12 @@ def test_sycl_timer():
         m1.copy_from_device(m2)
         # host operation
         [x**2 for x in range(128 * 1024)]
-    host_dt, device_dt = timer.dt
+    elapsed = timer.dt
+    host_dt, device_dt = elapsed
+    assert isinstance(repr(elapsed), str)
+    assert isinstance(str(elapsed), str)
+    assert host_dt == elapsed.host_dt
+    assert device_dt == elapsed.device_dt
     assert host_dt > device_dt or (host_dt > 0 and device_dt >= 0)
     q_no_profiling = dpctl.SyclQueue()
     assert q_no_profiling.has_enable_profiling is False