Deprecate the ThreadGroup.cancel() API

This API is awkward, inefficient, incoherent, and unintuitive. The bug
fix for which it was originally added was abandoned in favour of a
different approach, so it was never used. It appears that no consumers
are currently calling it. It would be best if none started.

Add a deprecation warning to discourage its use and allow us to remove
it altogether at some point in the future.

Change-Id: I9559c7051024019fac957385faced645920b815c

oslo_service/threadgroup.py

@@ -16,6 +16,7 @@ import logging
 import threading
 import warnings
 
+from debtcollector import removals
 import eventlet
 from eventlet import greenpool
 
@@ -374,9 +375,14 @@ class ThreadGroup(object):
                 return True
         return False
 
+    @removals.remove(removal_version='?')
     def cancel(self, *throw_args, **kwargs):
         """Cancel unstarted threads in the group, and optionally stop the rest.
 
+        .. warning::
+            This method is deprecated and should not be used. It will be
+            removed in a future release.
+
         If called without the ``timeout`` argument, this does **not** stop any
         running threads, but prevents any threads in the group that have not
         yet started from running, then returns immediately. Timers are not

releasenotes/notes/threadgroup-cancel-bd89d72f383a3d9b.yaml

@@ -0,0 +1,5 @@
+---
+deprecations:
+  - |
+    The ``ThreadGroup.cancel()`` method is deprecated and will be removed in a
+    future major release.

requirements.txt

@@ -3,6 +3,7 @@
 # process, which may cause wedges in the gate later.
 
 WebOb>=1.7.1 # MIT
+debtcollector>=1.2.0 # Apache 2.0
 eventlet!=0.18.3,!=0.20.1,>=0.18.2 # MIT
 fixtures>=3.0.0 # Apache-2.0/BSD
 greenlet>=0.4.10 # MIT