tasktiger 0.26.3__tar.gz → 0.27.0__tar.gz

{tasktiger-0.26.3/tasktiger.egg-info → tasktiger-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasktiger
-Version: 0.26.3
+Version: 0.27.0
 Summary: Python task queue
 Home-page: http://github.com/closeio/tasktiger
 License: MIT
@@ -212,6 +212,18 @@ decorate and queue tasks. The constructor takes the following arguments:
     given queues (and their subqueues), unless explicit queues are passed to
     the command line.
 
+  - ``STATS_INTERVAL``
+
+    Interval in seconds between worker task runtime statistics (default: 60).
+    Set to 0 to disable the stats thread and its callbacks. Queue maintenance
+    can occupy a worker outside task-execution statistics. When enabled,
+    ``StatsThread.report_maintenance_start()`` and ``report_maintenance_end()``
+    bracket the combined scheduled-task promotion and expired-task recovery
+    pass, with the end callback called even if either operation raises.
+    The hooks allow custom instrumentation; their defaults are no-ops and do
+    not change task runtime or utilization statistics. No maintenance callbacks
+    run when maintenance is not due or the worker is stopping.
+
 - ``setup_structlog``
 
   If set to True, sets up structured logging using ``structlog`` when

{tasktiger-0.26.3 → tasktiger-0.27.0}/README.rst

@@ -182,6 +182,18 @@ decorate and queue tasks. The constructor takes the following arguments:
     given queues (and their subqueues), unless explicit queues are passed to
     the command line.
 
+  - ``STATS_INTERVAL``
+
+    Interval in seconds between worker task runtime statistics (default: 60).
+    Set to 0 to disable the stats thread and its callbacks. Queue maintenance
+    can occupy a worker outside task-execution statistics. When enabled,
+    ``StatsThread.report_maintenance_start()`` and ``report_maintenance_end()``
+    bracket the combined scheduled-task promotion and expired-task recovery
+    pass, with the end callback called even if either operation raises.
+    The hooks allow custom instrumentation; their defaults are no-ops and do
+    not change task runtime or utilization statistics. No maintenance callbacks
+    run when maintenance is not due or the worker is stopping.
+
 - ``setup_structlog``
 
   If set to True, sets up structured logging using ``structlog`` when

{tasktiger-0.26.3 → tasktiger-0.27.0}/tasktiger/__init__.py

@@ -12,7 +12,7 @@ from .task import Task
 from .tasktiger import TaskTiger, run_worker
 from .worker import Worker
 
-__version__ = "0.26.3"
+__version__ = "0.27.0"
 __all__ = [
     "TaskTiger",
     "Worker",

{tasktiger-0.26.3 → tasktiger-0.27.0}/tasktiger/stats.py

@@ -39,6 +39,18 @@ class StatsThread(threading.Thread):
             self._task_running = False
             self._task_start_time = None
 
+    def report_maintenance_start(self) -> None:
+        """Signal the start of scheduled-task promotion and expired-task recovery.
+
+        The default is a no-op and does not alter task statistics.
+        """
+
+    def report_maintenance_end(self) -> None:
+        """Signal the end of scheduled-task promotion and expired-task recovery.
+
+        The default is a no-op and does not alter task statistics.
+        """
+
     def compute_stats(self) -> None:
         now = time.monotonic()
 

{tasktiger-0.26.3 → tasktiger-0.27.0}/tasktiger/worker.py

@@ -867,9 +867,15 @@ class Worker:
             time.time() - self._last_task_check > self.config["SELECT_TIMEOUT"]
             and not self._stop_requested
         ):
-            self._worker_queue_scheduled_tasks()
-            self._worker_queue_expired_tasks()
-            self._last_task_check = time.time()
+            if self.stats_thread:
+                self.stats_thread.report_maintenance_start()
+            try:
+                self._worker_queue_scheduled_tasks()
+                self._worker_queue_expired_tasks()
+                self._last_task_check = time.time()
+            finally:
+                if self.stats_thread:
+                    self.stats_thread.report_maintenance_end()
 
     def _queue_periodic_tasks(self) -> None:
         # Only queue periodic tasks for queues this worker is responsible

{tasktiger-0.26.3 → tasktiger-0.27.0/tasktiger.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tasktiger
-Version: 0.26.3
+Version: 0.27.0
 Summary: Python task queue
 Home-page: http://github.com/closeio/tasktiger
 License: MIT
@@ -212,6 +212,18 @@ decorate and queue tasks. The constructor takes the following arguments:
     given queues (and their subqueues), unless explicit queues are passed to
     the command line.
 
+  - ``STATS_INTERVAL``
+
+    Interval in seconds between worker task runtime statistics (default: 60).
+    Set to 0 to disable the stats thread and its callbacks. Queue maintenance
+    can occupy a worker outside task-execution statistics. When enabled,
+    ``StatsThread.report_maintenance_start()`` and ``report_maintenance_end()``
+    bracket the combined scheduled-task promotion and expired-task recovery
+    pass, with the end callback called even if either operation raises.
+    The hooks allow custom instrumentation; their defaults are no-ops and do
+    not change task runtime or utilization statistics. No maintenance callbacks
+    run when maintenance is not due or the worker is stopping.
+
 - ``setup_structlog``
 
   If set to True, sets up structured logging using ``structlog`` when

{tasktiger-0.26.3 → tasktiger-0.27.0}/tests/test_workers.py

@@ -3,12 +3,15 @@
 import datetime
 import time
 from multiprocessing import Process
+from unittest import mock
 
+import pytest
 from freezefrog import FreezeTime
 
 from tasktiger import Task, Worker
 from tasktiger._internal import ACTIVE
 from tasktiger.executor import SyncExecutor
+from tasktiger.stats import StatsThread
 from tasktiger.worker import LOCK_REDIS_KEY
 
 from .config import DELAY
@@ -265,3 +268,37 @@ class TestSyncExecutorWorker:
         # handled by the executor, the task is still active until it times out
         # and gets requeued by another worker.
         ensure_queues(active={"default": 1})
+
+
+@pytest.mark.parametrize("failing_operation", [None, "scheduled", "expired"])
+def test_maintenance_stats_callbacks(tiger, monkeypatch, failing_operation):
+    worker = Worker(tiger)
+    worker._queue_set = set()
+    calls = mock.Mock()
+    calls.stats = mock.Mock(spec=StatsThread)
+    worker.stats_thread = calls.stats
+    monkeypatch.setattr(worker, "_worker_queue_scheduled_tasks", calls.scheduled)
+    monkeypatch.setattr(worker, "_worker_queue_expired_tasks", calls.expired)
+
+    if failing_operation:
+        getattr(calls, failing_operation).side_effect = RuntimeError("maintenance")
+        with pytest.raises(RuntimeError, match="maintenance"):
+            worker._worker_run()
+    else:
+        worker._worker_run()
+
+    expected = [mock.call.stats.report_maintenance_start(), mock.call.scheduled()]
+    if failing_operation != "scheduled":
+        expected.append(mock.call.expired())
+    expected.append(mock.call.stats.report_maintenance_end())
+    assert calls.mock_calls == expected
+
+
+def test_maintenance_without_stats(tiger, monkeypatch):
+    worker = Worker(tiger)
+    worker._queue_set = set()
+    calls = mock.Mock()
+    monkeypatch.setattr(worker, "_worker_queue_scheduled_tasks", calls.scheduled)
+    monkeypatch.setattr(worker, "_worker_queue_expired_tasks", calls.expired)
+    worker._worker_run()
+    assert calls.mock_calls == [mock.call.scheduled(), mock.call.expired()]