Document Pool close and terminate behavior

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()
 

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
 --------------