fix(setup_helpers): ensure ThreadPool is closed (#3548)

* Ensure ThreadPool is closed in setup_helpers

The ParallelCompile setup helper using a ThreadPool to enable its
parallelism. It does not properly close the pool when it is done with
it.
This can lead to a "Exception ignored in: <function Pool.__del__..."
message with traceback being printed at shutdown.
Use pool.terminate() instead of context manager for Python 2.7
compatibility

* Add note to remove code that supports Python 2

Co-authored-by: Bobby Impollonia <bobby@k13capital.com>

pybind11/setup_helpers.py

@@ -466,8 +466,14 @@ class ParallelCompile(object):
                     threads = 1
 
             if threads > 1:
-                for _ in ThreadPool(threads).imap_unordered(_single_compile, objects):
+                pool = ThreadPool(threads)
+                # In Python 2, ThreadPool can't be used as a context manager.
+                # Once we are no longer supporting it, this can be 'with pool:'
+                try:
+                    for _ in pool.imap_unordered(_single_compile, objects):
                         pass
+                finally:
+                    pool.terminate()
             else:
                 for ob in objects:
                     _single_compile(ob)