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.
Files changed (39) hide show
  1. ponkan_python-0.1.0.dist-info/METADATA +157 -0
  2. ponkan_python-0.1.0.dist-info/RECORD +39 -0
  3. ponkan_python-0.1.0.dist-info/WHEEL +4 -0
  4. ponkan_python-0.1.0.dist-info/entry_points.txt +5 -0
  5. ponkan_python-0.1.0.dist-info/licenses/LICENSE +22 -0
  6. ponkan_python-0.1.0.dist-info/licenses/NOTICE.md +14 -0
  7. py3dscapture/__init__.py +36 -0
  8. py3dscapture/artifacts.py +66 -0
  9. py3dscapture/capture.py +599 -0
  10. py3dscapture/devices/__init__.py +1 -0
  11. py3dscapture/devices/n3dsxl_ftd3.py +238 -0
  12. py3dscapture/errors.py +120 -0
  13. py3dscapture/hardware_gate.py +143 -0
  14. py3dscapture/image/__init__.py +1 -0
  15. py3dscapture/image/frame.py +166 -0
  16. py3dscapture/protocol/__init__.py +1 -0
  17. py3dscapture/protocol/layout_3ds.py +60 -0
  18. py3dscapture/protocol/n3dsxl.py +249 -0
  19. py3dscapture/protocol/sizes.py +128 -0
  20. py3dscapture/py.typed +1 -0
  21. py3dscapture/streaming/__init__.py +1 -0
  22. py3dscapture/streaming/buffers.py +156 -0
  23. py3dscapture/streaming/engine.py +285 -0
  24. py3dscapture/streaming/policies.py +157 -0
  25. py3dscapture/streaming/stats.py +254 -0
  26. py3dscapture/tools/__init__.py +1 -0
  27. py3dscapture/tools/capture_raw.py +44 -0
  28. py3dscapture/tools/list_devices.py +68 -0
  29. py3dscapture/tools/raw_to_png.py +251 -0
  30. py3dscapture/tools/stream_n3dsxl.py +152 -0
  31. py3dscapture/transport/__init__.py +1 -0
  32. py3dscapture/transport/d3xx_backend.py +850 -0
  33. py3dscapture/transport/d3xx_native.py +268 -0
  34. py3dscapture/transport/d3xx_native_streaming.py +306 -0
  35. py3dscapture/transport/d3xx_streaming.py +202 -0
  36. py3dscapture/transport/ftd3_backend.py +275 -0
  37. py3dscapture/transport/ftd3_pipe.py +387 -0
  38. py3dscapture/transport/libusb_async.py +134 -0
  39. py3dscapture/transport/libusb_backend.py +357 -0
@@ -0,0 +1,60 @@
1
+ """3DS RGB8 raw video layout decoders."""
2
+
3
+ import numpy as np
4
+
5
+ from py3dscapture.errors import DecodeError
6
+ from py3dscapture.image.frame import CaptureFrame
7
+ from py3dscapture.protocol.sizes import (
8
+ BOTTOM_WIDTH_3DS,
9
+ HEIGHT_3DS,
10
+ TOP_WIDTH_3DS,
11
+ video_size,
12
+ )
13
+
14
+ APPROVED_N3DSXL_2D_DECODER_ID = "ftd3_cc3dsfs_2d"
15
+
16
+
17
+ def decode_rgb8_2d(raw_video: bytes | memoryview) -> CaptureFrame:
18
+ """Decode 2D N3DSXL raw RGB8 bytes into top and bottom screens.
19
+
20
+ Args:
21
+ raw_video: Exact 2D RGB8 video region from an N3DSXL raw capture. The
22
+ input must not include audio, unused, or error-buffer bytes.
23
+
24
+ Returns:
25
+ A decoded RGB ``CaptureFrame`` with top and bottom screens populated.
26
+
27
+ Raises:
28
+ DecodeError: The input length does not match the 2D video payload size.
29
+ """
30
+ raw_bytes = bytes(raw_video)
31
+ if len(raw_bytes) != video_size(mode_3d=False):
32
+ raise DecodeError
33
+
34
+ stacked = np.frombuffer(raw_bytes, dtype=np.uint8).reshape(
35
+ (TOP_WIDTH_3DS + BOTTOM_WIDTH_3DS, HEIGHT_3DS, 3)
36
+ )
37
+ top_source, bottom_source = _split_ftd3_2d_source(stacked)
38
+ return CaptureFrame(
39
+ top=_transform_2d_source(top_source),
40
+ bottom=_transform_2d_source(bottom_source),
41
+ top_right=None,
42
+ timestamp_ns=None,
43
+ source_model="new_3ds_xl",
44
+ mode_3d=False,
45
+ colorspace="RGB",
46
+ )
47
+
48
+
49
+ def _split_ftd3_2d_source(source: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
50
+ width_delta = TOP_WIDTH_3DS - BOTTOM_WIDTH_3DS
51
+ top_source = np.empty((TOP_WIDTH_3DS, HEIGHT_3DS, 3), dtype=np.uint8)
52
+ bottom_source = np.empty((BOTTOM_WIDTH_3DS, HEIGHT_3DS, 3), dtype=np.uint8)
53
+ top_source[:width_delta] = source[:width_delta]
54
+ bottom_source[:] = source[width_delta::2]
55
+ top_source[width_delta:] = source[width_delta + 1 :: 2]
56
+ return top_source, bottom_source
57
+
58
+
59
+ def _transform_2d_source(source: np.ndarray) -> np.ndarray:
60
+ return np.rot90(source, k=1).copy()
@@ -0,0 +1,249 @@
1
+ """N3DSXL protocol orchestration."""
2
+
3
+ from time import sleep
4
+ from typing import Protocol
5
+
6
+ from py3dscapture.capture import RawCapture
7
+ from py3dscapture.devices.n3dsxl_ftd3 import DeviceCandidate
8
+ from py3dscapture.errors import UnsupportedDevice, UnsupportedOperation
9
+ from py3dscapture.protocol.sizes import (
10
+ N3DSXL_BULK_IN_ENDPOINT,
11
+ N3DSXL_BULK_OUT_ENDPOINT,
12
+ capture_size,
13
+ video_size,
14
+ )
15
+ from py3dscapture.transport.ftd3_pipe import FTD3_COMMAND_TIMEOUT_MS
16
+
17
+ N3DSXL_CFG_WAIT_MS = 200
18
+ N3DSXL_RAW_FRAME_READ_ATTEMPTS = 8
19
+
20
+
21
+ class N3DSXLPipe(Protocol):
22
+ """FTD3 operations used by the N3DSXL protocol layer.
23
+
24
+ Implementations may wrap libusb command payloads or the native FTDI D3XX
25
+ API, but they must expose the same pipe-level behavior to the protocol
26
+ sequence.
27
+ """
28
+
29
+ backend_kind: str
30
+
31
+ def create_pipe(self) -> None:
32
+ """Create the FTD3 command pipe.
33
+
34
+ Raises:
35
+ Ftd3CommandError: The backend cannot create or emulate the command
36
+ pipe.
37
+ """
38
+ ...
39
+
40
+ def abort_pipe(self, pipe: int) -> None:
41
+ """Abort one FTD3 pipe.
42
+
43
+ Args:
44
+ pipe: Bulk pipe or endpoint ID to abort.
45
+
46
+ Raises:
47
+ Ftd3CommandError: The backend reports a pipe abort failure.
48
+ """
49
+ ...
50
+
51
+ def set_stream_pipe(self, pipe: int, length: int) -> None:
52
+ """Set the stream pipe transfer length.
53
+
54
+ Args:
55
+ pipe: Bulk pipe or endpoint ID to configure.
56
+ length: Transfer length in bytes for streaming reads.
57
+
58
+ Raises:
59
+ Ftd3CommandError: The backend rejects the stream configuration.
60
+ """
61
+ ...
62
+
63
+ def read_pipe(self, pipe: int, length: int, timeout_ms: int = FTD3_COMMAND_TIMEOUT_MS) -> bytes:
64
+ """Read from one FTD3 pipe.
65
+
66
+ Args:
67
+ pipe: Bulk pipe or endpoint ID to read.
68
+ length: Maximum number of bytes to read.
69
+ timeout_ms: Backend read timeout in milliseconds.
70
+
71
+ Returns:
72
+ Bytes transferred by the backend.
73
+
74
+ Raises:
75
+ Ftd3CommandError: The backend read or required prepare step fails.
76
+ """
77
+ ...
78
+
79
+ def write_pipe(
80
+ self,
81
+ pipe: int,
82
+ payload: bytes,
83
+ timeout_ms: int = FTD3_COMMAND_TIMEOUT_MS,
84
+ ) -> int:
85
+ """Write to one FTD3 pipe.
86
+
87
+ Args:
88
+ pipe: Bulk pipe or endpoint ID to write.
89
+ payload: Bytes to send.
90
+ timeout_ms: Backend write timeout in milliseconds.
91
+
92
+ Returns:
93
+ Number of payload bytes transferred.
94
+
95
+ Raises:
96
+ Ftd3CommandError: The backend write or required prepare step fails.
97
+ """
98
+ ...
99
+
100
+ def reconnect_after_drain(self) -> None:
101
+ """Reconnect after the initial drain when the backend requires it.
102
+
103
+ D3XX follows cc3dsfs by closing and reopening after the initial drain;
104
+ libusb keeps the current session.
105
+ """
106
+ ...
107
+
108
+
109
+ class N3DSXLSessionIdentity(Protocol):
110
+ """Opened session identity needed for raw metadata.
111
+
112
+ Attributes:
113
+ candidate: Accepted N3DSXL candidate for artifact metadata.
114
+ """
115
+
116
+ candidate: DeviceCandidate
117
+
118
+
119
+ class N3DSXLProtocol:
120
+ """N3DSXL connect sequence over an accepted device and FTD3 pipe.
121
+
122
+ The protocol assumes device classification and human hardware-command
123
+ approval have already happened outside this class.
124
+ """
125
+
126
+ def __init__(self, device: N3DSXLSessionIdentity, pipe: N3DSXLPipe) -> None:
127
+ """Create protocol orchestration for one safe device session.
128
+
129
+ Args:
130
+ device: Opened session identity with an accepted N3DSXL candidate.
131
+ pipe: FTD3 pipe implementation used for command and bulk transfer.
132
+
133
+ Raises:
134
+ UnsupportedDevice: ``device.candidate`` is not an accepted
135
+ ``DeviceCandidate``.
136
+ """
137
+ if not isinstance(device.candidate, DeviceCandidate):
138
+ raise UnsupportedDevice
139
+ self.device = device
140
+ self.pipe = pipe
141
+
142
+ def connect(self, *, mode_3d: bool = False) -> None:
143
+ """Run the 2D default connect and stream setup sequence.
144
+
145
+ Args:
146
+ mode_3d: Requested capture mode. 3D mode is outside the current MVP
147
+ and is rejected.
148
+
149
+ Raises:
150
+ UnsupportedOperation: ``mode_3d`` is true.
151
+ Ftd3CommandError: Any FTD3 setup command or transfer fails.
152
+ """
153
+ if mode_3d:
154
+ raise UnsupportedOperation
155
+
156
+ self.pipe.create_pipe()
157
+ self._drain_data()
158
+ self.pipe.reconnect_after_drain()
159
+ self.pipe.abort_pipe(N3DSXL_BULK_IN_ENDPOINT)
160
+ self.pipe.create_pipe()
161
+ self._spi_3ds_cc_stuff()
162
+ self._load_3ds_cc_firmware(firmware_id=1)
163
+ self._read_3ds_config_3d()
164
+ self._set_2d_stream_pipe()
165
+
166
+ def read_raw_frame(self, *, mode_3d: bool = False) -> RawCapture:
167
+ """Read one raw frame after connect.
168
+
169
+ Args:
170
+ mode_3d: Requested capture mode. 3D mode is outside the current MVP
171
+ and is rejected.
172
+
173
+ Returns:
174
+ Raw capture payload with N3DSXL identity metadata attached.
175
+
176
+ Raises:
177
+ UnsupportedOperation: ``mode_3d`` is true.
178
+ Ftd3CommandError: Bulk read through the selected backend fails.
179
+ DecodeError: The resulting raw capture is shorter than the expected
180
+ video region.
181
+ TransferOverflow: The backend reports more than the 2D capture size.
182
+ """
183
+ if mode_3d:
184
+ raise UnsupportedOperation
185
+ transfer_size = capture_size(mode_3d=False)
186
+ expected_video_size = video_size(mode_3d=False)
187
+ payload = b""
188
+ for _ in range(N3DSXL_RAW_FRAME_READ_ATTEMPTS):
189
+ payload = self.pipe.read_pipe(N3DSXL_BULK_IN_ENDPOINT, transfer_size)
190
+ if len(payload) >= expected_video_size:
191
+ break
192
+ return RawCapture(
193
+ model="new_3ds_xl",
194
+ mode_3d=False,
195
+ payload=payload,
196
+ transferred=len(payload),
197
+ video_size=expected_video_size,
198
+ capture_size=transfer_size,
199
+ timestamp_ns=None,
200
+ sequence=None,
201
+ metadata={
202
+ "product_string": self.device.candidate.product_string,
203
+ "product_string_status": self.device.candidate.product_string_status,
204
+ "backend_kind": self.pipe.backend_kind,
205
+ "vid": f"0x{self.device.candidate.info.vendor_id:04x}",
206
+ "pid": f"0x{self.device.candidate.info.product_id:04x}",
207
+ },
208
+ )
209
+
210
+ def _drain_data(self) -> None:
211
+ self._set_spi_access(enabled=True)
212
+ self.pipe.read_pipe(N3DSXL_BULK_IN_ENDPOINT, 0x100000, timeout_ms=N3DSXL_CFG_WAIT_MS)
213
+
214
+ def _spi_3ds_cc_stuff(self) -> None:
215
+ self._set_spi_access(enabled=True)
216
+ self.pipe.write_pipe(N3DSXL_BULK_OUT_ENDPOINT, bytes([0x80, 0x01, 0xAB, 0x00]))
217
+ self.pipe.write_pipe(
218
+ N3DSXL_BULK_OUT_ENDPOINT,
219
+ bytes([0x90, 0x08, 0x03, 0x02, 0x00, 0x00, 0x00, 0x00]),
220
+ )
221
+ self.pipe.read_pipe(N3DSXL_BULK_IN_ENDPOINT, 0x10)
222
+ self.pipe.write_pipe(N3DSXL_BULK_OUT_ENDPOINT, bytes([0x80, 0x01, 0xAB, 0x00]))
223
+ self._set_spi_access(enabled=False)
224
+
225
+ def _load_3ds_cc_firmware(self, *, firmware_id: int) -> None:
226
+ firmware_to_use = min(firmware_id, 1)
227
+ self._set_spi_access(enabled=True)
228
+ self.pipe.write_pipe(
229
+ N3DSXL_BULK_OUT_ENDPOINT,
230
+ bytes([0x42 + firmware_to_use, 0x00, 0x00, 0x00]),
231
+ )
232
+ sleep(N3DSXL_CFG_WAIT_MS / 1000)
233
+ self._set_spi_access(enabled=False)
234
+
235
+ def _read_3ds_config_3d(self) -> None:
236
+ self._set_spi_access(enabled=True)
237
+ self.pipe.write_pipe(N3DSXL_BULK_OUT_ENDPOINT, bytes([0x98, 0x05, 0x9F, 0x00]))
238
+ self.pipe.read_pipe(N3DSXL_BULK_IN_ENDPOINT, 0x10)
239
+ self._set_spi_access(enabled=False)
240
+
241
+ def _set_2d_stream_pipe(self) -> None:
242
+ length = capture_size(mode_3d=False)
243
+ self.pipe.set_stream_pipe(N3DSXL_BULK_IN_ENDPOINT, length)
244
+ self.pipe.abort_pipe(N3DSXL_BULK_IN_ENDPOINT)
245
+ self.pipe.set_stream_pipe(N3DSXL_BULK_IN_ENDPOINT, length)
246
+
247
+ def _set_spi_access(self, *, enabled: bool) -> None:
248
+ second_byte = 0x80 if enabled else 0x00
249
+ self.pipe.write_pipe(N3DSXL_BULK_OUT_ENDPOINT, bytes([0x40, second_byte, 0x00, 0x00]))
@@ -0,0 +1,128 @@
1
+ """N3DSXL capture constants and raw frame size calculations."""
2
+
3
+ from dataclasses import dataclass
4
+ from typing import Final
5
+
6
+ N3DSXL_VENDOR_ID: Final = 0x0403
7
+ ACCEPTED_N3DSXL_PRODUCT_IDS: Final[frozenset[int]] = frozenset(
8
+ {0x601E, 0x601F, 0x602A, 0x602B, 0x602C, 0x602D, 0x602F}
9
+ )
10
+ ACCEPTED_N3DSXL_PRODUCT_STRINGS: Final[frozenset[str]] = frozenset({"N3DSXL", "N3DSXL.2"})
11
+
12
+ N3DSXL_COMMAND_INTERFACE: Final = 0
13
+ N3DSXL_BULK_INTERFACE: Final = 1
14
+ N3DSXL_BULK_OUT_ENDPOINT: Final = 0x02
15
+ N3DSXL_BULK_IN_ENDPOINT: Final = 0x82
16
+ N3DSXL_FTD3_COMMAND_PIPE_ID: Final = 0x01
17
+ N3DSXL_DEFAULT_CONFIGURATION: Final = 1
18
+
19
+ TOP_WIDTH_3DS: Final = 400
20
+ BOTTOM_WIDTH_3DS: Final = 320
21
+ HEIGHT_3DS: Final = 240
22
+ RGB8_CHANNELS: Final = 3
23
+
24
+ N3DSXL_SAMPLES_IN: Final = 1096 * 16
25
+ AUDIO_SAMPLE_BYTES: Final = 2
26
+ AUDIO_SIZE_BYTES: Final = N3DSXL_SAMPLES_IN * AUDIO_SAMPLE_BYTES
27
+ UNUSED_BUFFER_SIZE_BYTES: Final = 1024
28
+ ERROR_BUFFER_SIZE_BYTES: Final = 1024
29
+ USB_CAPTURE_ALIGNMENT_BYTES: Final = 1024
30
+
31
+
32
+ @dataclass(frozen=True, slots=True)
33
+ class CaptureSizes:
34
+ """Calculated raw capture sizes for one transfer mode.
35
+
36
+ Attributes:
37
+ mode_3d: Whether these values describe the N3DSXL 3D transfer layout.
38
+ video_size: RGB8 video payload bytes at the start of a transfer.
39
+ audio_size: Audio buffer bytes present in the cc3dsfs structure.
40
+ struct_total_before_1024_floor: Size before the cc3dsfs 1024-byte floor
41
+ operation.
42
+ capture_size: Bulk transfer size after 1024-byte alignment flooring.
43
+ max_non_error_transferred: Largest transfer length that does not overlap
44
+ the error buffer.
45
+ """
46
+
47
+ mode_3d: bool
48
+ video_size: int
49
+ audio_size: int
50
+ struct_total_before_1024_floor: int
51
+ capture_size: int
52
+ max_non_error_transferred: int
53
+
54
+
55
+ def video_size(mode_3d: bool) -> int:
56
+ """Return RGB8 video payload bytes for 2D or 3D mode.
57
+
58
+ Args:
59
+ mode_3d: Include the right-eye top screen when true.
60
+
61
+ Returns:
62
+ Number of RGB8 video bytes before audio, unused, and error buffers.
63
+ """
64
+ stacked_screen_width = TOP_WIDTH_3DS + BOTTOM_WIDTH_3DS
65
+ if mode_3d:
66
+ stacked_screen_width += TOP_WIDTH_3DS
67
+ return HEIGHT_3DS * stacked_screen_width * RGB8_CHANNELS
68
+
69
+
70
+ def struct_total_before_1024_floor(mode_3d: bool) -> int:
71
+ """Return the C capture struct size before cc3dsfs' 1024-byte floor operation.
72
+
73
+ Args:
74
+ mode_3d: Include the right-eye top screen when true.
75
+
76
+ Returns:
77
+ Sum of video, audio, unused, and error-buffer bytes before USB transfer
78
+ alignment is applied.
79
+ """
80
+ return (
81
+ video_size(mode_3d) + AUDIO_SIZE_BYTES + UNUSED_BUFFER_SIZE_BYTES + ERROR_BUFFER_SIZE_BYTES
82
+ )
83
+
84
+
85
+ def capture_size(mode_3d: bool) -> int:
86
+ """Return the transfer size after the 1024-byte floor operation.
87
+
88
+ Args:
89
+ mode_3d: Include the right-eye top screen when true.
90
+
91
+ Returns:
92
+ Bulk transfer length used by the N3DSXL read path.
93
+ """
94
+ total = struct_total_before_1024_floor(mode_3d)
95
+ return (total // USB_CAPTURE_ALIGNMENT_BYTES) * USB_CAPTURE_ALIGNMENT_BYTES
96
+
97
+
98
+ def max_non_error_transferred(mode_3d: bool) -> int:
99
+ """Return the largest transfer length that does not enter the error buffer.
100
+
101
+ Args:
102
+ mode_3d: Include the right-eye top screen when true.
103
+
104
+ Returns:
105
+ Transfer byte count threshold before the cc3dsfs error buffer starts.
106
+ """
107
+ return capture_size(mode_3d) - ERROR_BUFFER_SIZE_BYTES
108
+
109
+
110
+ def capture_sizes(mode_3d: bool) -> CaptureSizes:
111
+ """Return all calculated size values for one transfer mode.
112
+
113
+ Args:
114
+ mode_3d: Include the right-eye top screen when true.
115
+
116
+ Returns:
117
+ Immutable grouped size values for metadata and characterization tests.
118
+ """
119
+ total = struct_total_before_1024_floor(mode_3d)
120
+ transfer_size = capture_size(mode_3d)
121
+ return CaptureSizes(
122
+ mode_3d=mode_3d,
123
+ video_size=video_size(mode_3d),
124
+ audio_size=AUDIO_SIZE_BYTES,
125
+ struct_total_before_1024_floor=total,
126
+ capture_size=transfer_size,
127
+ max_non_error_transferred=transfer_size - ERROR_BUFFER_SIZE_BYTES,
128
+ )
py3dscapture/py.typed ADDED
@@ -0,0 +1 @@
1
+
@@ -0,0 +1 @@
1
+ """Streaming engine components."""
@@ -0,0 +1,156 @@
1
+ """Raw streaming buffer pool."""
2
+
3
+ from dataclasses import dataclass, field
4
+
5
+
6
+ @dataclass(slots=True)
7
+ class RawFrameSlot:
8
+ """One reusable raw transfer slot.
9
+
10
+ Attributes:
11
+ index: Stable slot index used by backend callbacks.
12
+ buffer: Mutable byte storage owned by the pool.
13
+ view: Stable memoryview over ``buffer`` for zero-copy backend writes.
14
+ in_use: Whether the slot is checked out by an in-flight transfer.
15
+ submitted_ns: Optional monotonic timestamp when the transfer was queued.
16
+ backend_started_ns: Optional monotonic timestamp when the backend worker
17
+ started the actual read.
18
+ completed_ns: Optional monotonic timestamp when the transfer completed.
19
+ transferred: Bytes reported by the backend.
20
+ sequence: Optional streaming sequence assigned at submission time.
21
+ """
22
+
23
+ index: int
24
+ buffer: bytearray
25
+ view: memoryview = field(init=False)
26
+ in_use: bool = False
27
+ submitted_ns: int | None = None
28
+ backend_started_ns: int | None = None
29
+ completed_ns: int | None = None
30
+ transferred: int = 0
31
+ sequence: int | None = None
32
+
33
+ def __post_init__(self) -> None:
34
+ """Create a stable memoryview for the slot buffer.
35
+
36
+ The view is reused for the lifetime of the slot so callbacks can refer
37
+ to the same memory without allocating a new memoryview per transfer.
38
+ """
39
+ self.view = memoryview(self.buffer)
40
+
41
+
42
+ @dataclass(frozen=True, slots=True)
43
+ class RawFrameResult:
44
+ """Completed raw transfer metadata.
45
+
46
+ Attributes:
47
+ slot_index: Slot that produced this result.
48
+ view: Memoryview containing the completed raw bytes.
49
+ transferred: Number of bytes reported by the backend.
50
+ status: Backend completion status, where zero means success.
51
+ submitted_ns: Monotonic submission timestamp when available.
52
+ backend_started_ns: Monotonic backend read-start timestamp when
53
+ available.
54
+ completed_ns: Monotonic completion timestamp.
55
+ sequence: Streaming sequence assigned when the read was submitted.
56
+ """
57
+
58
+ slot_index: int
59
+ view: memoryview
60
+ transferred: int
61
+ status: int
62
+ submitted_ns: int | None
63
+ backend_started_ns: int | None
64
+ completed_ns: int
65
+ sequence: int
66
+
67
+
68
+ class BufferPool:
69
+ """Preallocated raw slot pool.
70
+
71
+ The pool keeps raw buffers stable so async backends can write into memory
72
+ owned by the streaming engine without allocating per transfer.
73
+ """
74
+
75
+ def __init__(self, *, raw_slots: int, raw_slot_size: int) -> None:
76
+ """Create fixed raw slots.
77
+
78
+ Args:
79
+ raw_slots: Number of reusable slots to allocate.
80
+ raw_slot_size: Byte size for each raw transfer buffer.
81
+
82
+ Raises:
83
+ ValueError: Either value is not positive.
84
+ """
85
+ if raw_slots <= 0 or raw_slot_size <= 0:
86
+ raise ValueError
87
+ self._slots = tuple(
88
+ RawFrameSlot(index=index, buffer=bytearray(raw_slot_size)) for index in range(raw_slots)
89
+ )
90
+
91
+ @property
92
+ def slots(self) -> tuple[RawFrameSlot, ...]:
93
+ """Return all slots.
94
+
95
+ Returns:
96
+ Tuple of pool slots in stable index order.
97
+ """
98
+ return self._slots
99
+
100
+ def checkout(self, index: int) -> RawFrameSlot:
101
+ """Mark one slot in use.
102
+
103
+ Args:
104
+ index: Slot index to reserve.
105
+
106
+ Returns:
107
+ The reserved slot.
108
+
109
+ Raises:
110
+ RuntimeError: The slot is already checked out.
111
+ IndexError: ``index`` is outside the pool.
112
+ """
113
+ slot = self._slots[index]
114
+ if slot.in_use:
115
+ raise RuntimeError
116
+ slot.in_use = True
117
+ return slot
118
+
119
+ def release(self, index: int) -> None:
120
+ """Release one slot.
121
+
122
+ Args:
123
+ index: Slot index to release and reset.
124
+
125
+ Raises:
126
+ IndexError: ``index`` is outside the pool.
127
+ """
128
+ slot = self._slots[index]
129
+ slot.in_use = False
130
+ slot.submitted_ns = None
131
+ slot.backend_started_ns = None
132
+ slot.completed_ns = None
133
+ slot.transferred = 0
134
+ slot.sequence = None
135
+
136
+ def get(self, index: int) -> RawFrameSlot:
137
+ """Return one slot by index.
138
+
139
+ Args:
140
+ index: Slot index to return.
141
+
142
+ Returns:
143
+ The slot with the requested index.
144
+
145
+ Raises:
146
+ IndexError: ``index`` is outside the pool.
147
+ """
148
+ return self._slots[index]
149
+
150
+ def in_use_count(self) -> int:
151
+ """Return the number of checked-out slots.
152
+
153
+ Returns:
154
+ Count of slots currently marked in use.
155
+ """
156
+ return sum(1 for slot in self._slots if slot.in_use)