Rename ITaskSpecification.background_task to ITaskSpecification.task (#…

…425)

docs/source/changes.rst

@@ -39,6 +39,10 @@ of Traits Futures.
   background task types.
 * The ``state`` trait of the ``~.TraitsExecutor`` is now read-only;
   previously, it was writable.
+* The ``ITaskSpecification.background_task`` method has been renamed to
+  ``task``.
+* The ``ITaskSpecification.future`` method now requires a cancellation callback
+  to be passed.
 
 Other Changes
 ~~~~~~~~~~~~~

docs/source/guide/advanced.rst

@@ -128,9 +128,9 @@ Putting it all together: the task specification
 
 The last piece we need is a task specification, which is the object that can be
 submitted to the |TraitsExecutor|. This object needs to have two attributes:
-``future`` and ``background_task``. Given an instance ``task`` of a task
+``future`` and ``task``. Given an instance ``task`` of a task
 specification, the |TraitsExecutor| calls ``task.future(cancel)``
-to create the future, and ``task.background_task()`` to create the background
+to create the future, and ``task.task()`` to create the background
 callable. For the background task, we want to return (but not call!) the
 ``fizz_buzz`` function that we defined above. For the future, we create and
 return a new ``FizzBuzzFuture`` instance. So our task specification

docs/source/guide/examples/fizz_buzz_task.py

@@ -133,7 +133,7 @@ def future(self, cancel):
         """
         return FizzBuzzFuture(_cancel=cancel)
 
-    def background_task(self):
+    def task(self):
         """
         Return a background callable for this task specification.
 

traits_futures/background_call.py

@@ -72,7 +72,7 @@ def future(self, cancel):
         """
         return CallFuture(_cancel=cancel)
 
-    def background_task(self):
+    def task(self):
         """
         Return a background callable for this task specification.
 

traits_futures/background_iteration.py

@@ -100,7 +100,7 @@ def future(self, cancel):
         """
         return IterationFuture(_cancel=cancel)
 
-    def background_task(self):
+    def task(self):
         """
         Return a background callable for this task specification.
 

traits_futures/background_progress.py

@@ -146,7 +146,7 @@ def future(self, cancel):
         """
         return ProgressFuture(_cancel=cancel)
 
-    def background_task(self):
+    def task(self):
         """
         Return a background callable for this task specification.
 

traits_futures/i_task_specification.py

@@ -28,7 +28,7 @@ class ITaskSpecification(ABC):
     """
 
     @abstractmethod
-    def background_task(self):
+    def task(self):
         """
         Return the callable that will be invoked as the background task.
 

traits_futures/traits_executor.py

@@ -303,7 +303,7 @@ def submit(self, task):
         cancel_event = self._context.event()
 
         sender, receiver = self._message_router.pipe()
-        runner = task.background_task()
+        runner = task.task()
         future = task.future(cancel_event.set)
 
         self._worker_pool.submit(

traits_futures/wrappers.py

@@ -52,13 +52,13 @@ def _dispatch_to_future(self, event):
             self.done = True
 
 
-def run_background_task(background_task, sender, cancelled):
+def run_background_task(task, sender, cancelled):
     """
     Wrapper for callables submitted to the underlying executor.
 
     Parameters
     ----------
-    background_task
+    task
         Callable representing the background task. This will be called
         with arguments ``send`` and ``cancelled``.
     sender : IMessageSender
@@ -69,7 +69,7 @@ def run_background_task(background_task, sender, cancelled):
     """
     try:
         with sender:
-            background_task(sender.send, cancelled)
+            task(sender.send, cancelled)
     except BaseException:
         # We'll only ever get here in the case of a coding error. But in
         # case that happens, it's useful to have the exception logged to