Skip to content

Refactor Connect/Disconnect out to CClient with an explicit connection state #3805

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mcfnord wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Refactor Connect/Disconnect out to CClient with an explicit connection state #3805

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
43b5eb5
Refactor Connect out to CClient
pgScorpio Sep 13, 2024
1b49a78
Add explicit client connection state machine
Jul 19, 2026
efee722
client: address review feedback on the connection-state refactor
Jul 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 90 additions & 7 deletions src/client.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ CClient::CClient ( const quint16 iPortNumber,
strClientName ( strNClientName ),
pSignalHandler ( CSignalHandler::getSingletonP() ),
pSettings ( nullptr ),
eConnectionState ( CS_DISCONNECTED ),
Channel ( false ), /* we need a client channel -> "false" */
CurOpusEncoder ( nullptr ),
CurOpusDecoder ( nullptr ),
Expand Down Expand Up @@ -145,7 +146,7 @@ CClient::CClient ( const quint16 iPortNumber,
// The first ConClientListMesReceived handler performs the necessary cleanup and has to run first:
QObject::connect ( &Channel, &CChannel::ConClientListMesReceived, this, &CClient::OnConClientListMesReceived );

QObject::connect ( &Channel, &CChannel::Disconnected, this, &CClient::Disconnected );
QObject::connect ( &Channel, &CChannel::Disconnected, this, &CClient::Stop );

QObject::connect ( &Channel, &CChannel::NewConnection, this, &CClient::OnNewConnection );

Expand Down Expand Up @@ -618,6 +619,9 @@ bool CClient::SetServerAddr ( QString strNAddr )
// apply address to the channel
Channel.SetAddress ( HostAddress );

// By default, set server name to HostAddress. If using the Connect() method, this may be overwritten
SetConnectedServerName ( HostAddress.toString() );

return true;
}
else
Expand Down Expand Up @@ -905,13 +909,10 @@ void CClient::OnHandledSignal ( int sigNum )
{
case SIGINT:
case SIGTERM:
// if connected, terminate connection (needed for headless mode)
if ( IsRunning() )
{
Stop();
}
// tear down any pending or established connection first, so the server
// is notified we are leaving (Disconnect() is a no-op if not connected)
Disconnect();

// this should trigger OnAboutToQuit

@pljones pljones Jul 21, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe the comment should remain. The QCoreApplication::instance()->exit(); was added so that OnAboutToQuit got called.

QCoreApplication::instance()->exit();
break;

Expand Down Expand Up @@ -1003,6 +1004,9 @@ void CClient::OnClientIDReceived ( int iServerChanID )
SetRemoteChanGain ( iChanID, 0, false );
}

// the server has assigned us a channel ID, so the connection is established
SetConnectionState ( CS_CONNECTED );

emit ClientIDReceived ( iChanID );
}

Expand Down Expand Up @@ -1045,8 +1049,19 @@ void CClient::Start()
// Disable hibernation or display dimming if the app is running on Windows
SetThreadExecutionState ( ES_CONTINUOUS | ES_SYSTEM_REQUIRED | ES_DISPLAY_REQUIRED );
#endif

// the connection is requested now but not yet established: the transition
// to CS_CONNECTED happens when the server assigns our channel ID
// (see OnClientIDReceived)
SetConnectionState ( CS_CONNECTING );

emit Connecting ( GetConnectedServerName() );
}

/// @method
/// @brief Stops client and disconnects from server
/// @emit Disconnected
/// Use to set CClientDlg to show not being connected
void CClient::Stop()
{
// stop audio interface

@ann0see ann0see Jul 19, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The IsRunning() guard is not needed? (don't remember the initial argument of my PR.)

@ann0see ann0see Jul 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please check this - especially for the sigterm case: https://github.com/jamulussoftware/jamulus/pull/3805/changes#diff-7bc46552432fa03e009f9f455e4729312853d92775935ef20849797f24ac0c60R912-R913

@mcfnord mcfnord Jul 21, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed together with the guard above in efee722 — OnHandledSignal now calls Disconnect(), and the state-based guard means SIGTERM while CS_CONNECTING still sends CLM_DISCONNECTION (verified by capture).

@mcfnord mcfnord Jul 21, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch — a guard is needed, but IsRunning() was the wrong predicate.

IsRunning() is Sound.IsRunning() (the audio device). Start() sets CS_CONNECTING and calls Sound.Start() as separate steps, so the two diverge: during CS_CONNECTING, and in headless mode where audio may lag or be unavailable, the state is connecting/connected while IsRunning() is still false. Stop() is the only thing that sends CLDisconnection, and on the client there is no aboutToQuit handler and ~CClient() only does Sound.Stop() — so OnHandledSignal was calling raw Stop() precisely to dodge the guard and still notify the server on shutdown.

Fixed in efee722 by keying the guard off the explicit state this PR introduces, and routing SIGTERM through Disconnect():

void CClient::Disconnect()
{
    if ( GetConnectionState() != CS_DISCONNECTED ) { Stop(); }
}
// OnHandledSignal now: Disconnect();  (was: raw Stop();)

So Disconnect() stays idempotent (the repeated UI calls remain no-ops) and SIGTERM notifies the server whenever a connection is pending or established — including mid-connect and in headless mode. Dropped the stale // needed for headless mode / // this should trigger OnAboutToQuit comments (there is no client OnAboutToQuit).

Verified with a UDP capture: SIGTERM while connected → server receives CLM_DISCONNECTION; SIGTERM while idle → no spurious disconnect (the old raw Stop() sent one to a stale address); clean exit 0 in both cases.

Expand Down Expand Up @@ -1088,6 +1103,74 @@ void CClient::Stop()
// Allow hibernation or display dimming if the app is running again (Windows)
SetThreadExecutionState ( ES_CONTINUOUS );
#endif

SetConnectionState ( CS_DISCONNECTED );

// emit Disconnected() to inform UI of disconnection
emit Disconnected();
}

/// @method
/// @brief Disconnects from the server if a connection is requested or established.
/// Idempotent: a no-op when already disconnected.
/// @emit Disconnected
void CClient::Disconnect()
{
// Key off the connection state, not IsRunning() (which tracks the audio
// device): the two diverge while connecting and in headless mode, and on
// SIGTERM we must still send the disconnect message to the server.
if ( GetConnectionState() != CS_DISCONNECTED )
{
Stop();
}
}

/// @method
/// @brief Connects to strServerAddress. If a connection is currently requested
/// or established, that connection is terminated first.
/// @emit Connecting (strServerName) if SetServerAddr was valid. emit happens through Start().
/// Use to set CClientDlg to show being connected
/// @emit ConnectingFailed (error) if an error occurred
/// Use to display error message in CClientDlg
/// @param strServerAddress - the server address to connect to
/// @param strServerName - the human readable server name passed to Connecting()
void CClient::Connect ( QString strServerAddress, QString strServerName )
{
try
{
// disconnect from any current server first so that connecting to a
// different server while connected behaves as a reconnect
Disconnect();

// Set server address and connect if valid address was supplied
if ( SetServerAddr ( strServerAddress ) )
{
SetConnectedServerName ( strServerName );
Start();
}
else
{
throw CGenErr ( tr ( "Received invalid server address. Please check for typos in the provided server address." ) );
}
}
catch ( const CGenErr& generr )
{
Stop();
emit ConnectingFailed ( generr.GetErrorText() );
}
}

/// @method
/// @brief Updates the connection state and, if it changed, notifies observers.
/// @emit ConnectionStateChanged (state) when the state actually changes
/// @param eNewConnectionState - the state to transition to
void CClient::SetConnectionState ( const EConnectionState eNewConnectionState )

@ann0see ann0see Jul 19, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add documentation like for connect/disconnect.

@mcfnord mcfnord Jul 21, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in efee722 — added a /// @method doc-comment.

{
if ( eConnectionState != eNewConnectionState )
{
eConnectionState = eNewConnectionState;
emit ConnectionStateChanged ( eConnectionState );
}
}

void CClient::Init()
Expand Down
34 changes: 33 additions & 1 deletion src/client.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,17 @@
#endif

/* Definitions ****************************************************************/
// Client connection state -----------------------------------------------------
enum EConnectionState
{
// a connection is "requested" as soon as the client starts the audio
// stream towards the configured server and "established" once the server
// has assigned a channel ID to the client
CS_DISCONNECTED = 0, // no connection requested or established
CS_CONNECTING = 1, // connection requested but not yet established
CS_CONNECTED = 2 // connection established and current
};

// audio in fader range
#define AUD_FADER_IN_MIN 0
#define AUD_FADER_IN_MAX 100
Expand Down Expand Up @@ -159,6 +170,15 @@ class CClient : public QObject

void Start();
void Stop();
void Disconnect();
void Connect ( QString strServerAddress, QString strServerName );

// The ConnectedServerName is emitted by Connecting() to update the UI with a human readable server name
void SetConnectedServerName ( const QString strServerName ) { strConnectedServerName = strServerName; };
QString GetConnectedServerName() const { return strConnectedServerName; };

EConnectionState GetConnectionState() const { return eConnectionState; }

bool IsRunning() { return Sound.IsRunning(); }
bool IsCallbackEntered() const { return Sound.IsCallbackEntered(); }
bool SetServerAddr ( QString strNAddr );
Expand Down Expand Up @@ -353,6 +373,13 @@ class CClient : public QObject
void FreeClientChannel ( const int iServerChannelID );
int FindClientChannel ( const int iServerChannelID, const bool bCreateIfNew ); // returns a client channel ID or INVALID_INDEX
bool ReorderLevelList ( CVector<uint16_t>& vecLevelList ); // modifies vecLevelList, passed by reference
// human-readable name of the current server, shown in the UI
QString strConnectedServerName;

// current connection state; set only via SetConnectionState()
EConnectionState eConnectionState;

void SetConnectionState ( const EConnectionState eNewConnectionState );

// only one channel is needed for client application
CChannel Channel;
Expand Down Expand Up @@ -464,7 +491,8 @@ protected slots:
{
if ( InetAddr == Channel.GetAddress() )
{
emit Disconnected();
// Stop client in case it received a Disconnection request
Stop();
}
}
void OnCLPingReceived ( CHostAddress InetAddr, int iMs );
Expand Down Expand Up @@ -507,7 +535,11 @@ protected slots:

void CLChannelLevelListReceived ( CHostAddress InetAddr, CVector<uint16_t> vecLevelList );

void ConnectionStateChanged ( EConnectionState eConnectionState );
void Connecting ( QString strServerName );
void ConnectingFailed ( QString errorMessage );
void Disconnected();

void SoundDeviceChanged ( QString strError );
void ControllerInFaderLevel ( int iChannelIdx, int iValue );
void ControllerInPanValue ( int iChannelIdx, int iValue );
Expand Down
Loading
Loading