Add a test for traceback and update wiki

Signed-off-by: Gajowniczek, Artur <artur.gajowniczek@point72.com>

csp/tests/test_engine.py

@@ -825,8 +825,10 @@ def stop(self):
                 pass
 
             def process_next_sim_timeslice(self, now):
-                self.shutdown_engine(ValueError("Dummy exception message"))
-
+                try:
+                    [].pop()
+                except IndexError as e:
+                    self.shutdown_engine(e)
         class TestAdapterImpl(ManagedSimInputAdapter):
             def __init__(self, manager_impl):
                 pass
@@ -838,8 +840,12 @@ def graph():
             nc = adapter.subscribe()
             csp.add_graph_output("nc", nc)
 
-        with self.assertRaisesRegex(ValueError, "Dummy exception message"):
+        try:
             csp.run(graph, starttime=datetime(2020, 1, 1), endtime=timedelta(seconds=1))
+        except IndexError:
+            tb = traceback.format_exc()
+
+        self.assertTrue('[].pop()' in tb)
 
     def test_feedback(self):
         # Dummy example

docs/wiki/how-tos/Write-Realtime-Input-Adapters.md

@@ -405,3 +405,18 @@ csp.run(my_graph, starttime=datetime.utcnow(), endtime=timedelta(seconds=10), re
 ```
 
 Do note that realtime adapters will only run in realtime engines (note the `realtime=True` argument to `csp.run`).
+
+## Engine shutdown
+
+In case a pushing thread hits a terminal error, an exception can be passed to the main engine thread to shut down gracefully through a `shutdown_engine(exc: Exception)` method exposed by `PushInputAdapter`, `PushPullInputAdapter` and `AdapterManagerImpl`.
+
+For example:
+
+```python
+def _run(self):
+   while self._running:
+        try:
+            requests.get(endpoint) # API call over a network, may fail
+        catch Exception as exc:
+            self.shutdown_engine(exc)
+```