QApplication subclass enforcing single-instance behavior via IPC. More...

#include <singleapplication.h>

Inheritance diagram for SingleApplication:

Collaboration diagram for SingleApplication:

Public Slots
void	receiveMessage ()
	Slot for QLocalServer::newConnection: accept every pending connection and emit messageAvailable() with what it sent.

Signals
void	messageAvailable (const QString &message)
	messageAvailable notification from commandline

Public Member Functions
	SingleApplication (int &argc, char *argv[], QString uniqueKey)
	Construct a SingleApplication with a unique instance key.
auto	isRunning () -> bool
	Query whether another instance is already running.
auto	sendMessage (const QString &message) -> bool
	Send a message to the running instance.

Private Member Functions
auto	peerIsListening () -> bool
	Probe whether an instance is actually accepting connections.
void	becomePrimary ()
	Claim the segment and listen; no-op when another instance holds it.
auto	forwardMessage (const QString &message) -> bool
	Deliver a message over the local socket.

Private Attributes
bool	_isRunning
	true when another instance holds the segment and answers on the socket; this instance should forward and exit.
QString	_uniqueKey
	Name of both the shared-memory segment and the local socket.
QSharedMemory	sharedMemory
	The one-byte segment whose existence marks a running instance.
QScopedPointer< QLocalServer >	localServer
	Server accepting forwarded command lines; only set in the primary instance, null in a secondary or when listening failed.

Static Private Attributes
static const int	timeout = 1000
	Milliseconds to wait for a socket connect or write.
static const int	maxMessageBytes = 64 * 1024
	Upper bound for one forwarded message (a command line).
static const int	takeoverProbes = 5
	Probes for the winner of a takeover race before giving up on IPC.
static const int	takeoverProbeIntervalMs = 100
	Pause between two takeover probes, in milliseconds.

Detailed Description

QApplication subclass enforcing single-instance behavior via IPC.

Detects whether another instance with the same unique key is running and enables forwarding messages (e.g., command-line arguments) to it.

Definition at line 24 of file singleapplication.h.

Constructor & Destructor Documentation

◆ SingleApplication()

SingleApplication::SingleApplication	(	int &	argc,
		char *	argv[],
		QString	uniqueKey )

Construct a SingleApplication with a unique instance key.

Attaches to the shared-memory segment named uniqueKey. If an instance answers on the local socket this becomes a secondary and isRunning() turns true; if the segment is stale (left behind by a crash) or absent, this instance claims it and starts listening.

Parameters

argc	Reference to program argc forwarded to QApplication.
argv	Program argv forwarded to QApplication.
uniqueKey	Key used to identify and scope the single instance.

Definition at line 16 of file singleapplication.cpp.

Member Function Documentation

◆ becomePrimary()

void SingleApplication::becomePrimary ( )

private

Claim the segment and listen; no-op when another instance holds it.

When the segment is already taken the other launcher is probed a few times (see takeoverProbes) and, if it answers, this becomes a secondary. Otherwise isRunning() stays false and the caller runs without IPC rather than not at all.

Definition at line 82 of file singleapplication.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ forwardMessage()

auto SingleApplication::forwardMessage ( const QString & message ) -> bool

private

Deliver a message over the local socket.

Parameters

message Text to send; an empty string is sent as a single NUL so the peer still sees a connection with data.

Returns: true if the peer accepted the whole payload.

Definition at line 122 of file singleapplication.cpp.

Here is the caller graph for this function:

◆ isRunning()

auto SingleApplication::isRunning ( ) -> bool

Query whether another instance is already running.

Returns: true if another instance with the same key is running.

Definition at line 62 of file singleapplication.cpp.

Here is the caller graph for this function:

◆ messageAvailable

void SingleApplication::messageAvailable ( const QString & message )

signal

messageAvailable notification from commandline

Parameters

message args sent to qtpass executable

Here is the call graph for this function:

Here is the caller graph for this function:

◆ peerIsListening()

auto SingleApplication::peerIsListening ( ) -> bool

private

Probe whether an instance is actually accepting connections.

Returns: true if a connection to the unique key succeeded.

Definition at line 142 of file singleapplication.cpp.

Here is the caller graph for this function:

◆ receiveMessage

void SingleApplication::receiveMessage ( )

slot

Slot for QLocalServer::newConnection: accept every pending connection and emit messageAvailable() with what it sent.

Each accepted socket is read asynchronously so a peer that connects without sending anything cannot stall the GUI thread; the message is delivered once the peer disconnects and the socket is then deleted.

Definition at line 38 of file singleapplication.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ sendMessage()

auto SingleApplication::sendMessage ( const QString & message ) -> bool

Send a message to the running instance.

When delivery fails the peer is taken to have exited since the constructor probed it: this instance releases its segment and, if it can, becomes the listening instance itself, so isRunning() turns false and the window the caller opens next is reachable by later launches.

Parameters

message Text to deliver (typically forwarded command-line args).

Returns: true if the message was successfully delivered.

Definition at line 64 of file singleapplication.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ _isRunning

bool SingleApplication::_isRunning

private

true when another instance holds the segment and answers on the socket; this instance should forward and exit.

Definition at line 103 of file singleapplication.h.

◆ _uniqueKey

QString SingleApplication::_uniqueKey

private

Name of both the shared-memory segment and the local socket.

Definition at line 105 of file singleapplication.h.

◆ localServer

QScopedPointer<QLocalServer> SingleApplication::localServer

private

Server accepting forwarded command lines; only set in the primary instance, null in a secondary or when listening failed.

Definition at line 112 of file singleapplication.h.

◆ maxMessageBytes

const int SingleApplication::maxMessageBytes = 64 * 1024

staticprivate

Upper bound for one forwarded message (a command line).

The socket is user-only, but a peer that keeps a connection open and streams data would otherwise grow the per-connection buffer without limit; anything past this is dropped and the peer disconnected.

Definition at line 123 of file singleapplication.h.

◆ sharedMemory

QSharedMemory SingleApplication::sharedMemory

private

The one-byte segment whose existence marks a running instance.

Definition at line 107 of file singleapplication.h.

◆ takeoverProbeIntervalMs

const int SingleApplication::takeoverProbeIntervalMs = 100

staticprivate

Pause between two takeover probes, in milliseconds.

Definition at line 127 of file singleapplication.h.

◆ takeoverProbes

const int SingleApplication::takeoverProbes = 5

staticprivate

Probes for the winner of a takeover race before giving up on IPC.

Definition at line 125 of file singleapplication.h.

◆ timeout

const int SingleApplication::timeout = 1000

staticprivate

Milliseconds to wait for a socket connect or write.

Definition at line 115 of file singleapplication.h.

The documentation for this class was generated from the following files:

src/singleapplication.h
src/singleapplication.cpp

Public Slots

Signals

Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ SingleApplication()

Member Function Documentation

◆ becomePrimary()

◆ forwardMessage()

◆ isRunning()

◆ messageAvailable

◆ peerIsListening()

◆ receiveMessage

◆ sendMessage()

Member Data Documentation

◆ _isRunning

◆ _uniqueKey

◆ localServer

◆ maxMessageBytes

◆ sharedMemory

◆ takeoverProbeIntervalMs

◆ takeoverProbes

◆ timeout