Implement double threaded auxiliary interface

docs/advanced_features/dynamic_conf.rst

@@ -0,0 +1,24 @@
+Dynamic Configuration
+=====================
+
+In some situation, it can be useful to change the behaviour of the auxiliary in-use dynamically.
+For example, switching for a brand new channel or simply change an attribute value.
+
+Thanks to the common auxiliary interface, users can easily change their auxiliary
+configuration by simply stop it (call of delete_instance public method) ,access
+it different public attributes, and then just restarts the auxiliary (call of
+the public method ``delete_instance``)
+
+.. warning:: if you are using the original auxiliary instance don't forget to
+    switch back to its initial configuration for the next test cases.
+
+Find below a complete example where during the test, the current pcan
+connector is replaced by a simple CCLoopback:
+
+.. literalinclude:: ../../examples/templates/suite_proxy/test_proxy.py
+    :language: python
+    :lines: 22-152
+
+.. warning:: this feature allows to change the complete auxiliary configuration,
+	so depending on which parameters are changed the auxiliary execution could lead
+	to unexpected behaviors.

docs/advanced_features/index.rst

@@ -5,5 +5,5 @@ Advanced features
     :maxdepth: 2
 
     access_config
-    aux_copies
+    dynamic_conf
     multiprocessing

docs/auxiliary_interfaces/dt_aux.rst

@@ -0,0 +1,5 @@
+double threaded auxiliary
+========================
+
+.. automodule:: pykiso.interfaces.dt_auxiliary
+    :members:

docs/auxiliary_interfaces/index.rst

@@ -10,3 +10,4 @@ Auxiliary interfaces
     mp_auxiliary
     simple_auxiliary
     thread_auxiliary
+    dt_aux

docs/examples/how_to_auxiliary.rst

@@ -28,6 +28,10 @@ possible usage of an auxiliary:
 - The :py:class:`~pykiso.interfaces.simple_auxiliary.SimpleAuxiliaryInterface`
   does not implement any kind of concurrent execution. It is suited for host-based applications where the auxiliary
   initiates every possible action, i.e. the reception of data can always be expected.
+- The :py:class:`~pykiso.interfaces.dt_auxiliary.DTAuxiliaryInterface`
+  is a double threaded base auxiliary, where a thread is used for the transmission
+  and a second one for the reception. It is suited for IO-bound tasks where
+  the reception of data cannot be expected.
 
 Execution of an Auxiliary
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -46,7 +50,11 @@ Concurrent auxiliary execution
 
 The execution of concurrent auxiliaries (i.e. inheriting from :py:class:`~pykiso.interfaces.thread_auxiliary.AuxiliaryInterface`
 or :py:class:`~pykiso.interfaces.mp_auxiliary.MpAuxiliaryInterface`) is
-handled by the interfaces' :py:meth:`~pykiso.interfaces.thread_auxiliary.AuxiliaryInterface.run>` method.
+handled by the interfaces' :py:meth:`run()<pykiso.interfaces.thread_auxiliary.AuxiliaryInterface.run>` method.
+
+In the DTAuxiliaryInterface case, everything related to the tansmission is handled by
+:py:meth:`~pykiso.interfaces.dt_auxiliary.DTAuxiliaryInterface._transmit_task` and for the reception
+by :py:meth:`~pykiso.interfaces.dt_auxiliary.DTAuxiliaryInterface._reception_task`
 
 Each command execution is handled in a thread-safe way by getting values from an input queue and
 returning the command result in an output queue.
@@ -79,6 +87,20 @@ Each time the execution is entered, the following actions are performed:
   #. Call the auxiliarie's :py:meth:`~pykiso.interfaces.thread_auxiliary.AuxiliaryInterface._receive_message` method
   #. If something is returned, put it in the output queue, otherwise repeat this execution cycle.
 
+For an auxiliary based on DTAuxiliaryInterface, the execution is slightly different due to the usage of two threads:
+
+1. Verify if a request is available in the input queue
+
+  #. If the command message is "DELETE_AUXILIARY" the transmit task while loop ends
+
+  #. If the command message is a tuple of 2 elements starting with your custom command type, and then the data to send. This custom command has to be implemented in the :py:meth:`~pykiso.interfaces.dt_auxiliary.DTAuxiliaryInterface._run_command` method.
+
+2. Verify if a Message is available for reception
+
+  #. Call the auxiliarie's :py:meth:`~pykiso.interfaces.dt_auxiliary.DTAuxiliaryInterface._receive_message` and simpy wait for a message coming from the connector.
+
+  #. If something is returned, put it in the output queue, otherwise repeat this execution cycle.
+
 Implement an Auxiliary
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -115,6 +137,10 @@ the following methods to be implemented:
   :py:meth:`~pykiso.connector.CChannel.cc_receive` method. The received data can then be decoded according to a particular protocol, matched
   against a previously sent request, or trigger any kind of further processing.
 
+For the concurrent Auxiliary interface :py:class:`~pykiso.interfaces.dt_auxiliary.DTAuxiliaryInterface`,
+only one significant difference :
+
+- :py:meth:`~pykiso.interfaces.thread_auxiliary.AuxiliaryInterface._abort_command`: is not mandatory
 
 .. _aux-tutorial-example:
 
@@ -242,6 +268,10 @@ See below an example implementing the basic functionalities of a Thread Auxiliar
             except Exception:
                 logging.exception(f"Channel {self.channel} failed to receive data")
 
+Regarding a concrete implementation using :py:class:`~pykiso.interfaces.dt_auxiliary.DTAuxiliaryInterface`
+take a look to :py:class:`~pykiso.lib.auxiliaries.communication_auxiliary.CommunicationAuxiliary` source code.
+
+
 More examples are available under :py:mod:`pykiso.lib.auxiliaries`.
 
 .. note::

docs/introduction/integration_test.rst

@@ -69,7 +69,7 @@ following:
 -  provide the auxiliaries with the matching connectors
 -  generate the list of tests to perform
 -  provide the testcases with the auxiliaries they need
--  verify if the tests can be performed 
+-  verify if the tests can be performed
 -  for remote tests (see :ref:`../remote_test/remote_test`) flash and run and synchronize the tests on the auxiliaries
 -  gather the reports and publish the results
 
@@ -80,7 +80,7 @@ The **auxiliary** provides to the **test-coordinator** an interface to
 interact with the physical or digital auxiliary target. It is composed
 by 2 blocks:
 
--  instance creation / deletion 
+-  instance creation / deletion
 -  connectors to facilitate interaction and communication with the
    device (e.g. messaging with *UART*)
 

docs/remote_test/remote_test.rst

@@ -1,14 +1,14 @@
 Remote Test
 ===========
 
-With the remote test approach, the idea is to execute tests on the targeted hardware to enable 
+With the remote test approach, the idea is to execute tests on the targeted hardware to enable
 the developer to practice test-driven-development directly on the target.
 
 
 Test Coordinator
 ~~~~~~~~~~~~~~~~
 
-In the case of remote tests usage, the **test-coordinator** will still perform the same task 
+In the case of remote tests usage, the **test-coordinator** will still perform the same task
 but will also:
 
 -  verify if the tests can be performed
@@ -24,10 +24,10 @@ For the remote test approach, auxiliaries should be composed by 2 blocks:
    container)
 -  connectors to facilitate interaction and communication with the
    device (e.g. flashing via *JTAG*, messaging with *UART*)
-  
+
 One example of implementation of such an auxiliary is the *device under test* auxiliary used with the TestApp.
 In this specific case we have:
- 
+
   -  As communication channel (**cchannel**) usually *UART*
   -  As flashing channel (**flashing**) usually *JTAG*
 
@@ -49,7 +49,7 @@ The Flasher Connectors usually provide only one method, :py:meth:`Flasher.flash`
 .. _flashing-1:
 
 
-Message Protocol 
+Message Protocol
 ~~~~~~~~~~~~~~~~
 
 The message protocol is used (but not only) between the *device under
@@ -250,7 +250,7 @@ The flashing connector is in turn called from an appropriate auxiliary (usually
 Implementation of Remote Tests
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For remote tests, RemoteTestCase / RemoteTestSuite should be used instead of BasicTestCase / BasicTestSuite, based on Message Protocol, 
+For remote tests, RemoteTestCase / RemoteTestSuite should be used instead of BasicTestCase / BasicTestSuite, based on Message Protocol,
 users can configure the maximum time (in seconds) used to wait for a report.
 This "timeout" is configurable for each available fixtures :
 

examples/templates/suite_com/test_com.py

@@ -19,6 +19,7 @@
 """
 
 import logging
+import time
 
 import pykiso
 
@@ -42,17 +43,14 @@ def setUp(self):
         logging.info(
             f"--------------- SETUP: {self.test_suite_id}, {self.test_case_id} ---------------"
         )
-        # just create a communication auxiliary with a bran new channel
-        # in order to send odd bytes. Always use named arguments!
+        # due to the fact that auto_start flag is set to False, this let
+        # the user to start the auxiliary on demand using start method
         com_aux.start()
-        self.com_aux_odd = com_aux.create_copy(com=CCLoopback())
-        # just create a communication auxiliary based on the given
-        # parameters present in the yaml config (com_aux.yaml) to send
-        # even bytes
-        self.com_aux_even = self.com_aux_odd.create_copy()
-        # start com_aux_even because original configuration has
-        # auto_start flag set to False
-        self.com_aux_even.start()
+
+        # just suspend the current auxiliary execution
+        com_aux.suspend()
+        # just resume the current auxiliary execution
+        com_aux.resume()
 
     def test_run(self):
         """Thanks to the usage of dev cc_raw_loopback, let's try to send
@@ -61,29 +59,20 @@ def test_run(self):
         logging.info(
             f"--------------- RUN: {self.test_suite_id}, {self.test_case_id} ---------------"
         )
-        # first send the even bytes and stop the copy in order to
-        # automatically resume the original one (self.com_aux_odd)
-        self.com_aux_even.send_message(b"\x02\x04\x06")
-        response = self.com_aux_even.receive_message()
-        self.assertEqual(response, b"\x02\x04\x06")
-        # destroy com_aux_even and start working with com_aux_odd aux
-        # copy
-        self.com_aux_odd.destroy_copy()
-
-        # Then send the odd bytes and stop the copy in order to
-        # automatically resume the original one (com_aux)
-        self.com_aux_odd.send_message(b"\x01\x03\x05")
-        response = self.com_aux_odd.receive_message()
-        self.assertEqual(response, b"\x01\x03\x05")
-        # destroy com_aux_odd and start working with com_aux
-        com_aux.destroy_copy()
+        # send 20 requests over the connected channel and check if the
+        # command was successfully sent
+        for _ in range(20):
+            req = b"\x02\x04\x06"
+            logging.info(f"send request {req} over {com_aux.name}")
+            state = com_aux.send_message(req)
+            logging.info(f"request excecution state: {state}")
+            self.assertEqual(state, True)
 
-        # Just use the original communication auxiliary to send and
-        # receive some bytes
-        com_aux.send_message(b"\x01\x02\x03\x04\x05\x06")
-        response = com_aux.receive_message()
-        logging.info(f"received message: {response}")
-        self.assertEqual(response, b"\x01\x02\x03\x04\x05\x06")
+        # get the 20 first received messages
+        for _ in range(20):
+            response = com_aux.receive_message()
+            logging.info(f"received data {response}")
+            self.assertEqual(response, b"\x02\x04\x06")
 
     def tearDown(self):
         """If a fixture is not use just override it like below."""