Throttle backend activity when no clients connected

[bapowell]

I have a NiceGUI 1.x app that in the backend is constantly processing a bunch of incoming data, with bindings to UI elements. Think of it as a mini SCADA/HMI system. But, the app is only needed for specific tasks, so is usually wasting CPU. Since it's running on a Raspberry Pi, I need to be mindful of resource usage.

I'd like to detect when no client connections exist, to throttle down the backend data processing, and, if possible, increase the binding_refresh_interval.

Can a NiceGUI app detect when no active browser connections exist?

[falkoschindler]

You're probably not using the ui.page decorator yet. If you create UI elements without it, they automatically create an auto-index-page. This page lives forever and is shared for every browser that connects.

You should try explicitly wrapping your UI in a page. Then the UI is only built when a client connects, including timers and bindings. When a client disconnects, corresponding timers are stopped, bindings are removed and memory is freed up.

---

In case you want to count the number of clients anyway: When using individual pages, you can count clients as follows:

from nicegui import globals, ui

@ui.page('/')
def page():
    ui.label(f'{len(globals.clients)} clients')

ui.run()

Note that the displayed number includes one shared client for the auto-index page not used in this example. When only using the shared auto-index page, this number is always 1 (not very helpful in your case).

Alternatively, you could register to ui.on_connected and ui.on_disconnected and track the number of active connections yourself. Currently there is no such feature in NiceGUI.

[bapowell]

I appreciate the very helpful info and suggestions.

My app has multiple pages, each of which uses the ui.page decorator (even the root '/' page). So, wrapping everything under a single page doesn't seem like an option for this particular case. Good thing to consider for other use cases, though.

I can make this work for now using len(globals.clients), and keeping in mind it has a floor of 1 when no real clients are connected (reflecting only the shared client for the auto-index page).

As a side note, I did test the ui.on_connected and ui.on_disconnected callbacks. They work great for the auto-index page. But they are not called for any other pages, e.g. ones created using @ui.page. That may be the intent, although not very intuitive. It seems like they ought to fire regardless of the page. You're already keeping track of clients globally, e.g. globals.clients, so maybe this could be an enhancement at some point.

[falkoschindler]

Glad to hear that I could help.

Regarding ui.on_connect and ui.on_disconnect: I just checked and both hooks work as expected. That's why I think there's a misunderstanding. They refer only to the page they are placed on. If you put them somewhere in global scope, they only handle connections to the (in your case unreachable) auto-index page. Move them in one of your page functions and you should get connect and disconnect events.

@rodja Maybe the API is not very intuitive here. We might want to think about ways to improve it - or at least the documentation.

[bapowell]

Ah, now I get it: "They refer only to the page they are placed on." That's nice functionality to have, tracking clients per page. Might want to add that clarification to the docs... and/or rename the methods to on_page_connect and on_page_disconnect.

If feasible I do think an app-level on_connect and on_disconnect would be nice, too. This on_connect callback would only be called when a new client connects (i.e. not currently connected to any pages). The on_disconnect would be called only when a client disconnects from a page, and that client has no other page connections. Again, this seems like a straightforward enhancement, since tracking of clients is already being done via globals.clients. I'm not yet very familiar with the code base; otherwise I would consider tackling that myself.

[rodja]

@bapowell this indeed would be a nice addition. Let's gather all the facts:

• The suggestion to modify the behaviour of ui.on_connect and on_disconnect to always be called if any client connects/disconnects would break the current API. Which is not a huge issue if we put this change it in the next minor release 1.1.0. This bump is already need because of the API changes in ui.uplaod.
• We already have a client.on_connect of sorts: await client.handshake() will block further execution until a connection is established.
• Additional client.on_connect and client.on_disconnect callback registrations could be useful too.

[rodja]

Should we rename await client.handshake() into await client.connected() and also add await client.disconnected()? Usage would be like this:

from nicegui import ui

@ui.page('/')
async def main_page(client: Client):
    # setup code
    await client.connected()
    # working with the connection
    await client.disconnected()
    # cleanup

ui.run()    

[rodja]

I've started a new pull-request #234 to provide a better basis for the discussion. @bapowell I would be very happy if you could do a review. Maybe a good way to learn the code base ;-)

[falkoschindler]

The on_disconnect would be called only when a client disconnects from a page, and that client has no other page connections.

I think this is a bit more complicated than it sounds. Currently a "client" is basically a browser tab with a websocket connection to the Python backend. If the user opens a new tab, we treat it as a complete new client. And if the tab is closed, the client disconnects no matter if there is another browser tab.

To reflect multiple tabs, we would need to use something like session IDs. Although this is doable, it might complicate the API once more. A "disconnect" could either mean a tab closed or a complete session closed. This is independent of the current discussion about whether to fire on the current page only or globally.

To keep the required changes minimal, we should leave the concept of clients and their connect/disconnect events unchanged and introduce the concept of "sessions" with something like "session started" and "session ended" events. But I'm not sure if this is worth the effort.

[bapowell]

Agreed. I confused client connections (sockets) with sessions. My suggestion for the enhancement makes sense for session handling, rather than individual socket connections. Might just want to put the "session started/ended" concept on the backlog, for future consideration.

[bapowell]

Regarding this discussion, the changes introduced in v1.1.0 work well. Thank you.
Here's an example demonstrating the functionality:

import asyncio
import logging

from nicegui import ui, app, Client
import nicegui.globals
from fastapi import Request

logging.basicConfig(level=logging.DEBUG)
webui_client_count = 0

ui.label('Hello')  # will be put on the auto-index page

@ui.page('/page1', title='Page #1')
def page1(request: Request, client: Client):
    logging.debug(f'page1(request={request}, client={client})')
    ui.label('Lifecycle testing - using client.on_connect|disconnect').classes('text-lg text-weight-bold')
    client.on_connect(lambda: logging.debug('page1: on_connect fired'))
    client.on_disconnect(lambda: logging.debug('page1: on_disconnect fired'))

@ui.page('/page2', title='Page #2')
async def page2(request: Request, client: Client):
    logging.debug(f'page2(request={request}, client={client})')
    ui.label('Lifecycle testing - using await client.connected|disconnected').classes('text-lg text-weight-bold')
    await client.connected()
    logging.debug('page2: client connected')
    await asyncio.sleep(3)
    ui.label('displayed 3 secs after client connected')
    await client.disconnected()
    logging.debug('page2: client disconnected')

def setup_ui():
    app.on_startup(lambda: print('starting up'))

    def register_client_connect():
        global webui_client_count
        webui_client_count += 1
        nicegui_client_count = len(nicegui.globals.clients) - 1  # subtract 1 because NiceGUI always has a shared client for the auto-index page
        logging.info(f'client connected; webui_client_count={webui_client_count}, nicegui_client_count={nicegui_client_count}')
    app.on_connect(register_client_connect)

    def register_client_disconnect():
        global webui_client_count
        webui_client_count -= 1
        nicegui_client_count = len(nicegui.globals.clients) - 1  # subtract 1 because NiceGUI always has a shared client for the auto-index page
        logging.info(f'client DISconnected; webui_client_count={webui_client_count}, nicegui_client_count={nicegui_client_count}')
    app.on_disconnect(register_client_disconnect)

setup_ui()

ui.run()

[canDry]

Nice tool! I'm looking at converting a pysimplegui app over to this tool.

If I want my nicegui app to simply quit (i.e. via sys,exit()) when the lone/last client disconnects what would the be simplest/cleanest way to do that?

[rodja]

Just count the number of connections and when they reach 0, call app.shutdown() which was introduced in #83. You also need to disable auto-reloading with ui.run(reload=False).

[canDry]

Thanks.

p.s. I noticed that the #83 incorrectly states shutdown is a method of ui.

[rodja]

Thanks for the correction. We have moved it from ui to app to make the global behaviour it more clear.