Browse Source

Add better timer APIs to ThreadGroup

The ThreadGroup.add_timer() API is unintuitive, inflexible, and all
around pretty terrible. By allowing the caller to pass *args and
**kwargs, it strongly implies that you can write a wrapper like:

    def add_timer(self, interval, func, *args, **kwargs):
        self.group.add_timer(interval, func, *args, **kwargs)

and in fact at least 6 projects have done so (probably copying and
pasting from each other). But this is wrong, and will result in the
first positional arg intended for the callback function to be treated as
the initial_delay parameter and dropped from the list of arguments to be
passed to the callback when it is run. When called like this, the
initial_delay argument not only must be passed (preventing the caller
from relying on the default), interspersed between the callback function
and its arguments, but it must be passed as a positional and not a
keyword argument (preventing the caller from effectively documenting
what is going on):

        self.group.add_timer(interval, func, None, *args, **kwargs)

We are also unable to add any further options without breaking existing
consumers.

To improve the situation in the future, add a new add_timer_args() API
that takes the args and kwargs as individual sequence/mapping parameters
rather than as variadic parameters. The above call would become:

        self.group.add_timer_args(interval, func, args, kwargs)

and any optional parameters can be passed as keyword arguments. Any new
keyword arguments we might want to add can be safely added to this
method.

Calling the original add_timer() method with arguments (either
positional or keyword) intended for the callback function is now
deprecated. Those parameters could be removed in a future major release.

Change-Id: Ib2791342263e2b88c045bcc92adc8160f57a0ed6
Zane Bitter 4 months ago
parent
commit
750b51caaa

+ 43
- 0
oslo_service/tests/test_threadgroup.py View File

@@ -49,6 +49,49 @@ class ThreadGroupTestCase(test_base.BaseTestCase):
49 49
         self.assertEqual(('arg',), timer.args)
50 50
         self.assertEqual({'kwarg': 'kwarg'}, timer.kw)
51 51
 
52
+    def test_add_dynamic_timer_args(self):
53
+        def foo(*args, **kwargs):
54
+            pass
55
+
56
+        self.tg.add_dynamic_timer_args(foo, ['arg'], {'kwarg': 'kwarg'},
57
+                                       initial_delay=1,
58
+                                       periodic_interval_max=2)
59
+
60
+        self.assertEqual(1, len(self.tg.timers))
61
+
62
+        timer = self.tg.timers[0]
63
+        self.assertTrue(timer._running)
64
+        self.assertEqual(('arg',), timer.args)
65
+        self.assertEqual({'kwarg': 'kwarg'}, timer.kw)
66
+
67
+    def test_add_timer(self):
68
+        def foo(*args, **kwargs):
69
+            pass
70
+
71
+        self.tg.add_timer(1, foo, 1,
72
+                          'arg', kwarg='kwarg')
73
+
74
+        self.assertEqual(1, len(self.tg.timers))
75
+
76
+        timer = self.tg.timers[0]
77
+        self.assertTrue(timer._running)
78
+        self.assertEqual(('arg',), timer.args)
79
+        self.assertEqual({'kwarg': 'kwarg'}, timer.kw)
80
+
81
+    def test_add_timer_args(self):
82
+        def foo(*args, **kwargs):
83
+            pass
84
+
85
+        self.tg.add_timer_args(1, foo, ['arg'], {'kwarg': 'kwarg'},
86
+                               initial_delay=1)
87
+
88
+        self.assertEqual(1, len(self.tg.timers))
89
+
90
+        timer = self.tg.timers[0]
91
+        self.assertTrue(timer._running)
92
+        self.assertEqual(('arg',), timer.args)
93
+        self.assertEqual({'kwarg': 'kwarg'}, timer.kw)
94
+
52 95
     def test_stop_current_thread(self):
53 96
 
54 97
         stop_event = event.Event()

+ 27
- 0
oslo_service/threadgroup.py View File

@@ -14,6 +14,7 @@
14 14
 
15 15
 import logging
16 16
 import threading
17
+import warnings
17 18
 
18 19
 import eventlet
19 20
 from eventlet import greenpool
@@ -77,6 +78,20 @@ class ThreadGroup(object):
77 78
 
78 79
     def add_dynamic_timer(self, callback, initial_delay=None,
79 80
                           periodic_interval_max=None, *args, **kwargs):
81
+        if args or kwargs:
82
+            warnings.warn("Calling add_dynamic_timer() with arguments to the "
83
+                          "callback function is deprecated. Use "
84
+                          "add_dynamic_timer_args() instead.",
85
+                          DeprecationWarning)
86
+        return self.add_dynamic_timer_args(
87
+            callback, args, kwargs,
88
+            initial_delay=initial_delay,
89
+            periodic_interval_max=periodic_interval_max)
90
+
91
+    def add_dynamic_timer_args(self, callback, args=None, kwargs=None,
92
+                               initial_delay=None, periodic_interval_max=None):
93
+        args = args or []
94
+        kwargs = kwargs or {}
80 95
         timer = loopingcall.DynamicLoopingCall(callback, *args, **kwargs)
81 96
         timer.start(initial_delay=initial_delay,
82 97
                     periodic_interval_max=periodic_interval_max)
@@ -85,6 +100,18 @@ class ThreadGroup(object):
85 100
 
86 101
     def add_timer(self, interval, callback, initial_delay=None,
87 102
                   *args, **kwargs):
103
+        if args or kwargs:
104
+            warnings.warn("Calling add_timer() with arguments to the callback "
105
+                          "function is deprecated. Use add_timer_args() "
106
+                          "instead.",
107
+                          DeprecationWarning)
108
+        return self.add_timer_args(interval, callback, args, kwargs,
109
+                                   initial_delay=initial_delay)
110
+
111
+    def add_timer_args(self, interval, callback, args=None, kwargs=None,
112
+                       initial_delay=None):
113
+        args = args or []
114
+        kwargs = kwargs or {}
88 115
         pulse = loopingcall.FixedIntervalLoopingCall(callback, *args, **kwargs)
89 116
         pulse.start(interval=interval,
90 117
                     initial_delay=initial_delay)

+ 15
- 0
releasenotes/notes/timer-args-f578c8f9d08b217d.yaml View File

@@ -0,0 +1,15 @@
1
+---
2
+features:
3
+  - |
4
+    The ThreadGroup class has new add_timer_args() and add_dynamic_timer_args()
5
+    methods to create timers passing the positional and keyword arguments to
6
+    the callback as a sequence and a mapping. This API provides more
7
+    flexibility for the addition of timer control options in the future.
8
+deprecations:
9
+  - |
10
+    The API of the ThreadGroup add_timer() and add_dynamic_timer() methods has
11
+    been identified as error-prone when passing arguments intended for the
12
+    callback function. Passing callback arguments in this way is now
13
+    deprecated. Callers should use the new add_timer_args() or
14
+    add_dynamic_timer_args() methods (respectively) instead when it is
15
+    necessary to pass arguments to the timer callback function.

Loading…
Cancel
Save