summaryrefslogtreecommitdiff
path: root/docs/howto
diff options
context:
space:
mode:
Diffstat (limited to 'docs/howto')
-rw-r--r--docs/howto/index.rst1
-rw-r--r--docs/howto/remove_process.rst55
-rw-r--r--docs/howto/xmpp_tdg.rst2
3 files changed, 57 insertions, 1 deletions
diff --git a/docs/howto/index.rst b/docs/howto/index.rst
index e4dee4d7..a4f0f3b0 100644
--- a/docs/howto/index.rst
+++ b/docs/howto/index.rst
@@ -9,6 +9,7 @@ Tutorials, FAQs, and How To Guides
internal_api
features
sasl
+ remove_process
handlersmatchers
guide_xep_0030
xmpp_tdg
diff --git a/docs/howto/remove_process.rst b/docs/howto/remove_process.rst
new file mode 100644
index 00000000..26d54a62
--- /dev/null
+++ b/docs/howto/remove_process.rst
@@ -0,0 +1,55 @@
+.. _remove-process:
+
+How to remove xmpp.process()
+============================
+
+
+Starting from slixmpp 1.8.0, running ``process()`` on an
+XMLStream/ClientXMPP/ComponentXMPP instance is deprecated, and starting from
+1.9.0, it will be removed.
+
+Why
+---
+
+This has been the usual way of running an application using SleekXMPP/slixmpp
+for ages, but it has come at a price: people do not understand how they
+should run their application without it, or how to integrate their slixmpp
+code with the rest of their asyncio application.
+
+In essence, ``process()`` is only a very thin wrapper around asyncio loop
+functions:
+
+.. code-block:: python
+
+ if timeout is None:
+ if forever:
+ self.loop.run_forever()
+ else:
+ self.loop.run_until_complete(self.disconnected)
+ else:
+ tasks: List[Future] = [asyncio.sleep(timeout)]
+ if not forever:
+ tasks.append(self.disconnected)
+ self.loop.run_until_complete(asyncio.wait(tasks))
+
+How
+---
+
+Hence it can be replaced according to what you want your application to do:
+
+- To run forever, ``loop.run_forever()`` will work just fine
+
+- To run until disconnected, ``loop.run_until_complete(xmpp.disconnected)``
+ will be enough (XMLStream.disconnected is an future which result is set when
+ the stream gets disconnected.
+
+- To run for a scheduled time (and still abort when disconnected):
+
+.. code-block:: python
+
+ tasks = [asyncio.sleep(timeout)]
+ tasks.append(xmpp.disconnected)
+ loop.run_until_complete(asyncio.wait(tasks))
+
+There is no magic at play here and anything is possible if a more flexible
+execution scheme is expected.
diff --git a/docs/howto/xmpp_tdg.rst b/docs/howto/xmpp_tdg.rst
index 53194e13..d3b761d2 100644
--- a/docs/howto/xmpp_tdg.rst
+++ b/docs/howto/xmpp_tdg.rst
@@ -193,7 +193,7 @@ implementation should work correctly.
.. tip::
To see how to implement in-band registration as a Slixmpp plugin,
- see the tutorial :ref:`tutorial-create-plugin`.
+ see the tutorial :ref:`create-plugin`.
`View full source (5) <http://github.com/legastero/xmpp-tdg/blob/master/code/CheshiR/RegistrableComponent.py>`_ |
`View original code (5) <http://github.com/remko/xmpp-tdg/blob/master/code/CheshiR/RegistrableComponent.py>`_