ponkan-python 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ponkan_python-0.1.0.dist-info/METADATA +157 -0
- ponkan_python-0.1.0.dist-info/RECORD +39 -0
- ponkan_python-0.1.0.dist-info/WHEEL +4 -0
- ponkan_python-0.1.0.dist-info/entry_points.txt +5 -0
- ponkan_python-0.1.0.dist-info/licenses/LICENSE +22 -0
- ponkan_python-0.1.0.dist-info/licenses/NOTICE.md +14 -0
- py3dscapture/__init__.py +36 -0
- py3dscapture/artifacts.py +66 -0
- py3dscapture/capture.py +599 -0
- py3dscapture/devices/__init__.py +1 -0
- py3dscapture/devices/n3dsxl_ftd3.py +238 -0
- py3dscapture/errors.py +120 -0
- py3dscapture/hardware_gate.py +143 -0
- py3dscapture/image/__init__.py +1 -0
- py3dscapture/image/frame.py +166 -0
- py3dscapture/protocol/__init__.py +1 -0
- py3dscapture/protocol/layout_3ds.py +60 -0
- py3dscapture/protocol/n3dsxl.py +249 -0
- py3dscapture/protocol/sizes.py +128 -0
- py3dscapture/py.typed +1 -0
- py3dscapture/streaming/__init__.py +1 -0
- py3dscapture/streaming/buffers.py +156 -0
- py3dscapture/streaming/engine.py +285 -0
- py3dscapture/streaming/policies.py +157 -0
- py3dscapture/streaming/stats.py +254 -0
- py3dscapture/tools/__init__.py +1 -0
- py3dscapture/tools/capture_raw.py +44 -0
- py3dscapture/tools/list_devices.py +68 -0
- py3dscapture/tools/raw_to_png.py +251 -0
- py3dscapture/tools/stream_n3dsxl.py +152 -0
- py3dscapture/transport/__init__.py +1 -0
- py3dscapture/transport/d3xx_backend.py +850 -0
- py3dscapture/transport/d3xx_native.py +268 -0
- py3dscapture/transport/d3xx_native_streaming.py +306 -0
- py3dscapture/transport/d3xx_streaming.py +202 -0
- py3dscapture/transport/ftd3_backend.py +275 -0
- py3dscapture/transport/ftd3_pipe.py +387 -0
- py3dscapture/transport/libusb_async.py +134 -0
- py3dscapture/transport/libusb_backend.py +357 -0
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
"""Streaming engine built around async raw completions."""
|
|
2
|
+
|
|
3
|
+
import asyncio
|
|
4
|
+
import queue
|
|
5
|
+
import time
|
|
6
|
+
from collections.abc import AsyncIterator, Callable, Iterator
|
|
7
|
+
|
|
8
|
+
from py3dscapture.errors import DecodeError
|
|
9
|
+
from py3dscapture.image.frame import CaptureFrame
|
|
10
|
+
from py3dscapture.protocol.layout_3ds import decode_rgb8_2d
|
|
11
|
+
from py3dscapture.protocol.sizes import capture_size, video_size
|
|
12
|
+
from py3dscapture.streaming.buffers import BufferPool, RawFrameResult, RawFrameSlot
|
|
13
|
+
from py3dscapture.streaming.policies import BoundedFrameQueue, DropPolicy, put_frame_with_policy
|
|
14
|
+
from py3dscapture.streaming.stats import StreamStats, StreamTimingCollector, TimingSummary
|
|
15
|
+
from py3dscapture.transport.libusb_async import AsyncTransferBackend
|
|
16
|
+
|
|
17
|
+
Decoder = Callable[[bytes], CaptureFrame]
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class StreamingEngine:
|
|
21
|
+
"""Coordinate raw async acquisition, decode handoff, and frame delivery.
|
|
22
|
+
|
|
23
|
+
Transfer callbacks only enqueue raw completion metadata. Decoding and
|
|
24
|
+
decoded-frame queue policy are handled by ``process_completed`` outside the
|
|
25
|
+
callback path.
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
def __init__(
|
|
29
|
+
self,
|
|
30
|
+
backend: AsyncTransferBackend,
|
|
31
|
+
*,
|
|
32
|
+
raw_slots: int = 2,
|
|
33
|
+
raw_slot_size: int | None = None,
|
|
34
|
+
output_queue_size: int = 2,
|
|
35
|
+
drop_policy: DropPolicy = "drop_oldest",
|
|
36
|
+
decoder: Decoder | None = None,
|
|
37
|
+
collect_timing: bool = False,
|
|
38
|
+
) -> None:
|
|
39
|
+
"""Create a streaming engine over an async transfer backend.
|
|
40
|
+
|
|
41
|
+
Args:
|
|
42
|
+
backend: Async transfer backend that fills raw slots and invokes a
|
|
43
|
+
completion callback.
|
|
44
|
+
raw_slots: Number of in-flight raw transfer buffers.
|
|
45
|
+
raw_slot_size: Byte size for each raw slot. Defaults to the 2D
|
|
46
|
+
capture size.
|
|
47
|
+
output_queue_size: Number of decoded frames retained for consumers.
|
|
48
|
+
drop_policy: Overflow behavior for decoded-frame delivery.
|
|
49
|
+
decoder: Optional raw-video decoder used for tests or alternate
|
|
50
|
+
decode strategies.
|
|
51
|
+
collect_timing: Collect per-transfer timing samples and expose a
|
|
52
|
+
summary through ``timing_summary`` when true.
|
|
53
|
+
|
|
54
|
+
Raises:
|
|
55
|
+
ValueError: Slot or queue sizes are not positive.
|
|
56
|
+
"""
|
|
57
|
+
self.raw_slot_size = raw_slot_size or capture_size(mode_3d=False)
|
|
58
|
+
self.buffer_pool = BufferPool(raw_slots=raw_slots, raw_slot_size=self.raw_slot_size)
|
|
59
|
+
self.backend = backend
|
|
60
|
+
self.output_queue = BoundedFrameQueue(output_queue_size)
|
|
61
|
+
self.drop_policy = drop_policy
|
|
62
|
+
self._decoder = decoder or _decode_2d_default
|
|
63
|
+
self._stats = StreamStats()
|
|
64
|
+
self._completion_queue: queue.Queue[RawFrameResult] = queue.Queue(maxsize=raw_slots)
|
|
65
|
+
self._running = False
|
|
66
|
+
self._next_sequence = 0
|
|
67
|
+
self._timing = StreamTimingCollector() if collect_timing else None
|
|
68
|
+
|
|
69
|
+
def start(self) -> None:
|
|
70
|
+
"""Submit initial raw-slot async reads.
|
|
71
|
+
|
|
72
|
+
The method is idempotent while already running. Each slot is checked out
|
|
73
|
+
and submitted once.
|
|
74
|
+
"""
|
|
75
|
+
if self._running:
|
|
76
|
+
return
|
|
77
|
+
self._running = True
|
|
78
|
+
for slot in self.buffer_pool.slots:
|
|
79
|
+
self._submit_slot(self.buffer_pool.checkout(slot.index))
|
|
80
|
+
|
|
81
|
+
def stop(self, timeout: float | None = None) -> None:
|
|
82
|
+
"""Cancel, drain, release backend resources, and release raw slots.
|
|
83
|
+
|
|
84
|
+
Args:
|
|
85
|
+
timeout: Reserved for future bounded shutdown support. Current
|
|
86
|
+
shutdown drains using the backend's own semantics.
|
|
87
|
+
"""
|
|
88
|
+
_ = timeout
|
|
89
|
+
if not self._running and self.buffer_pool.in_use_count() == 0:
|
|
90
|
+
return
|
|
91
|
+
self._running = False
|
|
92
|
+
self._stats.cancelled += self.buffer_pool.in_use_count()
|
|
93
|
+
self.backend.cancel_all()
|
|
94
|
+
self.backend.drain()
|
|
95
|
+
for slot in self.buffer_pool.slots:
|
|
96
|
+
if slot.in_use:
|
|
97
|
+
self.buffer_pool.release(slot.index)
|
|
98
|
+
self.backend.release()
|
|
99
|
+
|
|
100
|
+
def process_completed(self, *, limit: int | None = None) -> int:
|
|
101
|
+
"""Decode completed raw results outside the callback.
|
|
102
|
+
|
|
103
|
+
Args:
|
|
104
|
+
limit: Maximum number of completions to process, or ``None`` to
|
|
105
|
+
process until the completion queue is empty.
|
|
106
|
+
|
|
107
|
+
Returns:
|
|
108
|
+
Number of raw completions consumed from the completion queue.
|
|
109
|
+
"""
|
|
110
|
+
processed = 0
|
|
111
|
+
while limit is None or processed < limit:
|
|
112
|
+
try:
|
|
113
|
+
result = self._completion_queue.get_nowait()
|
|
114
|
+
except queue.Empty:
|
|
115
|
+
break
|
|
116
|
+
processed += 1
|
|
117
|
+
self._process_result(result)
|
|
118
|
+
return processed
|
|
119
|
+
|
|
120
|
+
def frames(self, *, max_frames: int | None = None) -> Iterator[CaptureFrame]:
|
|
121
|
+
"""Yield decoded frames currently available to consumers.
|
|
122
|
+
|
|
123
|
+
Args:
|
|
124
|
+
max_frames: Maximum number of frames to yield, or ``None`` to drain
|
|
125
|
+
all currently queued frames.
|
|
126
|
+
|
|
127
|
+
Yields:
|
|
128
|
+
Decoded frames from the output queue in delivery order.
|
|
129
|
+
"""
|
|
130
|
+
delivered = 0
|
|
131
|
+
while max_frames is None or delivered < max_frames:
|
|
132
|
+
try:
|
|
133
|
+
frame = self.output_queue.get_nowait()
|
|
134
|
+
except IndexError:
|
|
135
|
+
break
|
|
136
|
+
delivered += 1
|
|
137
|
+
yield frame
|
|
138
|
+
|
|
139
|
+
async def frames_async(self, *, max_frames: int | None = None) -> AsyncIterator[CaptureFrame]:
|
|
140
|
+
"""Yield decoded frames through an async iterator.
|
|
141
|
+
|
|
142
|
+
Args:
|
|
143
|
+
max_frames: Maximum number of frames to yield, or ``None`` to drain
|
|
144
|
+
all currently queued frames.
|
|
145
|
+
|
|
146
|
+
Yields:
|
|
147
|
+
Decoded frames from the output queue in delivery order.
|
|
148
|
+
"""
|
|
149
|
+
delivered = 0
|
|
150
|
+
while max_frames is None or delivered < max_frames:
|
|
151
|
+
frame = next(self.frames(max_frames=1), None)
|
|
152
|
+
if frame is None:
|
|
153
|
+
break
|
|
154
|
+
delivered += 1
|
|
155
|
+
yield frame
|
|
156
|
+
await asyncio.sleep(0)
|
|
157
|
+
|
|
158
|
+
def stats(self) -> StreamStats:
|
|
159
|
+
"""Return a snapshot of current stream counters.
|
|
160
|
+
|
|
161
|
+
Returns:
|
|
162
|
+
Independent counter snapshot for reporting.
|
|
163
|
+
"""
|
|
164
|
+
return self._stats.snapshot()
|
|
165
|
+
|
|
166
|
+
def timing_summary(self) -> TimingSummary | None:
|
|
167
|
+
"""Return opt-in timing summary for completed samples.
|
|
168
|
+
|
|
169
|
+
Returns:
|
|
170
|
+
Timing summary when collection is enabled, otherwise ``None``.
|
|
171
|
+
"""
|
|
172
|
+
if self._timing is None:
|
|
173
|
+
return None
|
|
174
|
+
return self._timing.summary()
|
|
175
|
+
|
|
176
|
+
def _submit_slot(self, slot: RawFrameSlot) -> None:
|
|
177
|
+
slot.submitted_ns = time.monotonic_ns()
|
|
178
|
+
slot.backend_started_ns = None
|
|
179
|
+
slot.completed_ns = None
|
|
180
|
+
slot.transferred = 0
|
|
181
|
+
slot.sequence = self._next_sequence
|
|
182
|
+
self._next_sequence += 1
|
|
183
|
+
self.backend.submit_read(
|
|
184
|
+
slot,
|
|
185
|
+
length=self.raw_slot_size,
|
|
186
|
+
callback=self._on_transfer_complete,
|
|
187
|
+
)
|
|
188
|
+
self._stats.submitted += 1
|
|
189
|
+
|
|
190
|
+
def _on_transfer_complete(
|
|
191
|
+
self,
|
|
192
|
+
slot_index: int,
|
|
193
|
+
transferred: int,
|
|
194
|
+
status: int,
|
|
195
|
+
completed_ns: int,
|
|
196
|
+
) -> None:
|
|
197
|
+
slot = self.buffer_pool.get(slot_index)
|
|
198
|
+
slot.completed_ns = completed_ns
|
|
199
|
+
slot.transferred = transferred
|
|
200
|
+
submitted_ns = slot.submitted_ns
|
|
201
|
+
backend_started_ns = slot.backend_started_ns
|
|
202
|
+
sequence = 0 if slot.sequence is None else slot.sequence
|
|
203
|
+
result = RawFrameResult(
|
|
204
|
+
slot_index=slot_index,
|
|
205
|
+
view=slot.view,
|
|
206
|
+
transferred=transferred,
|
|
207
|
+
status=status,
|
|
208
|
+
submitted_ns=submitted_ns,
|
|
209
|
+
backend_started_ns=backend_started_ns,
|
|
210
|
+
completed_ns=completed_ns,
|
|
211
|
+
sequence=sequence,
|
|
212
|
+
)
|
|
213
|
+
if self._timing is not None:
|
|
214
|
+
self._timing.record_completion_interval(completed_ns)
|
|
215
|
+
if submitted_ns is not None:
|
|
216
|
+
self._timing.record_ns_delta(
|
|
217
|
+
"submit_to_complete_ms",
|
|
218
|
+
completed_ns - submitted_ns,
|
|
219
|
+
)
|
|
220
|
+
if backend_started_ns is not None:
|
|
221
|
+
self._timing.record_ns_delta(
|
|
222
|
+
"backend_queue_wait_ms",
|
|
223
|
+
backend_started_ns - submitted_ns,
|
|
224
|
+
)
|
|
225
|
+
if backend_started_ns is not None:
|
|
226
|
+
self._timing.record_ns_delta(
|
|
227
|
+
"read_duration_ms",
|
|
228
|
+
completed_ns - backend_started_ns,
|
|
229
|
+
)
|
|
230
|
+
try:
|
|
231
|
+
self._completion_queue.put_nowait(result)
|
|
232
|
+
except queue.Full:
|
|
233
|
+
self._stats.dropped_raw += 1
|
|
234
|
+
self.buffer_pool.release(slot_index)
|
|
235
|
+
else:
|
|
236
|
+
self._stats.completed += 1
|
|
237
|
+
|
|
238
|
+
def _process_result(self, result: RawFrameResult) -> None:
|
|
239
|
+
if self._timing is not None:
|
|
240
|
+
process_started_ns = time.monotonic_ns()
|
|
241
|
+
self._timing.record_ns_delta(
|
|
242
|
+
"completion_queue_wait_ms",
|
|
243
|
+
process_started_ns - result.completed_ns,
|
|
244
|
+
)
|
|
245
|
+
try:
|
|
246
|
+
if result.status != 0:
|
|
247
|
+
self._stats.usb_errors += 1
|
|
248
|
+
return
|
|
249
|
+
expected_video_size = video_size(mode_3d=False)
|
|
250
|
+
if result.transferred < expected_video_size:
|
|
251
|
+
self._stats.dropped_raw += 1
|
|
252
|
+
return
|
|
253
|
+
raw_video = bytes(result.view[:expected_video_size])
|
|
254
|
+
if self._timing is None:
|
|
255
|
+
frame = self._decoder(raw_video)
|
|
256
|
+
else:
|
|
257
|
+
decode_started_ns = time.monotonic_ns()
|
|
258
|
+
try:
|
|
259
|
+
frame = self._decoder(raw_video)
|
|
260
|
+
finally:
|
|
261
|
+
self._timing.record_ns_delta(
|
|
262
|
+
"decode_ms",
|
|
263
|
+
time.monotonic_ns() - decode_started_ns,
|
|
264
|
+
)
|
|
265
|
+
frame.sequence = result.sequence
|
|
266
|
+
frame.timestamp_ns = result.completed_ns
|
|
267
|
+
self._stats.decoded += 1
|
|
268
|
+
put_frame_with_policy(self.output_queue, frame, self.drop_policy, self._stats)
|
|
269
|
+
except DecodeError as exc:
|
|
270
|
+
self._stats.decode_errors += 1
|
|
271
|
+
self._stats.last_error = exc.__class__.__name__
|
|
272
|
+
finally:
|
|
273
|
+
self.buffer_pool.release(result.slot_index)
|
|
274
|
+
if self._running:
|
|
275
|
+
if self._timing is not None:
|
|
276
|
+
resubmit_started_ns = time.monotonic_ns()
|
|
277
|
+
self._timing.record_ns_delta(
|
|
278
|
+
"callback_to_resubmit_ms",
|
|
279
|
+
resubmit_started_ns - result.completed_ns,
|
|
280
|
+
)
|
|
281
|
+
self._submit_slot(self.buffer_pool.checkout(result.slot_index))
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
def _decode_2d_default(raw_video: bytes) -> CaptureFrame:
|
|
285
|
+
return decode_rgb8_2d(raw_video)
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
"""Bounded frame delivery queues and drop policies."""
|
|
2
|
+
|
|
3
|
+
from collections import deque
|
|
4
|
+
from collections.abc import Iterator
|
|
5
|
+
from typing import Literal
|
|
6
|
+
|
|
7
|
+
from py3dscapture.image.frame import CaptureFrame
|
|
8
|
+
from py3dscapture.streaming.stats import StreamStats
|
|
9
|
+
|
|
10
|
+
DropPolicy = Literal["drop_oldest", "drop_newest", "block"]
|
|
11
|
+
CopyPolicy = Literal["copy_decoded_frame_before_release_raw_slot", "zero_copy_experimental"]
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class BoundedFrameQueue:
|
|
15
|
+
"""Small FIFO queue for decoded frames.
|
|
16
|
+
|
|
17
|
+
The queue is intentionally simple and non-blocking for callback-adjacent
|
|
18
|
+
paths. Blocking behavior is modeled explicitly by ``put_frame_with_policy``.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
def __init__(self, max_size: int) -> None:
|
|
22
|
+
"""Create a bounded queue.
|
|
23
|
+
|
|
24
|
+
Args:
|
|
25
|
+
max_size: Maximum number of decoded frames retained.
|
|
26
|
+
|
|
27
|
+
Raises:
|
|
28
|
+
ValueError: ``max_size`` is not positive.
|
|
29
|
+
"""
|
|
30
|
+
if max_size <= 0:
|
|
31
|
+
raise ValueError
|
|
32
|
+
self._max_size = max_size
|
|
33
|
+
self._items: deque[CaptureFrame] = deque()
|
|
34
|
+
|
|
35
|
+
@property
|
|
36
|
+
def max_size(self) -> int:
|
|
37
|
+
"""Return the queue capacity.
|
|
38
|
+
|
|
39
|
+
Returns:
|
|
40
|
+
Maximum number of frames retained by the queue.
|
|
41
|
+
"""
|
|
42
|
+
return self._max_size
|
|
43
|
+
|
|
44
|
+
def __len__(self) -> int:
|
|
45
|
+
"""Return queued frame count.
|
|
46
|
+
|
|
47
|
+
Returns:
|
|
48
|
+
Number of frames currently queued.
|
|
49
|
+
"""
|
|
50
|
+
return len(self._items)
|
|
51
|
+
|
|
52
|
+
def __iter__(self) -> Iterator[CaptureFrame]:
|
|
53
|
+
"""Iterate queued frames from oldest to newest.
|
|
54
|
+
|
|
55
|
+
Yields:
|
|
56
|
+
Snapshot of queued frames in delivery order.
|
|
57
|
+
"""
|
|
58
|
+
return iter(tuple(self._items))
|
|
59
|
+
|
|
60
|
+
def full(self) -> bool:
|
|
61
|
+
"""Return whether no more frames can be enqueued.
|
|
62
|
+
|
|
63
|
+
Returns:
|
|
64
|
+
True when queue length is greater than or equal to capacity.
|
|
65
|
+
"""
|
|
66
|
+
return len(self._items) >= self._max_size
|
|
67
|
+
|
|
68
|
+
def put_nowait(self, frame: CaptureFrame) -> None:
|
|
69
|
+
"""Append a frame if capacity remains.
|
|
70
|
+
|
|
71
|
+
Args:
|
|
72
|
+
frame: Decoded frame to append.
|
|
73
|
+
|
|
74
|
+
Raises:
|
|
75
|
+
OverflowError: The queue is already full.
|
|
76
|
+
"""
|
|
77
|
+
if self.full():
|
|
78
|
+
raise OverflowError
|
|
79
|
+
self._items.append(frame)
|
|
80
|
+
|
|
81
|
+
def put_blocking(self, frame: CaptureFrame) -> None:
|
|
82
|
+
"""Append a frame for non-callback contexts.
|
|
83
|
+
|
|
84
|
+
Args:
|
|
85
|
+
frame: Decoded frame to append even when the queue is full.
|
|
86
|
+
"""
|
|
87
|
+
self._items.append(frame)
|
|
88
|
+
|
|
89
|
+
def get_nowait(self) -> CaptureFrame:
|
|
90
|
+
"""Pop the oldest frame.
|
|
91
|
+
|
|
92
|
+
Returns:
|
|
93
|
+
Oldest queued frame.
|
|
94
|
+
|
|
95
|
+
Raises:
|
|
96
|
+
IndexError: The queue is empty.
|
|
97
|
+
"""
|
|
98
|
+
return self._items.popleft()
|
|
99
|
+
|
|
100
|
+
def drop_oldest(self) -> CaptureFrame:
|
|
101
|
+
"""Drop and return the oldest frame.
|
|
102
|
+
|
|
103
|
+
Returns:
|
|
104
|
+
The frame removed from the queue.
|
|
105
|
+
|
|
106
|
+
Raises:
|
|
107
|
+
IndexError: The queue is empty.
|
|
108
|
+
"""
|
|
109
|
+
return self._items.popleft()
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def put_frame_with_policy(
|
|
113
|
+
queue: BoundedFrameQueue,
|
|
114
|
+
frame: CaptureFrame,
|
|
115
|
+
policy: DropPolicy,
|
|
116
|
+
stats: StreamStats,
|
|
117
|
+
*,
|
|
118
|
+
callback_thread: bool = False,
|
|
119
|
+
) -> bool:
|
|
120
|
+
"""Put one decoded frame using a bounded-queue policy.
|
|
121
|
+
|
|
122
|
+
Args:
|
|
123
|
+
queue: Destination queue.
|
|
124
|
+
frame: Decoded frame to enqueue or drop.
|
|
125
|
+
policy: Overflow behavior when the queue is full.
|
|
126
|
+
stats: Mutable counters updated with delivery or drop results.
|
|
127
|
+
callback_thread: Whether the caller is running on a callback thread.
|
|
128
|
+
|
|
129
|
+
Returns:
|
|
130
|
+
True when the frame was retained for delivery.
|
|
131
|
+
|
|
132
|
+
Raises:
|
|
133
|
+
RuntimeError: ``policy`` is ``"block"`` on a callback thread.
|
|
134
|
+
ValueError: ``policy`` is not one of the supported literal values.
|
|
135
|
+
"""
|
|
136
|
+
if policy == "block" and callback_thread:
|
|
137
|
+
raise RuntimeError
|
|
138
|
+
|
|
139
|
+
if not queue.full():
|
|
140
|
+
queue.put_nowait(frame)
|
|
141
|
+
stats.delivered += 1
|
|
142
|
+
return True
|
|
143
|
+
|
|
144
|
+
if policy == "drop_newest":
|
|
145
|
+
stats.dropped_decoded += 1
|
|
146
|
+
return False
|
|
147
|
+
if policy == "drop_oldest":
|
|
148
|
+
queue.drop_oldest()
|
|
149
|
+
stats.dropped_decoded += 1
|
|
150
|
+
queue.put_nowait(frame)
|
|
151
|
+
stats.delivered += 1
|
|
152
|
+
return True
|
|
153
|
+
if policy == "block":
|
|
154
|
+
queue.put_blocking(frame)
|
|
155
|
+
stats.delivered += 1
|
|
156
|
+
return True
|
|
157
|
+
raise ValueError
|
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
"""Streaming counters."""
|
|
2
|
+
|
|
3
|
+
from dataclasses import asdict, dataclass, field
|
|
4
|
+
from threading import Lock
|
|
5
|
+
from typing import Literal
|
|
6
|
+
|
|
7
|
+
TIMING_METRIC_NAMES = (
|
|
8
|
+
"backend_queue_wait_ms",
|
|
9
|
+
"read_duration_ms",
|
|
10
|
+
"submit_to_complete_ms",
|
|
11
|
+
"completion_interval_ms",
|
|
12
|
+
"completion_queue_wait_ms",
|
|
13
|
+
"decode_ms",
|
|
14
|
+
"callback_to_resubmit_ms",
|
|
15
|
+
)
|
|
16
|
+
|
|
17
|
+
TimingMetricSummary = dict[str, float | int]
|
|
18
|
+
TimingSummary = dict[str, TimingMetricSummary]
|
|
19
|
+
StreamingBackendKind = Literal["libusb", "d3xx", "d3xx-native"]
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
@dataclass(slots=True)
|
|
23
|
+
class StreamTimingCollector:
|
|
24
|
+
"""Collect opt-in per-transfer timing samples for streaming reports.
|
|
25
|
+
|
|
26
|
+
The collector stores all samples in memory and summarizes them on demand.
|
|
27
|
+
This is intended for bounded smoke runs, not indefinite production
|
|
28
|
+
telemetry.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
_samples: dict[str, list[float]] = field(
|
|
32
|
+
default_factory=lambda: {name: [] for name in TIMING_METRIC_NAMES}
|
|
33
|
+
)
|
|
34
|
+
_last_completed_ns: int | None = None
|
|
35
|
+
_lock: Lock = field(default_factory=Lock)
|
|
36
|
+
|
|
37
|
+
def record_ns_delta(self, metric: str, delta_ns: int) -> None:
|
|
38
|
+
"""Record one non-negative nanosecond delta as milliseconds.
|
|
39
|
+
|
|
40
|
+
Args:
|
|
41
|
+
metric: Metric name from ``TIMING_METRIC_NAMES``.
|
|
42
|
+
delta_ns: Duration in nanoseconds.
|
|
43
|
+
"""
|
|
44
|
+
if delta_ns < 0:
|
|
45
|
+
return
|
|
46
|
+
with self._lock:
|
|
47
|
+
self._samples[metric].append(delta_ns / 1_000_000)
|
|
48
|
+
|
|
49
|
+
def record_completion_interval(self, completed_ns: int) -> None:
|
|
50
|
+
"""Record interval from the previous backend completion.
|
|
51
|
+
|
|
52
|
+
Args:
|
|
53
|
+
completed_ns: Monotonic timestamp for the current completion.
|
|
54
|
+
"""
|
|
55
|
+
with self._lock:
|
|
56
|
+
if self._last_completed_ns is not None:
|
|
57
|
+
delta_ns = completed_ns - self._last_completed_ns
|
|
58
|
+
if delta_ns >= 0:
|
|
59
|
+
self._samples["completion_interval_ms"].append(delta_ns / 1_000_000)
|
|
60
|
+
self._last_completed_ns = completed_ns
|
|
61
|
+
|
|
62
|
+
def summary(self) -> TimingSummary:
|
|
63
|
+
"""Return count/min/percentile/max/mean summaries by metric.
|
|
64
|
+
|
|
65
|
+
Returns:
|
|
66
|
+
JSON-serializable timing summary. Metrics without samples are
|
|
67
|
+
omitted.
|
|
68
|
+
"""
|
|
69
|
+
with self._lock:
|
|
70
|
+
samples = {name: tuple(values) for name, values in self._samples.items()}
|
|
71
|
+
return {name: _summarize_metric(values) for name, values in samples.items() if values}
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
@dataclass(slots=True)
|
|
75
|
+
class StreamStats:
|
|
76
|
+
"""Mutable streaming counters.
|
|
77
|
+
|
|
78
|
+
Attributes:
|
|
79
|
+
submitted: Raw reads submitted to the backend.
|
|
80
|
+
completed: Backend completions received.
|
|
81
|
+
decoded: Raw completions decoded into frames.
|
|
82
|
+
delivered: Decoded frames retained for consumers.
|
|
83
|
+
dropped_raw: Raw completions dropped before decode.
|
|
84
|
+
dropped_decoded: Decoded frames dropped by queue policy.
|
|
85
|
+
usb_errors: Backend completion errors.
|
|
86
|
+
decode_errors: Decoder failures.
|
|
87
|
+
cancelled: In-flight transfers cancelled during shutdown.
|
|
88
|
+
last_error: Optional class name for the last decode error.
|
|
89
|
+
"""
|
|
90
|
+
|
|
91
|
+
submitted: int = 0
|
|
92
|
+
completed: int = 0
|
|
93
|
+
decoded: int = 0
|
|
94
|
+
delivered: int = 0
|
|
95
|
+
dropped_raw: int = 0
|
|
96
|
+
dropped_decoded: int = 0
|
|
97
|
+
usb_errors: int = 0
|
|
98
|
+
decode_errors: int = 0
|
|
99
|
+
cancelled: int = 0
|
|
100
|
+
last_error: str | None = None
|
|
101
|
+
|
|
102
|
+
def snapshot(self) -> "StreamStats":
|
|
103
|
+
"""Return a copy suitable for reporting.
|
|
104
|
+
|
|
105
|
+
Returns:
|
|
106
|
+
Independent counter object representing the current values.
|
|
107
|
+
"""
|
|
108
|
+
return StreamStats(**asdict(self))
|
|
109
|
+
|
|
110
|
+
def to_dict(self) -> dict[str, int | str | None]:
|
|
111
|
+
"""Return JSON-serializable counters.
|
|
112
|
+
|
|
113
|
+
Returns:
|
|
114
|
+
Dictionary form of all stream counters.
|
|
115
|
+
"""
|
|
116
|
+
return asdict(self)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
@dataclass(frozen=True, slots=True)
|
|
120
|
+
class PerformanceStats:
|
|
121
|
+
"""JSON-serializable performance smoke report.
|
|
122
|
+
|
|
123
|
+
Attributes mirror the performance smoke artifact schema. Time values are
|
|
124
|
+
seconds, and ``delivered_fps`` is calculated from delivered frame count and
|
|
125
|
+
requested duration.
|
|
126
|
+
"""
|
|
127
|
+
|
|
128
|
+
model: Literal["new_3ds_xl"]
|
|
129
|
+
product_string: str | None
|
|
130
|
+
product_string_status: Literal["accepted", "unreadable"]
|
|
131
|
+
backend_kind: StreamingBackendKind
|
|
132
|
+
driver_service: str | None
|
|
133
|
+
mode_3d: bool
|
|
134
|
+
duration_seconds: float
|
|
135
|
+
raw_slots: int
|
|
136
|
+
output_queue_size: int
|
|
137
|
+
drop_policy: str
|
|
138
|
+
submitted: int
|
|
139
|
+
completed: int
|
|
140
|
+
decoded: int
|
|
141
|
+
delivered: int
|
|
142
|
+
dropped_raw: int
|
|
143
|
+
dropped_decoded: int
|
|
144
|
+
usb_errors: int
|
|
145
|
+
decode_errors: int
|
|
146
|
+
cancelled: int
|
|
147
|
+
last_error: str | None
|
|
148
|
+
shutdown_seconds: float
|
|
149
|
+
delivered_fps: float
|
|
150
|
+
timing: TimingSummary | None = None
|
|
151
|
+
|
|
152
|
+
@classmethod
|
|
153
|
+
def from_stream_stats(
|
|
154
|
+
cls,
|
|
155
|
+
stats: StreamStats,
|
|
156
|
+
*,
|
|
157
|
+
product_string: str | None,
|
|
158
|
+
product_string_status: Literal["accepted", "unreadable"],
|
|
159
|
+
mode_3d: bool,
|
|
160
|
+
duration_seconds: float,
|
|
161
|
+
raw_slots: int,
|
|
162
|
+
output_queue_size: int,
|
|
163
|
+
drop_policy: str,
|
|
164
|
+
shutdown_seconds: float,
|
|
165
|
+
backend_kind: StreamingBackendKind = "libusb",
|
|
166
|
+
driver_service: str | None = None,
|
|
167
|
+
timing: TimingSummary | None = None,
|
|
168
|
+
) -> "PerformanceStats":
|
|
169
|
+
"""Build a performance report from streaming counters.
|
|
170
|
+
|
|
171
|
+
Args:
|
|
172
|
+
stats: Streaming counters collected during the smoke run.
|
|
173
|
+
product_string: USB product string when readable.
|
|
174
|
+
product_string_status: Whether the product string was accepted or
|
|
175
|
+
unreadable.
|
|
176
|
+
mode_3d: Capture mode used by the smoke run.
|
|
177
|
+
duration_seconds: Requested smoke duration in seconds.
|
|
178
|
+
raw_slots: Raw transfer slot count.
|
|
179
|
+
output_queue_size: Decoded frame queue capacity.
|
|
180
|
+
drop_policy: Decoded frame overflow policy.
|
|
181
|
+
shutdown_seconds: Time spent stopping the engine.
|
|
182
|
+
backend_kind: Transport backend used for the run.
|
|
183
|
+
driver_service: Optional Windows driver service observed.
|
|
184
|
+
timing: Optional timing summary collected by ``StreamingEngine``.
|
|
185
|
+
|
|
186
|
+
Returns:
|
|
187
|
+
Frozen JSON-serializable performance report.
|
|
188
|
+
"""
|
|
189
|
+
delivered_fps = stats.delivered / duration_seconds if duration_seconds > 0 else 0.0
|
|
190
|
+
timing_copy = (
|
|
191
|
+
{metric: dict(summary) for metric, summary in timing.items()}
|
|
192
|
+
if timing is not None
|
|
193
|
+
else None
|
|
194
|
+
)
|
|
195
|
+
return cls(
|
|
196
|
+
model="new_3ds_xl",
|
|
197
|
+
product_string=product_string,
|
|
198
|
+
product_string_status=product_string_status,
|
|
199
|
+
backend_kind=backend_kind,
|
|
200
|
+
driver_service=driver_service,
|
|
201
|
+
mode_3d=mode_3d,
|
|
202
|
+
duration_seconds=duration_seconds,
|
|
203
|
+
raw_slots=raw_slots,
|
|
204
|
+
output_queue_size=output_queue_size,
|
|
205
|
+
drop_policy=drop_policy,
|
|
206
|
+
submitted=stats.submitted,
|
|
207
|
+
completed=stats.completed,
|
|
208
|
+
decoded=stats.decoded,
|
|
209
|
+
delivered=stats.delivered,
|
|
210
|
+
dropped_raw=stats.dropped_raw,
|
|
211
|
+
dropped_decoded=stats.dropped_decoded,
|
|
212
|
+
usb_errors=stats.usb_errors,
|
|
213
|
+
decode_errors=stats.decode_errors,
|
|
214
|
+
cancelled=stats.cancelled,
|
|
215
|
+
last_error=stats.last_error,
|
|
216
|
+
shutdown_seconds=shutdown_seconds,
|
|
217
|
+
delivered_fps=delivered_fps,
|
|
218
|
+
timing=timing_copy,
|
|
219
|
+
)
|
|
220
|
+
|
|
221
|
+
def to_dict(self) -> dict[str, object]:
|
|
222
|
+
"""Return JSON-serializable performance stats.
|
|
223
|
+
|
|
224
|
+
Returns:
|
|
225
|
+
Dictionary form suitable for JSON artifact output.
|
|
226
|
+
"""
|
|
227
|
+
payload = asdict(self)
|
|
228
|
+
if self.timing is None:
|
|
229
|
+
payload.pop("timing")
|
|
230
|
+
return payload
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
def _summarize_metric(values: tuple[float, ...]) -> TimingMetricSummary:
|
|
234
|
+
ordered = tuple(sorted(values))
|
|
235
|
+
count = len(ordered)
|
|
236
|
+
return {
|
|
237
|
+
"count": count,
|
|
238
|
+
"min": ordered[0],
|
|
239
|
+
"p50": _percentile(ordered, 0.50),
|
|
240
|
+
"p95": _percentile(ordered, 0.95),
|
|
241
|
+
"p99": _percentile(ordered, 0.99),
|
|
242
|
+
"max": ordered[-1],
|
|
243
|
+
"mean": sum(ordered) / count,
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
def _percentile(values: tuple[float, ...], percentile: float) -> float:
|
|
248
|
+
if len(values) == 1:
|
|
249
|
+
return values[0]
|
|
250
|
+
position = (len(values) - 1) * percentile
|
|
251
|
+
lower_index = int(position)
|
|
252
|
+
upper_index = min(lower_index + 1, len(values) - 1)
|
|
253
|
+
fraction = position - lower_index
|
|
254
|
+
return values[lower_index] + (values[upper_index] - values[lower_index]) * fraction
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Command line helpers."""
|