Added Multiple servers example

Author: michalpokusa

docs/examples.rst

@@ -183,3 +183,19 @@ In both cases you can check if ``request`` is authenticated by calling ``check_a
     :caption: examples/httpserver_authentication_handlers.py
     :emphasize-lines: 9-15,21-25,33,44,57
     :linenos:
+
+Multiple servers
+----------------
+
+Although it is not the primary use case, it is possible to run multiple servers at the same time.
+In order to do that, you need to create multiple ``Server`` instances and call ``.start()`` and ``.poll()`` on each of them.
+Using ``.serve_forever()`` for this is not possible because of it's blocking behaviour.
+
+Each server **must have a different port number**.
+
+In combination with separate authentication and diffrent ``root_path`` this allows creating moderately complex setups.
+
+.. literalinclude:: ../examples/httpserver_multiple_servers.py
+    :caption: examples/httpserver_multiple_servers.py
+    :emphasize-lines: 13-14,17,26,35-36,51-52,57-58
+    :linenos:

examples/httpserver_multiple_servers.py

@@ -0,0 +1,61 @@
+# SPDX-FileCopyrightText: 2022 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+import socketpool
+import wifi
+
+from adafruit_httpserver import Server, Request, Response
+
+
+pool = socketpool.SocketPool(wifi.radio)
+
+bedroom_server = Server(pool, "/bedroom")
+office_server = Server(pool, "/office")
+
+
+@bedroom_server.route("/bedroom")
+def bedroom(request: Request):
+    """
+    This route is registered only with ``bedroom_server``.
+    """
+    with Response(request) as response:
+        response.send("Hello from the bedroom!")
+
+
+@office_server.route("/office")
+def office(request: Request):
+    """
+    This route is registered only with ``office_server``.
+    """
+    with Response(request) as response:
+        response.send("Hello from the office!")
+
+
+@bedroom_server.route("/home")
+@office_server.route("/home")
+def home(request: Request):
+    """
+    This route is registered with both servers.
+    """
+    with Response(request) as response:
+        response.send("Hello from home!")
+
+
+id_address = str(wifi.radio.ipv4_address)
+
+# Start the servers.
+
+print(f"[bedroom_server] Listening on http://{id_address}:5000")
+print(f"[office_server] Listening on http://{id_address}:8000")
+bedroom_server.start(id_address, 5000)
+office_server.start(id_address, 8000)
+
+while True:
+    try:
+        # Process any waiting requests for both servers.
+        bedroom_server.poll()
+        office_server.poll()
+    except OSError as error:
+        print(error)
+        continue