cpp-signal

cpp-signal is a header-only pure C++11 library providing signal and slot functionality. Using it is as easy as

#include <cpp-signal.h>
...
auto slot = [](int value) -> int
{
  std::cout << "slot(" << value << << ")" << std::endl;

  return 2 * value;
}

cpp_signal<>::signal<int(int)> signal;
signal.connect(slot);

signal.emit(1);  // prints "slot(1)"
signal.emit(2);  // prints "slot(2)"

signal.disconnect(slot);

signal.emit(3);  // this will not call the slot

which will result in the following output on standard out:

slot(1)
slot(2)

Table of Contents

• Requirements
  • Buildsystem
  • Compilers
• Features
  • Type-safety
  • Managed connections
  • Flexible slots
  • Signal chaining
  • Copying
  • Slot result collection
  • Threading policy
  • Asynchronous signal emission
• Known Issues
  • Deadlocks
• Performance
• The Future

Requirements

The only thing required to use cpp-signal is a C++11 compliant compiler.

Buildsystem

To be able to run the tests provided with cpp-signal CMake 3.1 or newer is required. Run the following commands to build the tests and execute them:

# mkdir build
# cd build
# cmake ..
# cmake --build
# ctest -C Debug

Compilers

cpp-signal has been explictely tested with the following compilers:

• gcc
  • 5.4.0
  • 5.5.0
• clang
  • 7.0.0
• Apple LLVM
  • 9.1.0
• MSVC
  • Visual Studio 2015 (v140 / 1900) requires some legacy code (see MSVC_LEGACY in cpp-signal-async.h)
  • Visual Studio 2017 (v141 / 1916)

Features

Type-safety

Thanks to C++11's variadic templates cpp-signal calls are completely type-safe. It is not possible to connect a slot with mismatching return type and or parameter list to a signal. Furthermore it is not possible to emit a signal with mismatching parameters.

Managed connections

With cpp-signal's slot_tracker class it is possible to automatically keep track of all methods in a class that have been connected to different signals as slots. It's as simple as deriving from slot_tracker which will take care of automatically disconnecting all connected slots when an object is destroyed.

class tracked_class : public cpp_signal<>::slot_tracker
{
  ...
}

Flexible slots

cpp-signal is very flexible when it comes to connecting slots to a signal.

Static (global) methods

static void global_slot(int value)
{
  std::cout << "global_slot(" << value << ")" << std::endl;
}
...
cpp_signal<>::signal<void(int)> signal;
signal.connect<global_slot>();

signal.emit(1);  // prints "global_slot(1)"

Static and non-static class methods

class test_class
{
  public:
    static void static_slot(int value)
    {
      std::cout << "static_slot(" << value << ")" << std::endl;
    }

    static void slot(int value)
    {
      std::cout << "slot(" << value << ")" << std::endl;
    }
};

test_class test;

cpp_signal<>::signal<void(int)> signal;
signal.connect<&test_class::static_slot>();  // connects the static class method
signal.connect<test_class, &test_class::slot>(test);  // connects the non-static class method

signal.emit(1);  // prints "static_slot(1)" and "slot(1)"

Callables

class test_class
{
  public:
    void operator()(int value)
    {
      std::cout << "test_class(" << value << ")" << std::endl;
    }
};

test_class test;

auto lambda = [](int value) { std::cout << "lambda(" << value << ")" << std::endl; };

cpp_signal<>::signal<void(int)> signal;
signal.connect(test);  // connects the callable test_class object
signal.connect(lambda);  // connects the callable lambda expression

signal.emit(1);  // prints "test_class(1)" and "lambda(1)"

Signal chaining

Due to the fact that any callable object can be used as a slot it is also possible to use cpp-signal's signal class as a slot therefore effectively chaining multiple signals together. There's nothing more to it.

cpp_signal<>::signal<void(int)> signal;
cpp_signal<>::signal<void(int)> chained_signal;

auto slot = [](int value) { std::cout << "slot(" << value << << ")" << std::endl; }

signal.connect(slot);
signal.connect(chained_signal);
chained_signal.connect(slot);

signal.emit(1);

will result in slot being called twice: once as a direct slot of signal and once as a slot of chained_signal.

Copying

cpp-signal features full support for copying classes deriving from slot_tracker including signal:

• when copying a tracked slot connected to a signal the copied slot will automatically also be connected to the same signal
• when copying a signal with connected slots the copied signal will have the same slots connected

Slot result collection

cpp-signal does not only support signals and slots with return type void but any copyable return type. A signal emitted using signal::emit() will simply discard the returned value(s). But using the special signal::emit_collect() method with a matching collector (which can be any callable object) it is possible to access and possibly collect all the values returned by connected slots. As with the rest of cpp-signal any collector needs to match the signal's return type or it will not even compile.

cpp_signal<>::signal<int(int)> signal;

auto slot_one = [](int value) -> int { return value; };
signal.connect(slot_one);
auto slot_two = [](int value) -> int { return value * 2; };
signal.connect(slot_two);

signal.emit(1);  // the values returned by the slots is discarded

int total = 0;
auto collector = [&total](int value) { total += value; }

signal.emit_collect(collector, 1);  // total == 3

Threading policy

When it comes to threading there are many different applications out there with different needs. Some applications run in a single thread and concurrency is not an issue. Other applications use multiple threads which can all potentially interact with signals and it is necessary to protect the signal's internal state. Because locking isn't free and has a negative impact on performance cpp-signal does not enforce locking but rather provides the possibility to choose the best fitting threading policy. This is achieved by specifying the threading policy in cppsignal<TThreadingPolicy>. cpp-signal comes with the following threading policies:

• No locking (default): cpp_signal_no_locking
• Global locking: cpp_signal_global_locking
• Local locking: cpp_signal_local_locking = std::mutex
• Local recursive locking: cpp_signal_recursive_local_locking = std::recursive_mutex

It is also possible to implement and use custom threading policies. All that is required by any threading policy is to implement the following methods (matching std::mutex):

void lock();
void unlock();

Asynchronous signal emission

In addition to the cpp-signal.h header file cpp-signal comes with a second (optional) header file cpp-signal-async.h which provides cpp_signal_async<>. cpp_signal_async<> provides the same functionalities as cpp_signal<> but emitting a signal will be done asynchronously i.e. in a seperate thread.

#include <chrono>
#include <thread>

#include <cpp-signal-async.h>
...
auto slot = [](int value) -> int
{
  std::this_thread::sleep_for(std::chrono::milliseconds(1000));
  std::cout << "slot(" << value << << ")" << std::endl;

  return 2 * value;
}

cpp_signal<>::signal<int(int)> signal;
signal.connect(slot);

std::cout << "signal.emit(1)" << std::endl;
signal.emit(1);  // prints "slot(1)"
std::cout << "signal.emit(2)" << std::endl;
signal.emit(2);  // prints "slot(2)"

std::cout << "signal.disconnect(slot)" << std::endl;
signal.disconnect(slot);

std::cout << "signal.emit(3)" << std::endl;
signal.emit(3);  // this will not call the slot

will result in the following output:

signal.emit(1)
signal.emit(2)
slot(1)
signal.disconnect(slot)
slot(2)
slot(3)

As can be seen the order is not the same as if it would be executed synchronously.

Due to the asynchronous emission of signals there are a few things that need to be kept in mind:

• signal objects cannot be modified while they are being asynchronously emitted. It is possible to call any modifying methods on a signal object but it will block until the signal has finished the asynchronous emission.
• cpp_signal_async<> also supports specifying the locking policy. While for cpp_signal<> the default locking policy is no locking at all for cpp_signal_async<> the default locking policy is std::mutex because it needs to be thread-safe. When choosing a different locking policy it is the users responsibility to provide a thread-safe locking policy.
• All emission methods (emit(), accumulate(), accumulate_op(), aggregate() and collect()) return an std::future<> to be able to wait for emission to finish and to be able to access any results. As opposed to when using std::future<> returned from std::async() the returned std::future<> does not have to be stored and used but can be ignored. Either way the emission will be executed asynchronously (which is not the case with std::async()).

Known Issues

Deadlocks

Right now cpp-signal is not fully thread safe / reentrant and does not support recursive signal emissions within slots. Doing so may cause a deadlock if the emissions affect multiple threads. The reported issue will stay open until this has been resolved.

Performance

Based on the benchmarks used by nano-signal-slot cpp-signal ranks fourth right on nano-signal-slot's and Wink-Signals tails:

* library is designed to always be thread-safe

The Future

I'm always open for new ideas and feedback.