MAINT: add main thread check for ui dispatch, solve no ui failure (#1740

)

Previously the ui_dispatch(handler, *args, **kw) function in
traits/traits/trait_notifiers.py only checks current_thread().ident with
ui_thread. But supposedly, this current thread id should be compared
with the main thread (threading.main_thread()). This discrepancy caused
a no ui failure in ui dispatch as mentioned in issue #1732. This PR
attempts to resolve this failure. Closes #1732

**Checklist**
- [ ] Tests
- [x] Update API reference (`docs/source/traits_api_reference`) (seems
no need to change for this PR)
- [ ] Update User manual (`docs/source/traits_user_manual`) (seems no
need to change for this PR)
- [x] Update type annotation hints in stub files (seems no need to
change for this PR)

---------

Co-authored-by: Chengyu Liu <[email protected]>
Co-authored-by: Mark Dickinson <[email protected]>

docs/source/traits_user_manual/notification.rst

@@ -257,8 +257,20 @@ Notification Handler
 --------------------
 
 By default, the **handler** is invoked immediately after the change has
-occurred. The **dispatch** parameter in |@observe| can be set such that the
-handler is dispatched elsewhere to be invoked later (e.g. on a GUI event loop).
+occurred. This behaviour can be changed using the **dispatch** parameter
+to the |@observe| method.
+
+The |@observe| method currently supports two values for the **dispatch**
+parameter: ``"same"`` and ``"ui"``. ``dispatch="same"`` corresponds to the
+default behaviour. When using ``dispatch="ui"``, the behaviour depends on the
+thread that triggered the observer. If the change that triggers the observer
+occurs on the main thread then the behaviour is the same as
+``dispatch="same"``: the observer is called immediately. However, if the change
+occurs on a thread other than the main thread then the observer is scheduled to
+be called on the UI thread, using the UI handler (if any) that has been set by
+the function :func:`~.set_ui_handler`. (Note: in normal use, this handler is
+set by Pyface as part of GUI selection; it's rare that the user needs to call
+:func:`~.set_ui_handler` directly.)
 
 The following expectations apply to any change handler:
 

traits/tests/test_trait_notifiers.py

@@ -0,0 +1,42 @@
+# (C) Copyright 2005-2023 Enthought, Inc., Austin, TX
+# All rights reserved.
+#
+# This software is provided without warranty under the terms of the BSD
+# license included in LICENSE.txt and may be redistributed only under
+# the conditions described in the aforementioned license. The license
+# is also available online at http://www.enthought.com/licenses/BSD.txt
+#
+# Thanks for using Enthought open source!
+
+import unittest
+
+from traits.api import HasTraits, Int
+
+
+class TestTraitNotifiers(unittest.TestCase):
+    def test_ui_dispatch(self):
+        # Given
+        class DispatchTest(HasTraits):
+            test_param = Int()
+
+        t = DispatchTest()
+
+        event_list = []
+
+        # create handler
+        def test_handler(event):
+            event_list.append(event)
+
+        # When
+        t.observe(test_handler, "test_param", dispatch="ui")
+        t.test_param = 1
+
+        # Then
+        # check the observer is called once
+        self.assertEqual(len(event_list), 1)
+        # check the name of the parameter change
+        self.assertEqual(event_list[0].name, "test_param")
+        # check whether the value starts at 0
+        self.assertEqual(event_list[0].old, 0)
+        # check whether the value has been set to 1
+        self.assertEqual(event_list[0].new, 1)

traits/trait_notifiers.py

@@ -44,7 +44,7 @@ def set_ui_handler(handler):
 
 
 def ui_dispatch(handler, *args, **kw):
-    if threading.current_thread().ident == ui_thread:
+    if threading.current_thread() == threading.main_thread():
         handler(*args, **kw)
     else:
         ui_handler(handler, *args, **kw)