Socketio to zmq in background thread works in Werkzeug development environment but blocks in deployment

[robin-price]

I have niche application which involves hooking lasers up to websockets so people can play vector arcade games projected on public buildings using their phone as an interface. It's worked really well when I run it with the werkzeug development environment:

python -m flask run --host=192.168.1.2 --port=5000

But now I'm getting close to deployment and I'd like to run it either with gunicorn or ideally just the socketio.run(app) method and get it all set up as unit file for systemd. When I try this though (i.e. just python app.py) my background thread code blocks and the web server hangs till I ctrl c and I get

^CTraceback (most recent call last):
  File "src/gevent/greenlet.py", line 908, in gevent._gevent_cgreenlet.Greenlet.run
  File "/home/pi/eco-laser-arcade-web/app.py", line 20, in background_thread
    data = socket.recv_json()
           ^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/zmq/sugar/socket.py", line 941, in recv_json
    msg = self.recv(flags)
          ^^^^^^^^^^^^^^^^
  File "zmq/backend/cython/socket.pyx", line 809, in zmq.backend.cython.socket.Socket.recv
  File "zmq/backend/cython/socket.pyx", line 845, in zmq.backend.cython.socket.Socket.recv
  File "zmq/backend/cython/socket.pyx", line 194, in zmq.backend.cython.socket._recv_copy
  File "zmq/backend/cython/checkrc.pxd", line 13, in zmq.backend.cython.checkrc._check_rc
KeyboardInterrupt
2025-10-23T16:48:57Z <Thread at 0x7fff1c3b62a0: background_thread> failed with KeyboardInterrupt

Traceback (most recent call last):
  File "/home/pi/eco-laser-arcade-web/app.py", line 110, in <module>
    socketio.run(app, host="192.168.188.4", port=5000)
  File "/usr/lib/python3/dist-packages/flask_socketio/__init__.py", line 719, in run
    self.wsgi_server.serve_forever()
  File "/usr/lib/python3/dist-packages/gevent/baseserver.py", line 400, in serve_forever
    self._stop_event.wait()
  File "src/gevent/event.py", line 163, in gevent._gevent_cevent.Event.wait
  File "src/gevent/_abstract_linkable.py", line 521, in gevent._gevent_c_abstract_linkable.AbstractLinkable._wait
  File "src/gevent/_abstract_linkable.py", line 487, in gevent._gevent_c_abstract_linkable.AbstractLinkable._wait_core
  File "src/gevent/_abstract_linkable.py", line 490, in gevent._gevent_c_abstract_linkable.AbstractLinkable._wait_core
  File "src/gevent/_abstract_linkable.py", line 442, in gevent._gevent_c_abstract_linkable.AbstractLinkable.__wait_to_be_notified
  File "src/gevent/_abstract_linkable.py", line 451, in gevent._gevent_c_abstract_linkable.AbstractLinkable._switch_to_hub
  File "src/gevent/_greenlet_primitives.py", line 61, in gevent._gevent_c_greenlet_primitives.SwitchOutGreenletWithLoop.switch
  File "src/gevent/_greenlet_primitives.py", line 65, in gevent._gevent_c_greenlet_primitives.SwitchOutGreenletWithLoop.switch
  File "src/gevent/_gevent_c_greenlet_primitives.pxd", line 35, in gevent._gevent_c_greenlet_primitives._greenlet_switch
  File "src/gevent/greenlet.py", line 908, in gevent._gevent_cgreenlet.Greenlet.run
  File "/home/pi/eco-laser-arcade-web/app.py", line 20, in background_thread
    data = socket.recv_json()
           ^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3/dist-packages/zmq/sugar/socket.py", line 941, in recv_json
    msg = self.recv(flags)
          ^^^^^^^^^^^^^^^^
  File "zmq/backend/cython/socket.pyx", line 809, in zmq.backend.cython.socket.Socket.recv
  File "zmq/backend/cython/socket.pyx", line 845, in zmq.backend.cython.socket.Socket.recv
  File "zmq/backend/cython/socket.pyx", line 194, in zmq.backend.cython.socket._recv_copy
  File "zmq/backend/cython/checkrc.pxd", line 13, in zmq.backend.cython.checkrc._check_rc
KeyboardInterrupt

Like I said it works in the development environment. I know this is something to do with the background task I'm using to create a persistent connection via zmq with my c++ app to send data back to clients from the game.

from threading import Lock
from flask import Flask, render_template, request, session
from flask_socketio import SocketIO
import zmq

app = Flask(__name__)
app.config['SECRET_KEY'] = 'secret!'
async_mode = None
socketio = SocketIO(app, async_mode=async_mode, cors_allowed_origins='*')
thread = None
thread_lock = Lock()

context = zmq.Context()
socket = context.socket(zmq.PAIR)
socket.connect("tcp://localhost:9999")

def background_thread():
    while True:
        socketio.sleep(0)
        data = socket.recv_json()
        socketio.emit('response', data, to=data.get('sid'))
        print("sending json: " + str(data))


@app.route("/")
def index():
    return render_template('index.html')

@socketio.on('connect')
def handle_connection():
    global thread
    with thread_lock:
        if thread is None:
           thread = socketio.start_background_task(background_thread)
    data = {"event type": "connection",
            "sid": request.sid}
    socket.send_json(data)

@socketio.on('disconnect')
def handle_disconnection():
    print('closed connection with sid' + request.sid)
    data = {"event type": "disconnection",
            "sid": request.sid}
    socket.send_json(data)

@socketio.on('message')
def handle_message(data):
    print('received message: ' + data)

@socketio.on('my event')
def handle_my_custom_event(json):
    print('received json: ' + str(json))
    socket.send_json(json)

@socketio.on('paddle')
def handle_my_custom_event(json):
    json.update({"event type": "paddle"})
    json.update({"sid": request.sid})
    print('received json: ' + str(json))
    socket.send_json(json)

@socketio.on('joystick')
def handle_my_custom_event(json):
    json.update({"event type": "joystick"})
    json.update({"sid": request.sid})
    print('received json: ' + str(json))
    socket.send_json(json)

@socketio.on('mouse')
def handle_my_custom_event(json):
    #socketio.emit('iamdrawing', [json["x"], json["y"]])
    socketio.emit('mouse', json, include_self=False)
    json.update({"event type": "paddle"})
    json.update({"sid": request.sid})
    print('received json: ' + str(json))
    socket.send_json(json)

@socketio.on('buttonA')
def handle_my_custom_event(json):
    json.update({"event type": "buttonA"})
    json.update({"sid": request.sid})
    print('received json: ' + str(json))
    socket.send_json(json)

@socketio.on('buttonB')
def handle_my_custom_event(json):
    json.update({"event type": "buttonB"})
    json.update({"sid": request.sid})
    print('received json: ' + str(json))
    socket.send_json(json)

@socketio.on('mousePressed')
def handle_my_custom_event(json):
    json.update({"event type": "buttonA"})
    json.update({"sid": request.sid})
    print('received json: ' + str(json))
    socket.send_json(json)

@socketio.on('clear')
def handle_my_custom_event(json):
    json.update({"event type": "buttonB"})
    json.update({"sid": request.sid})
    print('received json: ' + str(json))
    socket.send_json(json)

if __name__ == '__main__':
    socketio.run(app)

Does anyone have any clues how to make the background thread non blocking in any of the socketio.run() scenarios? I would prefer to not use the dev environment in production for my event....

[miguelgrinberg]

Cool application!

Let me clarify something that maybe isn't completely clear. Socket.IO does not have a web server. You always have to choose a web server to run your application on. If you don't explicitly pick a web server, then a web server is chosen for you from what's installed in your virtualenv.

From the errors you shared, it looks like you are using the gevent web server. Are you sure your code and all your dependencies are compatible with gevent? And if they are, have you monkey patched the Python standard library so that it does not block?

If you have issues with gevent, then your other option in practice is to use a multithreaded web server like Werkzeug, but production ready. You can use gunicorn in threaded mode, for example. This should be the closest to the Werkzeug solution, but you will need to configure gunicorn with enough threads to handle all your clients. Each client consumes one thread exclusively.

[robin-price]

Socket.IO does not have a web server. You always have to choose a web server to run your application on. If you don't explicitly pick a web server, then a web server is chosen for you from what's installed in your virtualenv.

I think I just about parsed this from the deployment section of the docs. From what I understand just running
python app.py

is inherently more secure than using the Werkzeug setup, is this right? I just wanted to make the warning go away before it goes public facing. I'm not anticipating more than 20 connections at a time and the whole thing is running on raspberry pi 5 seeming very well. I haven't got Nginx or anything at the front just python running flask and Socketio serving up the files and handling the connections. I think because of the zmq situation I can only run one instance or flask doesn't know which SID to route data from the game back to. I'm routing through a Cloudflare tunnel to get round CGNAT handling incoming connections on a 4g dongle if that makes any difference.

Thank you very much for the gevent non blocking tip! I googled how to run zmq non in a non blocking mode and handle the errors when there's no data coming in. If anyone else ever gets stuck doing this kind of nonsense changing my background thread sorted it out.

def background_thread():
    while True:
        socketio.sleep(0)
        try:
            data = socket.recv_json(flags=zmq.NOBLOCK)
        except zmq.ZMQError as e:
            if e.errno == zmq.EAGAIN:
                pass
            else:
                raise
        else:
            socketio.emit('response', data, to=data.get('sid'))
            print("sending json: " + str(data))

[miguelgrinberg]

When you say that you run python app.py it's really hard to know what you mean. If you are calling socketio.run(app) inside your app.py file, then the server that is used depends on what packages you have installed. It could be Werkzeug, gevent or eventlet depending on what you installed. The server should print a line telling you what server it chose to run. Werkzeug is not a good option, of course. Eventlet is also not great, as it isn't well maintained. Gevent is good.

[robin-price]

Sorry yes I'm calling socketio.run(app) but it doesn't print anything out at the prompt when I start it. I've set async_mode = 'gevent' when starting and when I ctrl c it tells me that gevent/baseserver.py was running. So I guess I'm good to go?

[miguelgrinberg]

Maybe you are. But working with gevent is tricky, and my impression is that you aren't very familiar with it. I asked about monkey patching, for example, and you haven't said if you are doing it, or if you are sure this isn't needed. So all I can say is that gevent is not just something you add and everything works, it's quite tricky sometimes to make it work correctly, so maybe it would make sense for you to learn how it works so that you are better able to configure your app for it, and debug issues if they appear.

[robin-price]

Your impression is correct! I looked into monkey patching, imported it and calling patch all but it didn't fix the zmq blocking problem. I think explicitly calling it with non blocking flags set and handling errors if there's no data returned is their preferred design pattern and it was working ok in werkzeug more by accident than design. Setting async_mode to gevent seems to force it to use the gevent server as I have both eventlet and gevent installed.

I dived into https://upsun.com/blog/python-gevent-best-practices/ but I don't get any errors either if I monkey patch or not. It was more the supposed relative safety of the gevent server I was assuming.