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

Author: oleksandr-pavlyk

dpctl/_sycl_timer.py

@@ -14,14 +14,36 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-
 import timeit
 
 from . import SyclQueue
 
 __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)

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