From fef1c1543b03aebac1141dc03248eff5b537fb95 Mon Sep 17 00:00:00 2001
From: Zane Bitter <zbitter@redhat.com>
Date: Wed, 12 Dec 2018 19:53:11 +1300
Subject: [PATCH] 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                                 | 6 ++++++
 releasenotes/notes/threadgroup-cancel-bd89d72f383a3d9b.yaml | 5 +++++
 requirements.txt                                            | 1 +
 3 files changed, 12 insertions(+)
 create mode 100644 releasenotes/notes/threadgroup-cancel-bd89d72f383a3d9b.yaml

diff --git a/oslo_service/threadgroup.py b/oslo_service/threadgroup.py
index e57efb52..51a0711c 100644
--- a/oslo_service/threadgroup.py
+++ b/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
diff --git a/releasenotes/notes/threadgroup-cancel-bd89d72f383a3d9b.yaml b/releasenotes/notes/threadgroup-cancel-bd89d72f383a3d9b.yaml
new file mode 100644
index 00000000..b37c925f
--- /dev/null
+++ b/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.
diff --git a/requirements.txt b/requirements.txt
index 4afebff0..ecca3594 100644
--- a/requirements.txt
+++ b/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