Skip to content

Commit 2d6d8ea

Browse files
committed
use an in-order order manager for in-order queues
_InOrderManager keeps only the most recently added events, and submitted_events is the queue's last event when get_last_event is available. It is cached like _SequentialOrderManager, so clear() and thread exit wait on the queue.
1 parent 0a0bb05 commit 2d6d8ea

4 files changed

Lines changed: 227 additions & 5 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1212

1313
### Changed
1414

15+
* `dpctl.utils.SequentialOrderManager` keeps only the most recently added events for in-order queues, and `submitted_events` returns the queue's last event when `sycl_ext_oneapi_in_order_queue_events` is available [gh-2299](https://github.com/IntelPython/dpctl/pull/2299)
16+
1517
### Deprecated
1618

1719
### Removed

‎docs/doc_sources/api_reference/dpctl/utils.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,11 @@
1515

1616
Thread-local object mapping each :class:`dpctl.SyclQueue` to an order
1717
manager, used to ensure sequential ordering of offloaded tasks.
18+
19+
For an in-order queue, the queue orders the tasks, and the order manager
20+
keeps only the most recently added events. ``submitted_events`` is the
21+
event of the last command submitted to the queue if
22+
:meth:`dpctl.SyclQueue.is_get_last_event_available` is ``True``, and the
23+
most recently added computation events otherwise. Only in the first case
24+
does it cover tasks submitted to the queue without being added to the
25+
order manager, e.g. by other threads. ``wait`` waits on the queue.

‎dpctl/tests/test_utils.py‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,13 @@
1616

1717
"""Defines unit test cases for utility functions."""
1818

19+
import numpy as np
1920
import pytest
2021

2122
import dpctl
23+
import dpctl.memory
2224
import dpctl.utils
25+
from dpctl.utils import _order_manager
2326

2427

2528
@pytest.mark.filterwarnings("ignore:.*:RuntimeWarning")
@@ -92,3 +95,112 @@ def test_order_manager():
9295
_passed = True
9396
finally:
9497
assert _passed
98+
99+
100+
def _in_order_queue(*args, cls=dpctl.SyclQueue):
101+
try:
102+
return cls(*args, property="in_order")
103+
except dpctl.SyclQueueCreationError:
104+
pytest.skip("Queue could not be created for default-selected device")
105+
106+
107+
@pytest.fixture(params=[True, False], ids=["last_event", "added_events"])
108+
def use_last_event(request, monkeypatch):
109+
if request.param and not dpctl.SyclQueue.is_get_last_event_available():
110+
pytest.skip("sycl_ext_oneapi_in_order_queue_events not available")
111+
monkeypatch.setattr(_order_manager, "_use_last_event", request.param)
112+
return request.param
113+
114+
115+
def test_in_order_order_manager(use_last_event):
116+
q = _in_order_queue()
117+
_som = dpctl.utils.SequentialOrderManager
118+
_mngr = _som[q]
119+
assert _som[q] is _mngr
120+
assert _mngr.num_host_task_events == 0
121+
assert _mngr.num_submitted_events == 0
122+
assert isinstance(_mngr.submitted_events, list)
123+
assert isinstance(_mngr.host_task_events, list)
124+
_mngr.add_event_pair(dpctl.SyclEvent(), dpctl.SyclEvent())
125+
_mngr.add_event_pair([dpctl.SyclEvent()], dpctl.SyclEvent())
126+
ht_ev, comp_ev = dpctl.SyclEvent(), dpctl.SyclEvent()
127+
_mngr.add_event_pair(ht_ev, [comp_ev])
128+
# only the most recently added events are kept
129+
assert _mngr.host_task_events == [ht_ev]
130+
assert _mngr.num_host_task_events == 1
131+
# nothing was submitted to the queue, so both modes return added events
132+
assert _mngr.submitted_events == [comp_ev]
133+
assert _mngr.num_submitted_events == 1
134+
_mngr.wait()
135+
cpy = _mngr.__copy__()
136+
assert cpy.host_task_events == [ht_ev]
137+
assert cpy.submitted_events == [comp_ev]
138+
_som.clear()
139+
del cpy
140+
141+
142+
def test_in_order_order_manager_submitted_events(use_last_event):
143+
q = _in_order_queue()
144+
_mngr = dpctl.utils.SequentialOrderManager[q]
145+
buf = dpctl.memory.MemoryUSMDevice(1024, queue=q)
146+
comp_ev = q.memset_async(buf, 1, 1024)
147+
ht_ev = q._submit_keep_args_alive((buf,), [comp_ev])
148+
_mngr.add_event_pair(ht_ev, comp_ev)
149+
if use_last_event:
150+
# the keep-alive task is the last command submitted to the queue
151+
assert len(_mngr.submitted_events) == 1
152+
assert _mngr.submitted_events[0] is not comp_ev
153+
else:
154+
assert _mngr.submitted_events == [comp_ev]
155+
# work which is not added to the order manager
156+
q.memset_async(buf, 2, 1024)
157+
if use_last_event:
158+
assert len(_mngr.submitted_events) == 1
159+
else:
160+
assert _mngr.submitted_events == [comp_ev]
161+
dpctl.utils.SequentialOrderManager.clear()
162+
163+
164+
def test_in_order_order_manager_other_queue_depends(use_last_event):
165+
q_in = _in_order_queue()
166+
q_other = dpctl.SyclQueue(q_in.sycl_context, q_in.sycl_device)
167+
_mngr = dpctl.utils.SequentialOrderManager[q_in]
168+
nbytes, n_fills = 32 * 1024 * 1024, 8
169+
buf = dpctl.memory.MemoryUSMDevice(nbytes, queue=q_in)
170+
host = np.empty(nbytes, dtype=np.uint8)
171+
for _ in range(3):
172+
q_in.memset(buf, 0, nbytes)
173+
for v in range(1, n_fills + 1):
174+
comp_ev = q_in.memset_async(buf, v, nbytes)
175+
ht_ev = q_in._submit_keep_args_alive((buf,), [comp_ev])
176+
_mngr.add_event_pair(ht_ev, comp_ev)
177+
# work on another queue must wait for work done on the in-order queue
178+
deps = _mngr.submitted_events
179+
assert deps
180+
q_other.memcpy_async(host, buf, nbytes, dEvents=deps).wait()
181+
assert np.all(host == n_fills)
182+
dpctl.utils.SequentialOrderManager.clear()
183+
184+
185+
class _WaitCountingQueue(dpctl.SyclQueue):
186+
def __init__(self, *args, **kwargs):
187+
self.num_waits = 0
188+
189+
def wait(self):
190+
self.num_waits += 1
191+
super().wait()
192+
193+
194+
def test_in_order_order_manager_waits_on_queue():
195+
q = _in_order_queue(cls=_WaitCountingQueue)
196+
_som = dpctl.utils.SequentialOrderManager
197+
_mngr = _som[q]
198+
_mngr.wait()
199+
assert q.num_waits == 1
200+
cpy = _mngr.__copy__()
201+
del cpy
202+
assert q.num_waits == 2
203+
del _mngr
204+
# clear() runs at exit, and must wait on in-order queues as well
205+
_som.clear()
206+
assert q.num_waits > 2

‎dpctl/utils/_order_manager.py‎

Lines changed: 105 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,40 @@
11
import sys
22
import threading
33
import weakref
4-
from collections import defaultdict
4+
from collections.abc import Sequence
5+
from typing import Protocol
56

67
from .._sycl_event import SyclEvent
78
from .._sycl_queue import SyclQueue
89
from ._seq_order_keeper import _OrderManager
910

1011

12+
class OrderManagerProtocol(Protocol):
13+
"""Interface of order managers returned by ``SequentialOrderManager``."""
14+
15+
def add_event_pair(
16+
self,
17+
host_task_ev: SyclEvent | Sequence[SyclEvent],
18+
comp_ev: SyclEvent | Sequence[SyclEvent],
19+
) -> None: ...
20+
21+
@property
22+
def num_host_task_events(self) -> int: ...
23+
24+
@property
25+
def num_submitted_events(self) -> int: ...
26+
27+
@property
28+
def host_task_events(self) -> list[SyclEvent]: ...
29+
30+
@property
31+
def submitted_events(self) -> list[SyclEvent]: ...
32+
33+
def wait(self) -> None: ...
34+
35+
def __copy__(self) -> "OrderManagerProtocol": ...
36+
37+
1138
class _SequentialOrderManager:
1239
"""
1340
Class to orchestrate default sequential order
@@ -67,13 +94,78 @@ def __copy__(self):
6794
return res
6895

6996

97+
def _as_event_list(ev):
98+
if isinstance(ev, (list, tuple)):
99+
return list(ev)
100+
return [ev]
101+
102+
103+
_use_last_event = SyclQueue.is_get_last_event_available()
104+
105+
106+
class _InOrderManager:
107+
"""
108+
Order manager for an in-order queue. The queue orders its tasks, so only
109+
the most recently added events are kept.
110+
111+
``submitted_events`` is the event of the last command submitted to the
112+
queue if :meth:`dpctl.SyclQueue.get_last_event` is available, and the
113+
most recently added computation events otherwise. ``wait`` waits on the
114+
queue.
115+
"""
116+
117+
def __init__(self, q: SyclQueue):
118+
self._queue = q
119+
self._host_task_evs = []
120+
self._comp_evs = []
121+
122+
def __del__(self):
123+
if sys.is_finalizing():
124+
return
125+
self._queue.wait()
126+
127+
def add_event_pair(self, host_task_ev, comp_ev):
128+
self._host_task_evs = _as_event_list(host_task_ev)
129+
self._comp_evs = _as_event_list(comp_ev)
130+
131+
@property
132+
def num_host_task_events(self):
133+
return len(self._host_task_evs)
134+
135+
@property
136+
def num_submitted_events(self):
137+
return len(self.submitted_events)
138+
139+
@property
140+
def host_task_events(self):
141+
return list(self._host_task_evs)
142+
143+
@property
144+
def submitted_events(self):
145+
if _use_last_event:
146+
ev = self._queue.get_last_event()
147+
if ev is not None:
148+
return [ev]
149+
return list(self._comp_evs)
150+
151+
def wait(self):
152+
self._queue.wait()
153+
154+
def __copy__(self):
155+
res = _InOrderManager(self._queue)
156+
res._host_task_evs = list(self._host_task_evs)
157+
res._comp_evs = list(self._comp_evs)
158+
return res
159+
160+
70161
class SyclQueueToOrderManagerMap:
71162
"""
72163
Utility class used to ensure sequential ordering of offloaded tasks
73164
when passed to order manager.
74165
75166
Maintains a thread-local dictionary mapping SyclQueue instances to
76-
_SequentialOrderManager instances.
167+
order managers: _InOrderManager for in-order queues,
168+
_SequentialOrderManager otherwise.
77169
"""
78170

79171
def __init__(self):
@@ -88,15 +180,23 @@ def _get_map(self):
88180
try:
89181
return self._tls.order_manager_map
90182
except AttributeError:
91-
m = defaultdict(_SequentialOrderManager)
183+
m = {}
92184
self._tls.order_manager_map = m
93185
return m
94186

95-
def __getitem__(self, q: SyclQueue) -> _SequentialOrderManager:
187+
def __getitem__(self, q: SyclQueue) -> OrderManagerProtocol:
96188
"""Get order manager for given SyclQueue"""
97189
if not isinstance(q, SyclQueue):
98190
raise TypeError(f"Expected `dpctl.SyclQueue`, got {type(q)}")
99-
return self._get_map()[q]
191+
_local = self._get_map()
192+
om = _local.get(q)
193+
if om is None:
194+
if q.is_in_order:
195+
om = _InOrderManager(q)
196+
else:
197+
om = _SequentialOrderManager()
198+
_local[q] = om
199+
return om
100200

101201
def clear(self):
102202
"""Clear content of internal dictionary"""

0 commit comments

Comments
 (0)