zuvloop 0.0.19__cp313-cp313-win_amd64.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.
zuvloop/__init__.py ADDED
@@ -0,0 +1,17 @@
1
+ from ._instrumentation import Instrumentation
2
+ from ._loop import EventLoop
3
+ from ._runner import new_event_loop, run
4
+ from ._server import Server
5
+ from ._zuvloop import Handle, TimerHandle, Transport, libuv_version
6
+
7
+ __all__ = [
8
+ "EventLoop",
9
+ "Handle",
10
+ "Instrumentation",
11
+ "Server",
12
+ "TimerHandle",
13
+ "Transport",
14
+ "libuv_version",
15
+ "new_event_loop",
16
+ "run",
17
+ ]
zuvloop/_base.py ADDED
@@ -0,0 +1,529 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ import concurrent.futures
5
+ import logging
6
+ import os
7
+ import signal
8
+ import socket
9
+ import sys
10
+ import threading
11
+ import traceback
12
+ import warnings
13
+ import weakref
14
+ from asyncio import events as _events
15
+ from asyncio.base_events import _run_until_complete_cb # type: ignore[attr-defined]
16
+ from collections.abc import Callable
17
+ from contextvars import Context
18
+ from dataclasses import dataclass
19
+ from functools import partial
20
+ from typing import TYPE_CHECKING, Any, Protocol
21
+
22
+ from . import _zuvloop
23
+ from ._instrumentation import (
24
+ Instrumentation,
25
+ _safe_repr,
26
+ instrumentation_provider_installed,
27
+ metrics_provider_installed,
28
+ publish_metrics,
29
+ )
30
+
31
+ if TYPE_CHECKING:
32
+ from collections.abc import Coroutine
33
+
34
+ _ExceptionHandler = Callable[[asyncio.AbstractEventLoop, dict[str, Any]], object]
35
+
36
+
37
+ class _ExecutorNotifier(Protocol):
38
+ def call_soon_threadsafe(self, callback: Callable[..., object], *args: object) -> object: ...
39
+ def is_closed(self) -> bool: ...
40
+
41
+
42
+ class _ExecutorShutdown(Protocol):
43
+ def shutdown(self, *, wait: bool) -> None: ...
44
+
45
+
46
+ # Signal dispositions and the wakeup fd are process-global. Tokens let delayed
47
+ # finalization tell whether another loop has replaced the state it installed.
48
+ @dataclass(eq=False, slots=True)
49
+ class SignalOwner:
50
+ finalized: bool = False
51
+
52
+ def is_finalized(self) -> bool:
53
+ return self.finalized
54
+
55
+
56
+ @dataclass(frozen=True, slots=True)
57
+ class WakeupState:
58
+ fd: int
59
+ owner: SignalOwner | None
60
+ was_attached: bool
61
+
62
+
63
+ _signal_owners: dict[int, SignalOwner] = {}
64
+ _wakeup_fd_owner: SignalOwner | None = None
65
+
66
+
67
+ # The native methods are stricter than typeshed's AbstractEventLoop, which
68
+ # types several of them with TypeVarTuples this class cannot reproduce.
69
+ class LoopBase(_zuvloop.Loop, asyncio.AbstractEventLoop): # type: ignore[misc]
70
+ """Lifecycle, task creation, executors and error reporting.
71
+
72
+ Scheduling primitives (`call_soon`, `call_later`, `time`, the reader and
73
+ writer registrations) come from the Zig extension; everything here is
74
+ orchestration that runs once per loop or once per connection.
75
+ """
76
+
77
+ # How often the native sampler fires while the loop runs. It publishes the
78
+ # loop gauges when a meter provider is installed, and it is also how quickly
79
+ # a provider configured after the loop started is noticed. Assign before
80
+ # running the loop to change it.
81
+ metrics_interval: float = 10.0
82
+
83
+ def __init__(self) -> None:
84
+ self._exception_handler: _ExceptionHandler | None = None
85
+ self._default_executor: concurrent.futures.Executor | None = None
86
+ self._executor_shutdown_called = False
87
+ self._asyncgens: weakref.WeakSet[Any] = weakref.WeakSet()
88
+ self._asyncgens_shutdown_called = False
89
+ self._signal_handlers: dict[int, tuple[Callable[..., object], tuple[Any, ...], Context]] = {}
90
+ # Which `sock_*` call owns the watcher currently on each (fd, write).
91
+ self._sock_watchers: dict[tuple[int, bool], object] = {}
92
+ self._wakeup_fd_attached = False
93
+ self._signal_owner = SignalOwner()
94
+ self._instrumentation = Instrumentation()
95
+ self._monitoring_armed = False
96
+ self._metrics_armed = False
97
+ self._setup_self_pipe()
98
+
99
+ def __del__(self, _warn: Callable[..., object] = warnings.warn) -> None:
100
+ if not self.is_closed():
101
+ try:
102
+ _warn(f"unclosed event loop {self!r}", ResourceWarning, source=self)
103
+ except BaseException:
104
+ # Exceptions escaping a finalizer are only reported as
105
+ # unraisable; warning filters must not prevent cleanup.
106
+ pass
107
+ if not self.is_running():
108
+ try:
109
+ self.close()
110
+ except BaseException:
111
+ # Explicit closure also owns deferred signal cleanup.
112
+ pass
113
+
114
+ # -- lifecycle ---------------------------------------------------------
115
+
116
+ def run_forever(self) -> None:
117
+ self._check_closed()
118
+ self._check_runnable()
119
+ old_hooks = sys.get_asyncgen_hooks()
120
+ self._attach_wakeup_fd()
121
+ _events._set_running_loop(self)
122
+ sys.set_asyncgen_hooks(firstiter=self._asyncgen_firstiter, finalizer=self._asyncgen_finalizer)
123
+ self._monitoring_armed = instrumentation_provider_installed()
124
+ self._metrics_armed = metrics_provider_installed()
125
+ try:
126
+ self._set_slow_callback_monitoring(self._monitoring_armed)
127
+ self._start_metrics(self.metrics_interval, self._on_sample)
128
+ self._run()
129
+ finally:
130
+ self._set_slow_callback_monitoring(False)
131
+ self._stop_metrics()
132
+ sys.set_asyncgen_hooks(*old_hooks)
133
+ _events._set_running_loop(None)
134
+ self._detach_wakeup_fd()
135
+
136
+ def run_until_complete(self, future: Any) -> Any:
137
+ self._check_closed()
138
+ self._check_runnable()
139
+ new_task = not isinstance(future, asyncio.Future)
140
+ task = asyncio.ensure_future(future, loop=self)
141
+ if new_task:
142
+ task._log_destroy_pending = False
143
+ # AnyIO identifies the root task by this exact done callback.
144
+ task.add_done_callback(_run_until_complete_cb)
145
+ try:
146
+ self.run_forever()
147
+ except BaseException:
148
+ if new_task and task.done() and not task.cancelled():
149
+ task.exception()
150
+ raise
151
+ finally:
152
+ task.remove_done_callback(_run_until_complete_cb)
153
+ if not task.done():
154
+ raise RuntimeError("Event loop stopped before Future completed.")
155
+ return task.result()
156
+
157
+ def close(self) -> None:
158
+ if self.is_running():
159
+ raise RuntimeError("Cannot close a running event loop")
160
+ if self.is_closed():
161
+ return
162
+ executor = self._default_executor
163
+ self._default_executor = None
164
+ self._close()
165
+ self._signal_owner.finalized = True
166
+ try:
167
+ for sig in tuple(self._signal_handlers):
168
+ self.remove_signal_handler(sig)
169
+ finally:
170
+ try:
171
+ if self._signal_handlers or self._wakeup_fd_attached:
172
+ # Wakeup ownership can outlive this loop's ownership of its signal handlers.
173
+ wakeup_fd = self._csock.detach()
174
+ signals = tuple(self._signal_handlers)
175
+ self._signal_handlers.clear()
176
+ self._wakeup_fd_attached = False
177
+ cleanup = partial(_finish_deferred_signal_cleanup, signals, wakeup_fd, self._signal_owner)
178
+ if threading.current_thread() is threading.main_thread():
179
+ cleanup()
180
+ else:
181
+ self._defer_close(cleanup)
182
+ finally:
183
+ try:
184
+ self._teardown_self_pipe()
185
+ finally:
186
+ if executor is not None:
187
+ executor.shutdown(wait=False)
188
+
189
+ async def shutdown_asyncgens(self) -> None:
190
+ self._asyncgens_shutdown_called = True
191
+ closing = list(self._asyncgens)
192
+ if not closing:
193
+ return
194
+ self._asyncgens.clear()
195
+ results = await asyncio.gather(*(agen.aclose() for agen in closing), return_exceptions=True)
196
+ for result, agen in zip(results, closing, strict=True):
197
+ if isinstance(result, BaseException):
198
+ self.call_exception_handler(
199
+ {
200
+ "message": f"an error occurred during closing of asynchronous generator {agen!r}",
201
+ "exception": result,
202
+ "asyncgen": agen,
203
+ }
204
+ )
205
+
206
+ async def shutdown_default_executor(self, timeout: float | None = None) -> None:
207
+ self._executor_shutdown_called = True
208
+ executor = self._default_executor
209
+ if executor is None:
210
+ return
211
+ future = self.create_future()
212
+ thread = threading.Thread(target=_shutdown_executor, args=(self, future, executor))
213
+ thread.start()
214
+ try:
215
+ async with asyncio.timeout(timeout):
216
+ await future
217
+ except TimeoutError:
218
+ warnings.warn("The executor did not finish joining its threads within the timeout", RuntimeWarning, 2)
219
+ executor.shutdown(wait=False)
220
+ else:
221
+ thread.join()
222
+
223
+ # -- futures and tasks -------------------------------------------------
224
+
225
+ def create_future(self) -> asyncio.Future[Any]:
226
+ return asyncio.Future(loop=self)
227
+
228
+ if TYPE_CHECKING:
229
+
230
+ def create_task[T](
231
+ self,
232
+ coro: Coroutine[Any, Any, T],
233
+ *,
234
+ name: str | None = None,
235
+ context: Context | None = None,
236
+ **kwargs: Any,
237
+ ) -> asyncio.Task[T]: ...
238
+
239
+ def set_task_factory( # type: ignore[override] # typeshed's _TaskFactory is narrower than asyncio accepts
240
+ self, factory: Callable[..., asyncio.Task[Any]] | None, /
241
+ ) -> None: ...
242
+
243
+ def get_task_factory(self) -> Callable[..., asyncio.Task[Any]] | None: ...
244
+
245
+ # -- executors ---------------------------------------------------------
246
+
247
+ def run_in_executor[T]( # type: ignore[override] # typeshed loses the return type
248
+ self, executor: concurrent.futures.Executor | None, func: Callable[..., T], *args: Any
249
+ ) -> asyncio.Future[T]:
250
+ self._check_closed()
251
+ if executor is None:
252
+ if self._executor_shutdown_called:
253
+ raise RuntimeError("Executor shutdown has been called")
254
+ executor = self._default_executor
255
+ if executor is None:
256
+ executor = concurrent.futures.ThreadPoolExecutor(thread_name_prefix="zuvloop")
257
+ self._default_executor = executor
258
+ return asyncio.futures.wrap_future(executor.submit(func, *args), loop=self)
259
+
260
+ def set_default_executor(self, executor: concurrent.futures.Executor) -> None:
261
+ self._default_executor = executor
262
+
263
+ # -- error reporting ---------------------------------------------------
264
+
265
+ def get_exception_handler(self) -> _ExceptionHandler | None:
266
+ return self._exception_handler
267
+
268
+ def set_exception_handler(self, handler: _ExceptionHandler | None) -> None:
269
+ self._exception_handler = handler
270
+
271
+ def default_exception_handler(self, context: dict[str, Any]) -> None:
272
+ message = context.get("message") or "Unhandled exception in event loop"
273
+ exception = context.get("exception")
274
+ exc_info = (
275
+ (type(exception), exception, exception.__traceback__) if isinstance(exception, BaseException) else False
276
+ )
277
+ log_lines = [str(message)]
278
+ for key in sorted(context):
279
+ if key in ("message", "exception"):
280
+ continue
281
+ value = context[key]
282
+ if key == "source_traceback":
283
+ value = "Object created at (most recent call last):\n" + "".join(traceback.format_list(value)).rstrip()
284
+ elif key == "handle_traceback":
285
+ value = "Handle created at (most recent call last):\n" + "".join(traceback.format_list(value)).rstrip()
286
+ else:
287
+ value = _safe_repr(value)
288
+ log_lines.append(f"{key}: {value}")
289
+
290
+ # Keep asyncio's built-in stderr/logging behaviour. Telemetry is an
291
+ # additional destination, not a replacement: without an installed
292
+ # provider OpenTelemetry is deliberately a no-op, and an application
293
+ # must not lose "Task exception was never retrieved" and callback
294
+ # failures merely because it has not configured an exporter.
295
+ logging.getLogger("asyncio").error("\n".join(log_lines), exc_info=exc_info)
296
+ self._instrumentation.report_exception(context)
297
+
298
+ def call_exception_handler(self, context: dict[str, Any]) -> None:
299
+ if self._exception_handler is None:
300
+ try:
301
+ self.default_exception_handler(context)
302
+ except (SystemExit, KeyboardInterrupt):
303
+ raise
304
+ except BaseException:
305
+ logging.getLogger("asyncio").exception("Exception in default exception handler")
306
+ return
307
+ try:
308
+ thing = context.get("task")
309
+ if thing is None:
310
+ thing = context.get("future")
311
+ if thing is None:
312
+ thing = context.get("handle")
313
+ ctx = thing.get_context() if thing is not None and hasattr(thing, "get_context") else None
314
+ if ctx is not None and hasattr(ctx, "run"):
315
+ ctx.run(self._exception_handler, self, context)
316
+ else:
317
+ self._exception_handler(self, context)
318
+ except (SystemExit, KeyboardInterrupt):
319
+ raise
320
+ except BaseException as exc:
321
+ try:
322
+ self.default_exception_handler(
323
+ {"message": "Unhandled error in exception handler", "exception": exc, "context": context}
324
+ )
325
+ except (SystemExit, KeyboardInterrupt):
326
+ raise
327
+ except BaseException:
328
+ logging.getLogger("asyncio").exception(
329
+ "Exception in default exception handler while handling "
330
+ "an unexpected error in custom exception handler"
331
+ )
332
+
333
+ def _on_slow_callback(self, handle: object, duration: float, cpu_time: float = -1) -> None:
334
+ self._instrumentation.report_slow_callback(handle, duration, cpu_time)
335
+
336
+ def _on_sample(self, snapshot: dict[str, int]) -> None:
337
+ if not self._monitoring_armed and instrumentation_provider_installed():
338
+ self._monitoring_armed = True
339
+ self._set_slow_callback_monitoring(True)
340
+ if not self._metrics_armed:
341
+ self._metrics_armed = metrics_provider_installed()
342
+ if self._metrics_armed:
343
+ publish_metrics(snapshot)
344
+
345
+ # -- internals ---------------------------------------------------------
346
+
347
+ def _check_closed(self) -> None:
348
+ if self.is_closed():
349
+ raise RuntimeError("Event loop is closed")
350
+
351
+ def _check_runnable(self) -> None:
352
+ if self.is_running():
353
+ raise RuntimeError("This event loop is already running")
354
+ if _events._get_running_loop() is not None:
355
+ raise RuntimeError("Cannot run the event loop while another loop is running")
356
+
357
+ def _asyncgen_firstiter(self, agen: Any) -> None:
358
+ if self._asyncgens_shutdown_called:
359
+ warnings.warn(
360
+ f"asynchronous generator {agen!r} was scheduled after loop.shutdown_asyncgens() call",
361
+ ResourceWarning,
362
+ source=self,
363
+ )
364
+ self._asyncgens.add(agen)
365
+
366
+ def _asyncgen_finalizer(self, agen: Any) -> None:
367
+ self._asyncgens.discard(agen)
368
+ if not self.is_closed():
369
+ self.call_soon_threadsafe(self.create_task, agen.aclose())
370
+
371
+ def _setup_self_pipe(self) -> None:
372
+ self._ssock, self._csock = socket.socketpair()
373
+ self._ssock.setblocking(False)
374
+ self._csock.setblocking(False)
375
+ self.add_reader(self._ssock.fileno(), self._drain_self_pipe, self._ssock)
376
+
377
+ def _teardown_self_pipe(self) -> None:
378
+ try:
379
+ self.remove_reader(self._ssock.fileno())
380
+ finally:
381
+ try:
382
+ self._ssock.close()
383
+ finally:
384
+ self._csock.close()
385
+
386
+ def _attach_wakeup_fd(self) -> WakeupState | None:
387
+ # Only the main thread may own the wakeup fd, and only it runs Python
388
+ # signal handlers - so a loop on any other thread simply skips this.
389
+ if threading.current_thread() is threading.main_thread() and self._signal_handlers:
390
+ global _wakeup_fd_owner
391
+ previous_owner = _wakeup_fd_owner
392
+ previous_attached = self._wakeup_fd_attached
393
+ # Publish the provisional token before the syscall. A pending old
394
+ # cleanup can run as soon as the C call returns; it must already see
395
+ # that the descriptor has changed hands.
396
+ _wakeup_fd_owner = self._signal_owner
397
+ try:
398
+ previous_fd = signal.set_wakeup_fd(self._csock.fileno())
399
+ except OSError:
400
+ if previous_owner is None or not previous_owner.is_finalized():
401
+ _wakeup_fd_owner = previous_owner
402
+ else:
403
+ # A skipped stale cleanup may have closed its descriptor;
404
+ # never put that invalid owner back.
405
+ signal.set_wakeup_fd(-1)
406
+ _wakeup_fd_owner = None
407
+ raise
408
+ self._wakeup_fd_attached = True
409
+ return WakeupState(previous_fd, previous_owner, previous_attached)
410
+ return None
411
+
412
+ def _restore_wakeup_fd(self, previous: WakeupState | None) -> None:
413
+ if previous is None:
414
+ return
415
+ global _wakeup_fd_owner
416
+ # Stale cleanup skips a replacement token, so this transaction remains
417
+ # the wakeup owner until it either commits or restores this snapshot.
418
+ assert _wakeup_fd_owner is self._signal_owner
419
+ abandon = previous.owner is not None and previous.owner.is_finalized()
420
+ try:
421
+ signal.set_wakeup_fd(-1 if abandon else previous.fd)
422
+ except OSError: # pragma: no cover - fd closed between check and syscall
423
+ # Finalization may close fd after the check but before the syscall.
424
+ signal.set_wakeup_fd(-1)
425
+ abandon = True
426
+ _wakeup_fd_owner = None if abandon else previous.owner
427
+ self._wakeup_fd_attached = False if abandon else previous.was_attached
428
+ # Revalidate after publishing: cleanup can run between any two Python
429
+ # operations above. If it did, never leave its closed fd reinstalled.
430
+ if ( # pragma: no cover - defensive recheck after deferred cleanup
431
+ previous.owner is not None and previous.owner.is_finalized() and _wakeup_fd_owner is previous.owner
432
+ ):
433
+ signal.set_wakeup_fd(-1)
434
+ _wakeup_fd_owner = None
435
+ self._wakeup_fd_attached = False
436
+
437
+ def _detach_wakeup_fd(self) -> None:
438
+ # Registered handlers must keep the fd active between separate calls
439
+ # to run_forever/run_until_complete. A signal arriving while the loop
440
+ # is stopped remains queued in the self-pipe for the next run.
441
+ if (
442
+ threading.current_thread() is threading.main_thread()
443
+ and self._wakeup_fd_attached
444
+ and not self._signal_handlers
445
+ ):
446
+ global _wakeup_fd_owner
447
+ if _wakeup_fd_owner is self._signal_owner:
448
+ signal.set_wakeup_fd(-1)
449
+ _wakeup_fd_owner = None
450
+ self._wakeup_fd_attached = False
451
+
452
+ def _add_reader(self, fd: int, callback: Callable[..., object], *args: object) -> None:
453
+ """asyncio's own name for `add_reader`; its child watcher uses it."""
454
+ self.add_reader(fd, callback, *args)
455
+
456
+ def _remove_reader(self, fd: int) -> bool:
457
+ return self.remove_reader(fd)
458
+
459
+ def _stop_serving(self, sock: socket.socket) -> None:
460
+ """asyncio's own name for the hook `asyncio.base_events.Server.close` calls."""
461
+ self.remove_reader(sock.fileno())
462
+ sock.close()
463
+
464
+ def _drain_self_pipe(self, sock: socket.socket) -> None:
465
+ """Read the wakeup bytes; each one is a signal number to dispatch.
466
+
467
+ Signals arrive through `signal.set_wakeup_fd` rather than from the
468
+ Python-level handler, because applications legitimately install their own
469
+ handler with `signal.signal` afterwards - uvicorn does - and that must not
470
+ silently unhook the loop's own delivery.
471
+ """
472
+ try:
473
+ while True:
474
+ data = sock.recv(4096)
475
+ if not data:
476
+ # EOF remains level-triggered readable forever. Stop
477
+ # watching this dead pipe or the loop will spin on it.
478
+ self.remove_reader(sock.fileno())
479
+ break
480
+ for signum in data:
481
+ self._dispatch_signal(signum)
482
+ except (BlockingIOError, InterruptedError):
483
+ pass
484
+
485
+ def _dispatch_signal(self, signum: int) -> None:
486
+ entry = self._signal_handlers.get(signum)
487
+ if entry is None:
488
+ return
489
+ callback, args, context = entry
490
+ self.call_soon(callback, *args, context=context)
491
+
492
+
493
+ def _finish_deferred_signal_cleanup(signals: tuple[int, ...], wakeup_fd: int, owner: SignalOwner) -> None:
494
+ global _wakeup_fd_owner
495
+ owner.finalized = True
496
+ if _wakeup_fd_owner is owner:
497
+ signal.set_wakeup_fd(-1)
498
+ _wakeup_fd_owner = None
499
+ failure: OSError | ValueError | None = None
500
+ try:
501
+ for sig in signals:
502
+ if _signal_owners.get(sig) is owner:
503
+ handler = signal.default_int_handler if sig == signal.SIGINT else signal.SIG_DFL
504
+ try:
505
+ signal.signal(sig, handler)
506
+ except (OSError, ValueError) as exc:
507
+ # A failed reset keeps its owner, so a later reset cannot lose the signal.
508
+ failure = failure or exc
509
+ else:
510
+ if _signal_owners.get(sig) is owner:
511
+ del _signal_owners[sig]
512
+ if failure is not None:
513
+ raise failure
514
+ finally:
515
+ os.close(wakeup_fd)
516
+
517
+
518
+ def _shutdown_executor(loop: _ExecutorNotifier, future: asyncio.Future[None], executor: _ExecutorShutdown) -> None:
519
+ try:
520
+ executor.shutdown(wait=True)
521
+ finally:
522
+ # shutdown_default_executor() abandons this thread when it times out, so
523
+ # the loop can be long closed by the time the executor finishes.
524
+ try:
525
+ loop.call_soon_threadsafe(asyncio.futures._set_result_unless_cancelled, future, None) # type: ignore[attr-defined]
526
+ except RuntimeError:
527
+ # close() can win the race after call_soon_threadsafe starts.
528
+ if not loop.is_closed(): # pragma: no cover - only a closed loop raises here
529
+ raise