A Signal provides a mechanism for communication between objects. More...

#include <signal.h>

Public Member Functions
	Signal ()=default

	Signal (const Signal &)=delete

	Signal (Signal &&other) noexcept=default

	~Signal () noexcept

bool	blockConnection (const ConnectionHandle &handle, bool blocked)

template<typename Func , typename... FuncArgs, typename = std::enable_if_t<std::disjunction_v<std::negation<std::is_convertible<Func, std::function<void(Args...)>>>, std::integral_constant<bool, sizeof...(FuncArgs) >>>>
KDBINDINGS_WARN_UNUSED ConnectionHandle	connect (Func &&slot, FuncArgs &&...args)

KDBINDINGS_WARN_UNUSED ConnectionHandle	connect (std::function< void(Args...)> const &slot)

KDBINDINGS_WARN_UNUSED ConnectionHandle	connectDeferred (const std::shared_ptr< ConnectionEvaluator > &evaluator, std::function< void(Args...)> const &slot)
	Establishes a deferred connection between the provided evaluator and slot. More...

KDBINDINGS_WARN_UNUSED ConnectionHandle	connectReflective (std::function< void(ConnectionHandle &, Args...)> const &slot)

KDBINDINGS_WARN_UNUSED ConnectionHandle	connectSingleShot (std::function< void(Args...)> const &slot)

void	disconnect (const ConnectionHandle &handle)

void	disconnectAll () noexcept

void	emit (Args... p) const

bool	isConnectionBlocked (const ConnectionHandle &handle) const

Signal &	operator= (Signal &&other) noexcept=default

Signal &	operator= (Signal const &other)=delete

Detailed Description

template<typename... Args>
class KDBindings::Signal< Args >

A Signal provides a mechanism for communication between objects.

KDBindings::Signal recreates the Qt's Signals & Slots mechanism in pure C++17. A Signal can be used to notify any number of slots that a certain event has occurred.

The slot can be almost any callable object, including member functions and lambdas.

This connection happens in a type-safe manner, as a slot can only be connected to a Signal when the arguments of the slot match the values the Signal emits.

The Args type parameter pack describe which value types the Signal will emit.

Deferred Connection:

KDBindings::Signal supports deferred connections, enabling the decoupling of signal emission from the execution of connected slots. With deferred connections, you can connect slots to the Signal that are not immediately executed when the signal is emitted. Instead, you can evaluate these deferred connections at a later time, allowing for asynchronous or delayed execution of connected slots.

Examples:

Definition at line 71 of file signal.h.

Constructor & Destructor Documentation

◆ Signal() [1/3]

template<typename... Args>

KDBindings::Signal< Args >::Signal ( )

default

Signals are default constructible

◆ Signal() [2/3]

template<typename... Args>

KDBindings::Signal< Args >::Signal ( const Signal< Args > & )

delete

Signals cannot be copied.

◆ Signal() [3/3]

template<typename... Args>

KDBindings::Signal< Args >::Signal ( Signal< Args > && other )

defaultnoexcept

Signals can be moved

◆ ~Signal()

template<typename... Args>

KDBindings::Signal< Args >::~Signal ( )

inlinenoexcept

A signal disconnects all slots when it is destructed

Therefore, all active ConnectionHandles that belonged to this Signal will no longer be active (i.e. ConnectionHandle::isActive will return false).

Warning: While this function isn't marked as throwing, it may throw and terminate the program if it is not possible to allocate memory or if mutex locking isn't possible.

Definition at line 319 of file signal.h.

References KDBindings::Signal< Args >::disconnectAll().

Member Function Documentation

◆ blockConnection()

template<typename... Args>

bool KDBindings::Signal< Args >::blockConnection	(	const ConnectionHandle &	handle,
		bool	blocked
	)

inline

Sets the block state of the connection. If a connection is blocked, emitting the Signal will no longer call this connections slot, until the connection is unblocked.

ConnectionHandle::block can be used as an alternative.

To temporarily block a connection, consider using an instance of ConnectionBlocker, which offers a RAII-style implementation that makes sure the connection is always returned to its original state.

Parameters

blocked	Whether the connection should be blocked from now on.
handle	The ConnectionHandle to block.

Returns: Whether the connection was previously blocked.

Exceptions

std::out_of_range - If the ConnectionHandle does not belong to this Signal (i.e. ConnectionHandle::belongsTo returns false).

Definition at line 518 of file signal.h.

References KDBindings::ConnectionHandle::belongsTo().

◆ connect() [1/2]

template<typename... Args>

template<typename Func , typename... FuncArgs, typename = std::enable_if_t<std::disjunction_v<std::negation<std::is_convertible<Func, std::function<void(Args...)>>>, std::integral_constant<bool, sizeof...(FuncArgs) >>>>

KDBINDINGS_WARN_UNUSED ConnectionHandle KDBindings::Signal< Args >::connect	(	Func &&	slot,
		FuncArgs &&...	args
	)

inline

A template overload of Signal::connect that makes it easier to connect arbitrary functions to this Signal. It connects a function to this Signal, binds any provided arguments to that function and discards any values emitted by this Signal that aren't needed by the resulting function.

This is especially useful for connecting member functions to signals.

Examples:

Signal<int> signal;
std::vector<int> numbers{ 1, 2, 3 };
bool emitted = false;
 
// disambiguation necessary, as push_back is overloaded.
void (std::vector<int>::*push_back)(const int &) = &std::vector<int>::push_back;
signal.connect(push_back, &numbers);
 
// this slot doesn't require the int argument, so it will be discarded.
signal.connect([&emitted]() { emitted = true; });
 
signal.emit(4); // Will add 4 to the vector and set emitted to true

For more examples see the 07-advanced-connections/main.cpp example.

Returns: An instance of a Signal::ConnectionHandle that refers to this connection. Warning: When connecting a member function you must use the returned ConnectionHandle to disconnect when the object containing the slot goes out of scope!

Warning: Connecting functions to a signal that throw an exception when called is currently undefined behavior. All connected functions should handle their own exceptions. For backwards-compatibility, the slot function is not required to be noexcept.

Definition at line 455 of file signal.h.

◆ connect() [2/2]

template<typename... Args>

KDBINDINGS_WARN_UNUSED ConnectionHandle KDBindings::Signal< Args >::connect ( std::function< void(Args...)> const & slot )

inline

Connects a std::function to the signal.

When emit() is called on the Signal, the functions will be called with the arguments provided to emit().

Returns: An instance of ConnectionHandle, that can be used to disconnect or temporarily block the connection.

Warning: Connecting functions to a signal that throw an exception when called is currently undefined behavior. All connected functions should handle their own exceptions. For backwards-compatibility, the slot function is not required to be noexcept.

Definition at line 337 of file signal.h.

◆ connectDeferred()

template<typename... Args>

KDBINDINGS_WARN_UNUSED ConnectionHandle KDBindings::Signal< Args >::connectDeferred	(	const std::shared_ptr< ConnectionEvaluator > &	evaluator,
		std::function< void(Args...)> const &	slot
	)

inline

Establishes a deferred connection between the provided evaluator and slot.

Warning: Deferred connections are experimental and may be removed or changed in the future.

This function allows connecting an evaluator and a slot such that the slot's execution is deferred until the conditions evaluated by the evaluator are met.

First argument to the function is reference to a shared pointer to the ConnectionEvaluator responsible for determining when the slot should be executed.

Returns: An instance of ConnectionHandle, that can be used to disconnect or temporarily block the connection.

Note: The Signal class itself is not thread-safe. While the ConnectionEvaluator is inherently thread-safe, ensure that any concurrent access to this Signal is protected externally to maintain thread safety.

Warning: Connecting functions to a signal that throw an exception when called is currently undefined behavior. All connected functions should handle their own exceptions. For backwards-compatibility, the slot function is not required to be noexcept.

Definition at line 407 of file signal.h.

◆ connectReflective()

template<typename... Args>

KDBINDINGS_WARN_UNUSED ConnectionHandle KDBindings::Signal< Args >::connectReflective ( std::function< void(ConnectionHandle &, Args...)> const & slot )

inline

Establishes a connection between a signal and a slot, allowing the slot to access and manage its own connection handle. This method is particularly useful for creating connections that can autonomously manage themselves, such as disconnecting after being triggered a certain number of times or under specific conditions. It wraps the given slot function to include a reference to the ConnectionHandle as the first parameter, enabling the slot to interact with its own connection state directly.

Parameters

slot	A std::function that takes a ConnectionHandle reference followed by the signal's parameter types.

Returns: A ConnectionHandle to the newly established connection, allowing for advanced connection management.

Warning: Connecting functions to a signal that throw an exception when called is currently undefined behavior. All connected functions should handle their own exceptions. For backwards-compatibility, the slot function is not required to be noexcept.

Definition at line 358 of file signal.h.

Referenced by KDBindings::Signal< Args >::connectSingleShot().

◆ connectSingleShot()

template<typename... Args>

KDBINDINGS_WARN_UNUSED ConnectionHandle KDBindings::Signal< Args >::connectSingleShot ( std::function< void(Args...)> const & slot )

inline

Establishes a single-shot connection between a signal and a slot and when the signal is emitted, the connection will be disconnected and the slot will be called. Note that the slot will be disconnected before it is called. If the slot triggers another signal emission of the same signal, the slot will not be called again.

Parameters

slot	A std::function that takes the signal's parameter types.

Returns: An instance of ConnectionHandle, that can be used to disconnect.

Warning: Connecting functions to a signal that throw an exception when called is currently undefined behavior. All connected functions should handle their own exceptions. For backwards-compatibility, the slot function is not required to be noexcept.

Definition at line 377 of file signal.h.

References KDBindings::Signal< Args >::connectReflective().

◆ disconnect()

template<typename... Args>

void KDBindings::Signal< Args >::disconnect ( const ConnectionHandle & handle )

inline

Disconnect a previously connected slot.

After the slot was successfully disconnected, the ConnectionHandle will no longer be active. (i.e. ConnectionHandle::isActive will return false).

Exceptions

std::out_of_range - If the ConnectionHandle does not belong to this Signal (i.e. ConnectionHandle::belongsTo returns false).

Definition at line 470 of file signal.h.

References KDBindings::ConnectionHandle::belongsTo().

◆ disconnectAll()

template<typename... Args>

void KDBindings::Signal< Args >::disconnectAll ( )

inlinenoexcept

Disconnect all previously connected functions.

All currently active ConnectionHandles that belong to this Signal will no longer be active afterwards. (i.e. ConnectionHandle::isActive will return false).

Warning: While this function is marked with noexcept, it may terminate the program if it is not possible to allocate memory or if mutex locking isn't possible.

Definition at line 489 of file signal.h.

Referenced by KDBindings::Signal< Args >::~Signal().

◆ emit()

template<typename... Args>

void KDBindings::Signal< Args >::emit ( Args... p ) const

inline

Emits the Signal, which causes all connected slots to be called, as long as they are not blocked.

The arguments provided to emit will be passed to each slot by copy, therefore consider using (const) references as the Args to the Signal wherever possible.

Note: Slots may disconnect themselves during an emit, which will cause the connection to be disconnected after all slots have been called.

⚠️ Note: Connecting a new slot to a signal while the signal is still in the emit function is undefined behavior.

⚠️ Note: This function is not thread-safe and not reentrant. Specifically, this means it is undefined behavior to emit a signal from a slot of that same signal.

Definition at line 568 of file signal.h.

Referenced by KDBindings::Property< T >::~Property().

◆ isConnectionBlocked()

template<typename... Args>

bool KDBindings::Signal< Args >::isConnectionBlocked ( const ConnectionHandle & handle ) const

inline

Checks whether the connection is currently blocked.

To change the blocked state of a connection, call blockConnection().

Returns: Whether the connection is currently blocked

Exceptions

std::out_of_range - If the ConnectionHandle does not belong to this Signal (i.e. ConnectionHandle::belongsTo returns false).

Definition at line 536 of file signal.h.

References KDBindings::ConnectionHandle::belongsTo().

◆ operator=() [1/2]

template<typename... Args>

Signal& KDBindings::Signal< Args >::operator= ( Signal< Args > && other )

defaultnoexcept

◆ operator=() [2/2]

template<typename... Args>

Signal& KDBindings::Signal< Args >::operator= ( Signal< Args > const & other )

delete

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

Public Member Functions

Detailed Description

template<typename... Args> class KDBindings::Signal< Args >

Constructor & Destructor Documentation

◆ Signal() [1/3]

◆ Signal() [2/3]

◆ Signal() [3/3]

◆ ~Signal()

Member Function Documentation

◆ blockConnection()

◆ connect() [1/2]

◆ connect() [2/2]

◆ connectDeferred()

◆ connectReflective()

◆ connectSingleShot()

◆ disconnect()

◆ disconnectAll()

◆ emit()

◆ isConnectionBlocked()

◆ operator=() [1/2]

◆ operator=() [2/2]

template<typename... Args>
class KDBindings::Signal< Args >