RAHHH

backend/lib/python3.12/site-packages/twisted/_threads/test/__init__.py

@@ -0,0 +1,7 @@
+# -*- test-case-name: twisted._threads.test -*-
+# Copyright (c) Twisted Matrix Laboratories.
+# See LICENSE for details.
+
+"""
+Tests for L{twisted._threads}.
+"""

backend/lib/python3.12/site-packages/twisted/_threads/test/test_convenience.py

@@ -0,0 +1,56 @@
+# Copyright (c) Twisted Matrix Laboratories.
+# See LICENSE for details.
+
+"""
+Test cases for convenience functionality in L{twisted._threads._convenience}.
+"""
+
+
+from twisted.trial.unittest import SynchronousTestCase
+from .._convenience import Quit
+from .._ithreads import AlreadyQuit
+
+
+class QuitTests(SynchronousTestCase):
+    """
+    Tests for L{Quit}
+    """
+
+    def test_isInitiallySet(self) -> None:
+        """
+        L{Quit.isSet} starts as L{False}.
+        """
+        quit = Quit()
+        self.assertEqual(quit.isSet, False)
+
+    def test_setSetsSet(self) -> None:
+        """
+        L{Quit.set} sets L{Quit.isSet} to L{True}.
+        """
+        quit = Quit()
+        quit.set()
+        self.assertEqual(quit.isSet, True)
+
+    def test_checkDoesNothing(self) -> None:
+        """
+        L{Quit.check} initially does nothing and returns L{None}.
+        """
+        quit = Quit()
+        checked = quit.check()  # type:ignore[func-returns-value]
+        self.assertIs(checked, None)
+
+    def test_checkAfterSetRaises(self) -> None:
+        """
+        L{Quit.check} raises L{AlreadyQuit} if L{Quit.set} has been called.
+        """
+        quit = Quit()
+        quit.set()
+        self.assertRaises(AlreadyQuit, quit.check)
+
+    def test_setTwiceRaises(self) -> None:
+        """
+        L{Quit.set} raises L{AlreadyQuit} if it has been called previously.
+        """
+        quit = Quit()
+        quit.set()
+        self.assertRaises(AlreadyQuit, quit.set)

backend/lib/python3.12/site-packages/twisted/_threads/test/test_memory.py

@@ -0,0 +1,64 @@
+# Copyright (c) Twisted Matrix Laboratories.
+# See LICENSE for details.
+
+"""
+Tests for L{twisted._threads._memory}.
+"""
+
+from zope.interface.verify import verifyObject
+
+from twisted.trial.unittest import SynchronousTestCase
+from .. import AlreadyQuit, IWorker, createMemoryWorker
+
+
+class MemoryWorkerTests(SynchronousTestCase):
+    """
+    Tests for L{MemoryWorker}.
+    """
+
+    def test_createWorkerAndPerform(self) -> None:
+        """
+        L{createMemoryWorker} creates an L{IWorker} and a callable that can
+        perform work on it.  The performer returns C{True} if it accomplished
+        useful work.
+        """
+        worker, performer = createMemoryWorker()
+        verifyObject(IWorker, worker)
+        done = []
+        worker.do(lambda: done.append(3))
+        worker.do(lambda: done.append(4))
+        self.assertEqual(done, [])
+        self.assertEqual(performer(), True)
+        self.assertEqual(done, [3])
+        self.assertEqual(performer(), True)
+        self.assertEqual(done, [3, 4])
+
+    def test_quitQuits(self) -> None:
+        """
+        Calling C{quit} on the worker returned by L{createMemoryWorker} causes
+        its C{do} and C{quit} methods to raise L{AlreadyQuit}; its C{perform}
+        callable will start raising L{AlreadyQuit} when the work already
+        provided to C{do} has been exhausted.
+        """
+        worker, performer = createMemoryWorker()
+        done = []
+
+        def moreWork() -> None:
+            done.append(7)
+
+        worker.do(moreWork)
+        worker.quit()
+        self.assertRaises(AlreadyQuit, worker.do, moreWork)
+        self.assertRaises(AlreadyQuit, worker.quit)
+        performer()
+        self.assertEqual(done, [7])
+        self.assertEqual(performer(), False)
+
+    def test_performWhenNothingToDoYet(self) -> None:
+        """
+        The C{perform} callable returned by L{createMemoryWorker} will return
+        no result when there's no work to do yet.  Since there is no work to
+        do, the performer returns C{False}.
+        """
+        worker, performer = createMemoryWorker()
+        self.assertEqual(performer(), False)

backend/lib/python3.12/site-packages/twisted/_threads/test/test_team.py

@@ -0,0 +1,286 @@
+# Copyright (c) Twisted Matrix Laboratories.
+# See LICENSE for details.
+
+"""
+Tests for L{twisted._threads._team}.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from twisted.python.components import proxyForInterface
+from twisted.python.context import call, get
+from twisted.python.failure import Failure
+from twisted.trial.unittest import SynchronousTestCase
+from .. import AlreadyQuit, IWorker, Team, createMemoryWorker
+
+
+class ContextualWorker(proxyForInterface(IWorker, "_realWorker")):  # type: ignore[misc]
+    """
+    A worker implementation that supplies a context.
+    """
+
+    def __init__(self, realWorker: IWorker, **ctx: object) -> None:
+        """
+        Create with a real worker and a context.
+        """
+        self._realWorker = realWorker
+        self._context = ctx
+
+    def do(self, work: Callable[[], object]) -> None:
+        """
+        Perform the given work with the context given to __init__.
+
+        @param work: the work to pass on to the real worker.
+        """
+        super().do(lambda: call(self._context, work))
+
+
+class TeamTests(SynchronousTestCase):
+    """
+    Tests for L{Team}
+    """
+
+    def setUp(self) -> None:
+        """
+        Set up a L{Team} with inspectable, synchronous workers that can be
+        single-stepped.
+        """
+        coordinator, self.coordinateOnce = createMemoryWorker()
+        self.coordinator = ContextualWorker(coordinator, worker="coordinator")
+        self.workerPerformers: list[Callable[[], object]] = []
+        self.allWorkersEver: list[ContextualWorker] = []
+        self.allUnquitWorkers: list[ContextualWorker] = []
+        self.activePerformers: list[Callable[[], object]] = []
+        self.noMoreWorkers = lambda: False
+
+        def createWorker() -> ContextualWorker | None:
+            if self.noMoreWorkers():
+                return None
+            worker, performer = createMemoryWorker()
+            self.workerPerformers.append(performer)
+            self.activePerformers.append(performer)
+            cw = ContextualWorker(worker, worker=len(self.workerPerformers))
+            self.allWorkersEver.append(cw)
+            self.allUnquitWorkers.append(cw)
+            realQuit = cw.quit
+
+            def quitAndRemove() -> None:
+                realQuit()
+                self.allUnquitWorkers.remove(cw)
+                self.activePerformers.remove(performer)
+
+            cw.quit = quitAndRemove
+            return cw
+
+        self.failures: list[Failure] = []
+
+        def logException() -> None:
+            self.failures.append(Failure())
+
+        self.team = Team(coordinator, createWorker, logException)
+
+    def coordinate(self) -> bool:
+        """
+        Perform all work currently scheduled in the coordinator.
+
+        @return: whether any coordination work was performed; if the
+            coordinator was idle when this was called, return L{False}
+            (otherwise L{True}).
+        """
+        did = False
+        while self.coordinateOnce():
+            did = True
+        return did
+
+    def performAllOutstandingWork(self) -> None:
+        """
+        Perform all work on the coordinator and worker performers that needs to
+        be done.
+        """
+        continuing = True
+        while continuing:
+            continuing = self.coordinate()
+            for performer in self.workerPerformers:
+                if performer in self.activePerformers:
+                    performer()
+            continuing = continuing or self.coordinate()
+
+    def test_doDoesWorkInWorker(self) -> None:
+        """
+        L{Team.do} does the work in a worker created by the createWorker
+        callable.
+        """
+        who = None
+
+        def something() -> None:
+            nonlocal who
+            who = get("worker")
+
+        self.team.do(something)
+        self.coordinate()
+        self.assertEqual(self.team.statistics().busyWorkerCount, 1)
+        self.performAllOutstandingWork()
+        self.assertEqual(who, 1)
+        self.assertEqual(self.team.statistics().busyWorkerCount, 0)
+
+    def test_initialStatistics(self) -> None:
+        """
+        L{Team.statistics} returns an object with idleWorkerCount,
+        busyWorkerCount, and backloggedWorkCount integer attributes.
+        """
+        stats = self.team.statistics()
+        self.assertEqual(stats.idleWorkerCount, 0)
+        self.assertEqual(stats.busyWorkerCount, 0)
+        self.assertEqual(stats.backloggedWorkCount, 0)
+
+    def test_growCreatesIdleWorkers(self) -> None:
+        """
+        L{Team.grow} increases the number of available idle workers.
+        """
+        self.team.grow(5)
+        self.performAllOutstandingWork()
+        self.assertEqual(len(self.workerPerformers), 5)
+
+    def test_growCreateLimit(self) -> None:
+        """
+        L{Team.grow} increases the number of available idle workers until the
+        C{createWorker} callable starts returning None.
+        """
+        self.noMoreWorkers = lambda: len(self.allWorkersEver) >= 3
+        self.team.grow(5)
+        self.performAllOutstandingWork()
+        self.assertEqual(len(self.allWorkersEver), 3)
+        self.assertEqual(self.team.statistics().idleWorkerCount, 3)
+
+    def test_shrinkQuitsWorkers(self) -> None:
+        """
+        L{Team.shrink} will quit the given number of workers.
+        """
+        self.team.grow(5)
+        self.performAllOutstandingWork()
+        self.team.shrink(3)
+        self.performAllOutstandingWork()
+        self.assertEqual(len(self.allUnquitWorkers), 2)
+
+    def test_shrinkToZero(self) -> None:
+        """
+        L{Team.shrink} with no arguments will stop all outstanding workers.
+        """
+        self.team.grow(10)
+        self.performAllOutstandingWork()
+        self.assertEqual(len(self.allUnquitWorkers), 10)
+        self.team.shrink()
+        self.assertEqual(len(self.allUnquitWorkers), 10)
+        self.performAllOutstandingWork()
+        self.assertEqual(len(self.allUnquitWorkers), 0)
+
+    def test_moreWorkWhenNoWorkersAvailable(self) -> None:
+        """
+        When no additional workers are available, the given work is backlogged,
+        and then performed later when the work was.
+        """
+        self.team.grow(3)
+        self.coordinate()
+        times = 0
+
+        def something() -> None:
+            nonlocal times
+            times += 1
+
+        self.assertEqual(self.team.statistics().idleWorkerCount, 3)
+        for i in range(3):
+            self.team.do(something)
+        # Make progress on the coordinator but do _not_ actually complete the
+        # work, yet.
+        self.coordinate()
+        self.assertEqual(self.team.statistics().idleWorkerCount, 0)
+        self.noMoreWorkers = lambda: True
+        self.team.do(something)
+        self.coordinate()
+        self.assertEqual(self.team.statistics().idleWorkerCount, 0)
+        self.assertEqual(self.team.statistics().backloggedWorkCount, 1)
+        self.performAllOutstandingWork()
+        self.assertEqual(self.team.statistics().backloggedWorkCount, 0)
+        self.assertEqual(times, 4)
+
+    def test_exceptionInTask(self) -> None:
+        """
+        When an exception is raised in a task passed to L{Team.do}, the
+        C{logException} given to the L{Team} at construction is invoked in the
+        exception context.
+        """
+        self.team.do(lambda: 1 / 0)
+        self.performAllOutstandingWork()
+        self.assertEqual(len(self.failures), 1)
+        self.assertEqual(self.failures[0].type, ZeroDivisionError)
+
+    def test_quit(self) -> None:
+        """
+        L{Team.quit} causes future invocations of L{Team.do} and L{Team.quit}
+        to raise L{AlreadyQuit}.
+        """
+        self.team.quit()
+        self.assertRaises(AlreadyQuit, self.team.quit)
+        self.assertRaises(AlreadyQuit, self.team.do, list)
+
+    def test_quitQuits(self) -> None:
+        """
+        L{Team.quit} causes all idle workers, as well as the coordinator
+        worker, to quit.
+        """
+        for x in range(10):
+            self.team.do(list)
+        self.performAllOutstandingWork()
+        self.team.quit()
+        self.performAllOutstandingWork()
+        self.assertEqual(len(self.allUnquitWorkers), 0)
+        self.assertRaises(AlreadyQuit, self.coordinator.quit)
+
+    def test_quitQuitsLaterWhenBusy(self) -> None:
+        """
+        L{Team.quit} causes all busy workers to be quit once they've finished
+        the work they've been given.
+        """
+        self.team.grow(10)
+        for x in range(5):
+            self.team.do(list)
+        self.coordinate()
+        self.team.quit()
+        self.coordinate()
+        self.assertEqual(len(self.allUnquitWorkers), 5)
+        self.performAllOutstandingWork()
+        self.assertEqual(len(self.allUnquitWorkers), 0)
+        self.assertRaises(AlreadyQuit, self.coordinator.quit)
+
+    def test_quitConcurrentWithWorkHappening(self) -> None:
+        """
+        If work happens after L{Team.quit} sets its C{Quit} flag, but before
+        any other work takes place, the L{Team} should still exit gracefully.
+        """
+        self.team.do(list)
+        originalSet = self.team._quit.set
+
+        def performWorkConcurrently() -> None:
+            originalSet()
+            self.performAllOutstandingWork()
+
+        self.team._quit.set = performWorkConcurrently  # type:ignore[method-assign]
+        self.team.quit()
+        self.assertRaises(AlreadyQuit, self.team.quit)
+        self.assertRaises(AlreadyQuit, self.team.do, list)
+
+    def test_shrinkWhenBusy(self) -> None:
+        """
+        L{Team.shrink} will wait for busy workers to finish being busy and then
+        quit them.
+        """
+        for x in range(10):
+            self.team.do(list)
+        self.coordinate()
+        self.assertEqual(len(self.allUnquitWorkers), 10)
+        # There should be 10 busy workers at this point.
+        self.team.shrink(7)
+        self.performAllOutstandingWork()
+        self.assertEqual(len(self.allUnquitWorkers), 3)

backend/lib/python3.12/site-packages/twisted/_threads/test/test_threadworker.py

@@ -0,0 +1,314 @@
+# Copyright (c) Twisted Matrix Laboratories.
+# See LICENSE for details.
+
+"""
+Tests for L{twisted._threads._threadworker}.
+"""
+
+from __future__ import annotations
+
+import gc
+import weakref
+from threading import ThreadError, local
+from typing import Callable, Generic, TypeVar
+
+from twisted.trial.unittest import SynchronousTestCase
+from .. import AlreadyQuit, LockWorker, ThreadWorker
+from .._threadworker import SimpleLock
+
+T = TypeVar("T")
+
+
+class FakeQueueEmpty(Exception):
+    """
+    L{FakeQueue}'s C{get} has exhausted the queue.
+    """
+
+
+class WouldDeadlock(Exception):
+    """
+    If this were a real lock, you'd be deadlocked because the lock would be
+    double-acquired.
+    """
+
+
+class FakeThread:
+    """
+    A fake L{threading.Thread}.
+
+    @ivar target: A target function to run.
+
+    @ivar started: Has this thread been started?
+    @type started: L{bool}
+    """
+
+    def __init__(self, target: Callable[[], object]) -> None:
+        """
+        Create a L{FakeThread} with a target.
+        """
+        self.target = target
+        self.started = False
+
+    def start(self) -> None:
+        """
+        Set the "started" flag.
+        """
+        self.started = True
+
+
+class FakeQueue(Generic[T]):
+    """
+    A fake L{Queue} implementing C{put} and C{get}.
+
+    @ivar items: A lit of items placed by C{put} but not yet retrieved by
+        C{get}.
+    @type items: L{list}
+    """
+
+    def __init__(self) -> None:
+        """
+        Create a L{FakeQueue}.
+        """
+        self.items: list[T] = []
+
+    def put(self, item: T) -> None:
+        """
+        Put an item into the queue for later retrieval by L{FakeQueue.get}.
+
+        @param item: any object
+        """
+        self.items.append(item)
+
+    def get(self) -> T:
+        """
+        Get an item.
+
+        @return: an item previously put by C{put}.
+        """
+        if not self.items:
+            raise FakeQueueEmpty()
+        return self.items.pop(0)
+
+
+class FakeLock:
+    """
+    A stand-in for L{threading.Lock}.
+
+    @ivar acquired: Whether this lock is presently acquired.
+    """
+
+    def __init__(self) -> None:
+        """
+        Create a lock in the un-acquired state.
+        """
+        self.acquired = False
+
+    def acquire(self) -> bool:
+        """
+        Acquire the lock.  Raise an exception if the lock is already acquired.
+        """
+        if self.acquired:
+            raise WouldDeadlock()
+        self.acquired = True
+        return True
+
+    def release(self) -> None:
+        """
+        Release the lock.  Raise an exception if the lock is not presently
+        acquired.
+        """
+        if not self.acquired:
+            raise ThreadError()
+        self.acquired = False
+
+
+class ThreadWorkerTests(SynchronousTestCase):
+    """
+    Tests for L{ThreadWorker}.
+    """
+
+    def setUp(self) -> None:
+        """
+        Create a worker with fake threads.
+        """
+        self.fakeThreads: list[FakeThread] = []
+
+        def startThread(target: Callable[[], object]) -> FakeThread:
+            newThread = FakeThread(target=target)
+            newThread.start()
+            self.fakeThreads.append(newThread)
+            return newThread
+
+        self.worker = ThreadWorker(startThread, FakeQueue())
+
+    def test_startsThreadAndPerformsWork(self) -> None:
+        """
+        L{ThreadWorker} calls its C{createThread} callable to create a thread,
+        its C{createQueue} callable to create a queue, and then the thread's
+        target pulls work from that queue.
+        """
+        self.assertEqual(len(self.fakeThreads), 1)
+        self.assertEqual(self.fakeThreads[0].started, True)
+
+        done = False
+
+        def doIt() -> None:
+            nonlocal done
+            done = True
+
+        self.worker.do(doIt)
+        self.assertEqual(done, False)
+        self.assertRaises(FakeQueueEmpty, self.fakeThreads[0].target)
+        self.assertEqual(done, True)
+
+    def test_quitPreventsFutureCalls(self) -> None:
+        """
+        L{ThreadWorker.quit} causes future calls to L{ThreadWorker.do} and
+        L{ThreadWorker.quit} to raise L{AlreadyQuit}.
+        """
+        self.worker.quit()
+        self.assertRaises(AlreadyQuit, self.worker.quit)
+        self.assertRaises(AlreadyQuit, self.worker.do, list)
+
+
+class LockWorkerTests(SynchronousTestCase):
+    """
+    Tests for L{LockWorker}.
+    """
+
+    def test_fakeDeadlock(self) -> None:
+        """
+        The L{FakeLock} test fixture will alert us if there's a potential
+        deadlock.
+        """
+        lock = FakeLock()
+        lock.acquire()
+        self.assertRaises(WouldDeadlock, lock.acquire)
+
+    def test_fakeDoubleRelease(self) -> None:
+        """
+        The L{FakeLock} test fixture will alert us if there's a potential
+        double-release.
+        """
+        lock = FakeLock()
+        self.assertRaises(ThreadError, lock.release)
+        lock.acquire()
+        noResult = lock.release()  # type:ignore[func-returns-value]
+        self.assertIs(None, noResult)
+        self.assertRaises(ThreadError, lock.release)
+
+    def test_doExecutesImmediatelyWithLock(self) -> None:
+        """
+        L{LockWorker.do} immediately performs the work it's given, while the
+        lock is acquired.
+        """
+        storage = local()
+        lock = FakeLock()
+        worker = LockWorker(lock, storage)
+        done = False
+        acquired = False
+
+        def work() -> None:
+            nonlocal done, acquired
+            done = True
+            acquired = lock.acquired
+
+        worker.do(work)
+        self.assertEqual(done, True)
+        self.assertEqual(acquired, True)
+        self.assertEqual(lock.acquired, False)
+
+    def test_doUnwindsReentrancy(self) -> None:
+        """
+        If L{LockWorker.do} is called recursively, it postpones the inner call
+        until the outer one is complete.
+        """
+        lock = FakeLock()
+        worker = LockWorker(lock, local())
+        levels = []
+        acquired = []
+        level = 0
+
+        def work() -> None:
+            nonlocal level
+            level += 1
+            levels.append(level)
+            acquired.append(lock.acquired)
+            if len(levels) < 2:
+                worker.do(work)
+            level -= 1
+
+        worker.do(work)
+        self.assertEqual(levels, [1, 1])
+        self.assertEqual(acquired, [True, True])
+
+    def test_quit(self) -> None:
+        """
+        L{LockWorker.quit} frees the resources associated with its lock and
+        causes further calls to C{do} and C{quit} to fail.
+        """
+        lock = FakeLock()
+        ref = weakref.ref(lock)
+        worker = LockWorker(lock, local())
+        del lock
+        self.assertIsNot(ref(), None)
+        worker.quit()
+        gc.collect()
+        self.assertIs(ref(), None)
+        self.assertRaises(AlreadyQuit, worker.quit)
+        self.assertRaises(AlreadyQuit, worker.do, list)
+
+    def test_quitWhileWorking(self) -> None:
+        """
+        If L{LockWorker.quit} is invoked during a call to L{LockWorker.do}, all
+        recursive work scheduled with L{LockWorker.do} will be completed and
+        the lock will be released.
+        """
+        lock = FakeLock()
+        ref = weakref.ref(lock)
+        worker = LockWorker(lock, local())
+
+        phase1complete = False
+        phase2complete = False
+        phase2acquired = None
+
+        def phase1() -> None:
+            nonlocal phase1complete
+            worker.do(phase2)
+            worker.quit()
+            self.assertRaises(AlreadyQuit, worker.do, list)
+            phase1complete = True
+
+        def phase2() -> None:
+            nonlocal phase2complete, phase2acquired, lock
+            phase2complete = True
+            phase2acquired = lock.acquired
+
+        worker.do(phase1)
+        self.assertEqual(phase1complete, True)
+        self.assertEqual(phase2complete, True)
+        self.assertEqual(lock.acquired, False)
+        del lock
+        gc.collect()
+        self.assertIs(ref(), None)
+
+    def test_quitWhileGettingLock(self) -> None:
+        """
+        If L{LockWorker.do} is called concurrently with L{LockWorker.quit}, and
+        C{quit} wins the race before C{do} gets the lock attribute, then
+        L{AlreadyQuit} will be raised.
+        """
+
+        class RacyLockWorker(LockWorker):
+            @property
+            def _lock(self) -> SimpleLock | None:
+                self.quit()
+                it: SimpleLock = self.__dict__["_lock"]
+                return it
+
+            @_lock.setter
+            def _lock(self, value: SimpleLock | None) -> None:
+                self.__dict__["_lock"] = value
+
+        worker = RacyLockWorker(FakeLock(), local())
+        self.assertRaises(AlreadyQuit, worker.do, list)