diff --git a/changes/noissue.23.feature.rst b/changes/noissue.23.feature.rst new file mode 100644 index 00000000..cfd2f579 --- /dev/null +++ b/changes/noissue.23.feature.rst @@ -0,0 +1,3 @@ +Added a `stop_event` parameter to the :meth:`zhmcclient.NotificationReceiver.notifications` +method that allows stopping the iterations over the HMC notifications if the event +gets set. diff --git a/zhmcclient/_notification.py b/zhmcclient/_notification.py index 66f999a4..bd6af86c 100755 --- a/zhmcclient/_notification.py +++ b/zhmcclient/_notification.py @@ -582,7 +582,7 @@ def get_subscription(self, topic_name): return self._id_value(sub_id) @logged_api_call - def notifications(self): + def notifications(self, stop_event=None): """ Generator method that yields all HMC notifications (= JMS messages) received by this notification receiver. @@ -597,9 +597,19 @@ def notifications(self): thread; any errors do not cause the method to return but always cause an exception to be raised. + If a stop event is provided, the method performs checking for a stop. + This is done by testing whether the stop event is set. If so, this + method returns and the iteration of the caller on this method will end. + For an example how to use this method, see :ref:`Notifications` or the example scripts. + Parameters: + + stop_event (threading.Event): Stop event that is checked. This can + be used to end the iteration over the HMC notifications. + If None, no stop checking is performed. + Yields: : A tuple (headers, message) representing one HMC notification, with: @@ -638,10 +648,6 @@ def notifications(self): formats" in chapter 4. "Asynchronous notification" in the :term:`HMC API` book. - Returns: - - None - Raises: :exc:`~zhmcclient.NotificationJMSError`: Received JMS error from @@ -678,6 +684,10 @@ def notifications(self): try: item = self._handover_queue.get(timeout=ho_get_timeout) except queue.Empty: + + if stop_event and stop_event.is_set(): + break + # This check detects a disconnect only when heartbeating is # enabled in the stomp retry/timeout configuration. if not self._conn.is_connected(): @@ -686,6 +696,12 @@ def notifications(self): continue break + if stop_event and stop_event.is_set(): + # This will cause the generator to return to Python. Python + # will raise StopIteration, and the user loop on this method + # will simply end. + break + # Now we have an item from the listener if item.msgtype == 'message': if item.message is None: