From d889e40504a4d6a47cac30f1062e537083e46d79 Mon Sep 17 00:00:00 2001 From: "Joel T. Collins" Date: Wed, 15 Jul 2020 10:04:10 +0100 Subject: [PATCH 1/2] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c126a63..a75437a 100644 --- a/README.md +++ b/README.md @@ -73,11 +73,11 @@ Serving WebSockets in Python was really easy, if you used Gevent, AsyncIO, etc. To install Flask-Sockets, simply: -```pip install Flask-Sockets``` +```pip install flask-threaded-sockets``` ## WebSocket Interface The websocket interface that is passed into your routes is the same as [gevent-websocket](https://bitbucket.org/noppo/gevent-websocket). The basic methods are fairly straightforward —  -``send``, ``receive``, ``send_frame``, and ``close``. \ No newline at end of file +``send``, ``receive``, ``send_frame``, and ``close``. From cfed8e91141008a02ad066e9f541394632f87a34 Mon Sep 17 00:00:00 2001 From: "Joel T. Collins" Date: Wed, 15 Jul 2020 14:55:20 +0100 Subject: [PATCH 2/2] Added justification section --- README.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a75437a..502cc71 100644 --- a/README.md +++ b/README.md @@ -67,15 +67,25 @@ if __name__ == "__main__": Serving WebSockets in Python was really easy, if you used Gevent, AsyncIO, etc. Now it's easy if you just want to use a threaded development server. +## Why would you ever want this? + **This should not be used in deployed web apps with lots of requests expected! We developed this library for use in low-traffic IoT devices that benefit from using native Python threads** +Almost every Python websocket tutorial out there will tell you to use an async library like AsyncIO, Gevent, Tornado etc. For virtually all applications, this is absolutely true. These async libraries allow you to handle a huge number of concurrent requests, even long-running connections like websockets, with minimal overhead. + +In these cases, native threading is heavily discouraged. Most threaded production servers will use a small pool of threads to handle concurrency, and websockets will quickly saturate this pool. Async concurrency libraries get around this by allowing a virtually unlimited number of concurrent requests to be processed. + +One way to use native threads without risking pool saturation would be to spawn a thread *per client*, however it's obvious to see why this would be problematic for large public web apps: One thread per client will quickly lead to an infeasible number of native threads, introducing a huge context-switching overhead. + +However, for small services, such as local WoT devices, this is absolutely fine. If you only expect a small (<50) number of simultaneous connections, native threads are perfectly viable as a concurrency provider. Moreover, unlike most async libraries, you're able to easily integrate existing code without having to add `async`/`await` keywords, or monkey-patch libraries. For instrument control, this is ideal. We get the full capabilities of Python threading, and it's synchronisation primitives, unmodified use of existing device control code, and no need for monkey-patching. + ## Installation To install Flask-Sockets, simply: ```pip install flask-threaded-sockets``` -## WebSocket Interface +## WebSocket interface The websocket interface that is passed into your routes is the same as [gevent-websocket](https://bitbucket.org/noppo/gevent-websocket).