What is shutdown really doing

[DenvE]

As example simple_broker.rs.

I have added
tokio::time::sleep(std::time::Duration::from_mins(10)).await;
before the Ok(()) return

In the logging is see this :
Stored retained message for topic: $SYS/broker/subscriptions/count
2026-07-03T16:18:30.722345Z DEBUG mqtt5::broker::storage::file_backend: Storing retained message for topic: $SYS/broker/subscriptions/count
^C2026-07-03T16:18:32.971792Z INFO simple_broker:
⚠️ Shutdown signal received
2026-07-03T16:18:32.971988Z INFO simple_broker: Shutting down broker...
2026-07-03T16:18:32.972012Z INFO simple_broker: ✅ Broker shutdown complete
2026-07-03T16:18:40.710212Z DEBUG mqtt5::broker::sys_topics: Publishing $SYS topic: $SYS/broker/uptime = 20
2026-07-03T16:18:40.710366Z DEBUG mqtt5::broker::router: Stored retained message for topic: $SYS/broker/uptime
2026-07-03T16:18:40.710411Z DEBUG mqtt5::broker::storage::file_backend: Storing retained message for topic: $SYS/broker/uptime
2026-07-03T16:18:40.731700Z DEBUG mqtt5::broker::sys_topics: Publishing $SYS topic: $SYS/broker/clients/connected = 1
2026-07-03T16:18:40.731785Z DEBUG mqtt5::broker::router: Stored retained message for topic: $SYS/broker/clients/connected

and sys_topcis keeps logging.

So it seems the broker is still alive.

My question is : what is the purpose of shutdown function ?

Even after shutdown, clients can still connect :

^C2026-07-03T16:28:08.396136Z INFO simple_broker:
⚠️ Shutdown signal received
2026-07-03T16:28:08.396374Z INFO simple_broker: Shutting down broker...
2026-07-03T16:28:08.396404Z INFO simple_broker: ✅ Broker shutdown complete
2026-07-03T16:28:11.372380Z DEBUG mqtt5::broker::server: New TCP connection addr=127.0.0.1:44572
2026-07-03T16:28:11.372639Z DEBUG mqtt5::broker::client_handler: Client handler started for 127.0.0.1:44572 (TCP)
2026-07-03T16:28:11.372870Z DEBUG mqtt5::broker::client_handler::connect: Processing CONNECT packet client_id=mqttx_635dff9b2 addr=127.0.0.1:44572 protocol_version=5 clean_start=true keep_alive=60
2026-07-03T16:28:11.372901Z DEBUG mqtt5::broker::client_handler::connect: Client using MQTT v5.0 protocol_version=5 addr=127.0.0.1:44572
2026-07-03T16:28:11.373005Z DEBUG mqtt5::broker::client_handler::connect: Client connection limits client_id=mqttx_635dff9b2 receive_maximum=65535 max_packet_size=None
2026-07-03T16:28:11.373196Z DEBUG mqtt5::broker::client_handler::connect: Created new session with will_delay_interval: None
2026-07-03T16:28:11.373281Z DEBUG mqtt5::broker::client_handler::connect: Sending CONNACK client_id=mqttx_635dff9b2 session_present=false assigned_client_id=None
2026-07-03T16:28:11.373395Z DEBUG mqtt5::broker::client_handler::connect: CONNACK sent successfully
2026-07-03T16:28:11.373416Z INFO mqtt5::broker::client_handler: Client mqttx_635dff9b2 connected from 127.0.0.1:44572 (TCP)
2026-07-03T16:28:11.373434Z DEBUG mqtt5::broker::resource_monitor: Connection registered: mqttx_635dff9b2 from 127.0.0.1 (total: 1)
2026-07-03T16:28:11.373493Z INFO mqtt5::broker::router: Registered client: mqttx_635dff9b2
2026-07-03T16:28:11.405401Z DEBUG mqtt5::broker::router: Client mqttx_635dff9b2 subscribed to wildcard #
2026-07-03T16:28:11.405494Z DEBUG mqtt5::broker::client_handler::subscribe: Retained messages found for subscription topic=# count=0
2026-07-03T16:28:17.053903Z DEBUG mqtt5::broker::sys_topics: Publishing $SYS topic: $SYS/broker/uptime = 10
2026-07-03T16:28:17.054000Z DEBUG mqtt5::broker::router: Stored retained message for topic: $SYS/broker/uptime
2026-07-03T16:28:17.054029Z DEBUG mqtt5::broker::storage::file_backend: Storing retained message for topic: $SYS/broker/uptime
2026-07-03T16:28:17.056238Z DEBUG mqtt5::broker::sys_topics: Publishing $SYS topic: $SYS/broker/clients/connected = 1
2026-07-03T16:28:17.056293Z DEBUG mqtt5::broker::router: Stored retained message for topic: $SYS/broker/clients/connected
2026-07-03T16:28:17.056330Z DEBUG mqtt5::broker::storage::file_backend: Storing retained message for topic: $SYS/broker/clients/connected
...

2026-07-03T16:28:19.486687Z INFO mqtt5::broker::client_handler: Unregistering client mqttx_635dff9b2 (not taken over)
2026-07-03T16:28:19.486785Z DEBUG mqtt5::broker::router: Unregistered client: mqttx_635dff9b2
2026-07-03T16:28:19.486801Z DEBUG mqtt5::broker::resource_monitor: Connection unregistered: mqttx_635dff9b2 from 127.0.0.1 (total: 0)
2026-07-03T16:28:19.487093Z DEBUG mqtt5::broker::storage::file_backend: Removed session for client: mqttx_635dff9b2
2026-07-03T16:28:19.487144Z DEBUG mqtt5::broker::client_handler: Removed session, queued, and inflight messages for client mqttx_635dff9b2
2026-07-03T16:28:19.487162Z INFO mqtt5::broker::client_handler: Client mqttx_635dff9b2 disconnected
2026-07-03T16:28:19.487179Z DEBUG mqtt5::broker::client_handler: Client handler dropped for mqttx_635dff9b2
2026-07-03T16:28:19.487289Z DEBUG mqtt5::broker::server: Client handler finished
2026-07-03T16:28:21.813421Z DEBUG mqtt5::broker::server: New TCP connection addr=127.0.0.1:39570
2026-07-03T16:28:21.813576Z DEBUG mqtt5::broker::client_handler: Client handler started for 127.0.0.1:39570 (TCP)
2026-07-03T16:28:21.814432Z DEBUG mqtt5::broker::client_handler::connect: Processing CONNECT packet client_id=mqttx_635dff9b2 addr=127.0.0.1:39570 protocol_version=5 clean_start=true keep_alive=60
2026-07-03T16:28:21.814472Z DEBUG mqtt5::broker::client_handler::connect: Client using MQTT v5.0 protocol_version=5 addr=127.0.0.1:39570
2026-07-03T16:28:21.814531Z DEBUG mqtt5::broker::client_handler::connect: Client connection limits client_id=mqttx_635dff9b2 receive_maximum=65535 max_packet_size=None
2026-07-03T16:28:21.814879Z DEBUG mqtt5::broker::client_handler::connect: Created new session with will_delay_interval: None
2026-07-03T16:28:21.815343Z DEBUG mqtt5::broker::client_handler::connect: Sending CONNACK client_id=mqttx_635dff9b2 session_present=false assigned_client_id=None
2026-07-03T16:28:21.815481Z DEBUG mqtt5::broker::client_handler::connect: CONNACK sent successfully
2026-07-03T16:28:21.815517Z INFO mqtt5::broker::client_handler: Client mqttx_635dff9b2 connected from 127.0.0.1:39570 (TCP)
2026-07-03T16:28:21.815550Z DEBUG mqtt5::broker::resource_monitor: Connection registered: mqttx_635dff9b2 from 127.0.0.1 (total: 1)
2026-07-03T16:28:21.815622Z INFO mqtt5::broker::router: Registered client: mqttx_635dff9b2
2026-07-03T16:28:21.859466Z DEBUG mqtt5::broker::router: Client mqttx_635dff9b2 subscribed to wildcard #
2026-07-03T16:28:21.859554Z DEBUG mqtt5::broker::client_handler::subscribe: Retained messages found for subscription topic=# count=0

[fabracht]

Hi, good catch. These examples are very old, so it's time I revisited them to make sure they show coherent behaviour.
The short answer is that simple_broker.rs never actually shuts the broker down. It's not a bug in the broker's shutdown logic, it's that the example races the broker instead of signaling it, so the background tasks get orphaned. Normally they only die because the process exits a moment later, which is I never noticed it.
broker.run() isn't just an accept loop. It spawns a bunch of detached background tasks (the $SYS publisher, the TCP/TLS/WS/QUIC accept loops, the resource monitor, storage, hot-reload) and then parks itself waiting on an internal shutdown broadcast:

shutdown_rx.recv().await.ok();   // parks here until the internal signal fires
info!("Broker shutting down");
sys_handle.abort();              // only now is the $SYS task stopped
// then all spawned handles are joined (5s timeout)

Those tasks are detached, so dropping the run() future does not cancel them. Only that internal signal leads to sys_handle.abort() and joining the accept loops. That's why $SYS keeps publishing and new clients can still connect after your "shutdown complete" line. The accept loops are still alive.

The example does the wrong thing here:

tokio::select! {
    result = broker.run() => { ... }
    _ = shutdown => { info!("Shutting down broker..."); }   // ctrl_c wins here
}

So, on Ctrl+C the shutdown branch wins and the broker.run() future is just dropped, so the cleanup never runs. MqttBroker::shutdown() is the graceful path it skips: it broadcasts the internal signal that stops the tasks, stops bridges, and flushes telemetry. You can't just bolt it onto the end though, since run() does self.shutdown_tx.take() on startup, so shutdown() becomes a no-op once it's running. The right pattern is to feed Ctrl+C into the same channel run() waits on instead of racing it in a select!.
I will fix the example and rework run()/shutdown() so an external signal triggers a real graceful shutdown, and refresh the other examples while I'm at it. You can track it here if you want: #92
Thanks.

[DenvE]

Thanks for the update.