summaryrefslogtreecommitdiff
path: root/docs/howto
diff options
context:
space:
mode:
authormathieui <mathieui@mathieui.net>2022-02-27 20:33:26 +0100
committermathieui <mathieui@mathieui.net>2022-02-27 20:33:26 +0100
commit5c4c867dee2d0195d94c6f01f04ae92e1e8b84c2 (patch)
tree8c4963f4d72767443c3126ddc1d9cfdf527d755a /docs/howto
parentb23b805dc521edf0dcdd8d4ac6b8b43539aba536 (diff)
downloadslixmpp-5c4c867dee2d0195d94c6f01f04ae92e1e8b84c2.tar.gz
slixmpp-5c4c867dee2d0195d94c6f01f04ae92e1e8b84c2.tar.bz2
slixmpp-5c4c867dee2d0195d94c6f01f04ae92e1e8b84c2.tar.xz
slixmpp-5c4c867dee2d0195d94c6f01f04ae92e1e8b84c2.zip
docs: add a page on how to remove process()
Diffstat (limited to 'docs/howto')
-rw-r--r--docs/howto/index.rst1
-rw-r--r--docs/howto/remove_process.rst55
2 files changed, 56 insertions, 0 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.