diff --git a/aiomultiprocess/pool.py b/aiomultiprocess/pool.py index 93e7603..e1432d9 100644 --- a/aiomultiprocess/pool.py +++ b/aiomultiprocess/pool.py @@ -357,14 +357,26 @@ def starmap( return PoolResult(self, tids) def close(self) -> None: - """Close the pool to new visitors.""" + """ + Close the pool to new jobs. + + Pending jobs keep running, and worker processes stop gracefully once + their queues have been drained. Await :meth:`join` after calling this + method to wait for the worker processes to exit. + """ self.running = False for qid in self.processes.values(): tx, _ = self.queues[qid] tx.put_nowait(None) def terminate(self) -> None: - """No running by the pool!""" + """ + Terminate all worker processes immediately. + + This stops workers without waiting for queued or in-flight jobs to + finish. Pending result objects may not complete, so this should be + reserved for shutdown paths that cannot wait for graceful completion. + """ if self.running: self.close() diff --git a/docs/guide.rst b/docs/guide.rst index 33b5c82..c6bc5a8 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -98,6 +98,22 @@ order as the inputs:: async for value in pool.map(math.sqrt, data): ... +Pools can also be closed manually when they are not used as asynchronous +context managers. Calling ``close()`` prevents new jobs from being queued and +asks worker processes to stop once their current queues have been drained. Use +``await join()`` after ``close()`` to wait for those workers to exit +gracefully:: + + pool = Pool() + results = await pool.map(math.sqrt, data) + pool.close() + await pool.join() + +Calling ``terminate()`` stops worker processes immediately instead of waiting +for queued or in-flight jobs to finish. Pending result objects may not complete, +so ``terminate()`` is best reserved for shutdown paths that cannot wait for a +graceful ``close()`` and ``join()`` cycle. + Advanced Usage --------------