FBB::Signal(3bobcat)

📦
version 6.15.01 · 7 versions
, in ubuntu stonking

💖 FBB::Signal 💖 — the signal handler page from bobcat(3bobcat), bestie edition

okay so. you're reading a manual page. yes a manual page, we're doing this. this one's FBB::Signal(3bobcat) and it lives in the signal handler corner of the bobcat docs. grab a snack. 🍓

🌸 NAME 🌸

FBB::Signal — Signal Handler. that's it. that's the whole name section. short and iconic. 💅

✨ SYNOPSIS ✨

#include <bobcat/signal>
Linking option: -lbobcat

yes the -lbobcat is required, do not fight it, just link the library. 🫶

🦋 DESCRIPTION 🦋

okay so here's the tea. signals have a very well known drawback: they arrive free of context. like a text from a number you don't have saved. 😭

say your program runs a flow control loop like this:

void Class::run()
{
    while (d_continue)
        handleTasks();
    cleanup();
}

and now the program needs to recognize a termination signal. the typical signal handler looks like this:

void signalHandler(int signal)
{
    // perform required actions
}

the problem? since the signalHandler is called asynchronically, there is no context available. so the usual way of communicating between objects and signal handlers is via static variables, like this:

// declared as static bool s_continue;
bool Class::s_continue = true;

void Class::run()
{
    while (s_continue)
        handleTasks();
    cleanup();
}

// declared as static void signalHander(int signal);
void Class::signalHandler(int signal)
{
    s_continue = false;
}

(and yes, that typo signalHander is in the original and i am preserving it. archival queen behavior. 👑)

so the class Signal exists to let the signal handler operate in the context of a class. the advantage of this is that static data members are no longer required, and that the signal may be used to control data members of individual objects. that's the glow-up. ✨

the signal is now handled by an object, whose class must define a member

void signalHandler(size_t signum) override;

and this function is responsible for handling the received signal. since it's a member function it may affect its object's local variables and it may call its object's member functions. static data members are not required anymore (scroll down for an example). 🎀

⚠️ important, bestie, do NOT skip this: as the signal may arrive at unpredicable times, data members that can be modified by signalHandler should be declared using the volatile modifier. moreover, data that can be modified by the signalHandler member and by other class members should be protected by mutexes (cf. the C++-11 class std::mutex or pthread_mutex_lock(3posix)). this is not a vibe suggestion, this is a "your program will be haunted" situation. 💀

🌈 NAMESPACE 🌈

FBB

all constructors, members, operators and manipulators mentioned in this man-page are defined in the namespace FBB.

🎀 INHERITS FROM 🎀

Signal is not derived from other classes. but the classes for which signals must be handled by Signal must themselves publicly be derived from the class FBB::SignalHandler, and must implement a member

void signalHandler(size_t signum) override;

handling the received signal. so like. it's not the one inheriting. it's the one being inherited from. the main character energy is honestly reversed here and that's fine. 💅

💜 CONSTRUCTORS AND OVERLOADED OPERATORS 💜

Signal is defined as a singleton, and it does not offer public or protected constructors, nor does it offer overloaded operators. there's exactly one. no clones. no sequels. no overloads. periodt. 🙈

⭐ STATIC MEMBER FUNCTION ⭐

  • static Signal &instance() — this static member can be used to access a reference to the program's single Signal object. the one. the only. 🫶

💅 MEMBER FUNCTIONS 💅

all of Signal's member functions can only be called through a reference to the program's Signal object, returning a reference to the program's single Signal object. yeah we said it twice. it matters.

  • void add(size_t signum, SignalHandler &object) — the SignalHandler object is activated on arrival of signal signum. if multiple SignalHandler objects must be called, then multiple Signal::add calls can be provided, and the various SignalHandler::signalHandler members are called in the same sequence as their respective Signal::add calls. if one of the earlier signalHandler members terminates the program, then later signalHandler members are not activated anymore. also: if Signal::add is called by, e.g., an object's constructor, then its destructor should call Signal::remove to prevent the object's signal handler from being called after its destruction. (that last one is the classic oopsie. don't be that girl. 😭)
  • void remove(size_t signum, SignalHandler &object) — the SignalHandler object for signal signum is removed from the Signal object. it is the responsibility of object to deregister itself from Signal just before object goes out of scope. objects can only deregister themselves if they've previously registered themselves using add. no take-backs for things you never did. 🎀
  • void ignore(size_t signum) — any previously installed SignalHandler object is no longer activated on arrival of signal signum. in addition, if possible, signal signum is completely ignored (some signals cannot be caught, blocked, of ignored, like SIGKILL and SIGSTOP (cf. signal(7))). yes that "of ignored" is in the original, we love her, she stays. 💀
  • void reset(size_t signum) — any previously installed SignalHandler object is no longer activated on arrival of signal signum. in addition, the default action the program takes on arrival of signal signum is reinstalled (cf. signal(7)). back to factory settings. 🌸
heads up: if the signum value that is passed to Signal's members is not a defined signal value, then an FBB::Exception exception is thrown. so like, validate your inputs. 😭

🔥 EXAMPLE 🔥

this is the full demo. every line. no skipping. (it slays, honestly.)

#include <sys/types.h>
#include <unistd.h>

#include <iostream>

#include <bobcat/signal>

class SignalDemo: public FBB::SignalHandler
{
    volatile size_t d_signal;
    volatile bool d_continue;
    pid_t d_pid;

    public:
        SignalDemo();
        void run();

    private:
        void signalHandler(size_t signum) override;
};

using namespace std;
using namespace FBB;

SignalDemo::SignalDemo()
:
    d_signal(0),
    d_continue(true),
    d_pid(getpid())
{}

void SignalDemo::run()
{
    while (d_continue)
    {
        cout << "Send a SIGINT (2) or SIGTERM (15) ... to process " <<
                    d_pid << endl;

        sleep(1);
    }
    cout << "Ending `run’ after receiving signal " << d_signal << endl;
}

void SignalDemo::signalHandler(size_t signal)
{
    if (signal == SIGINT)
        cout << "Process " << d_pid << " received SIGINT" << endl;
    else if (signal == SIGTERM)
    {
        cout << "Process " << d_pid << " received SIGTERM" << endl;
        d_signal = SIGTERM;
        d_continue = false;
    }
}

int main()
{
    SignalDemo signalDemo;

    Signal::instance().add(SIGINT, signalDemo);
    Signal::instance().add(SIGTERM, signalDemo);

    signalDemo.run();
}

notice the volatile on d_signal and d_continue? that's the description section paying rent. 💅

🌸 FILES 🌸

  • bobcat/signal — defines the class interface

🦋 SEE ALSO 🦋

🙈 BUGS 🙈

None Reported. (not me being suspiciously calm about that. 💀)

🌈 BOBCAT PROJECT FILES 🌈

Debian Bobcat project files:

  • libbobcat6: debian package containing the shared library, changelog and copyright note;
  • libbobcat-dev: debian package containing the static library, headers, manual pages, and developer info;

👑 BOBCAT 👑

Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’. yes it's an acronym and it's a cat. we stan a double threat. 🐱

This is free software, distributed under the terms of the GNU General Public License (GPL).

🎀 AUTHOR 🎀

Frank B. Brokken (f.b.brokken@rug.nl).

okay that's the whole page bestie, you're officially Signal-literate, go forth and handle signals in context, protect your shared data with mutexes, and never call a signal handler after destruction. 🫶

signing off from FBB::Signal(3bobcat) — this lovely thing ships as libbobcat-dev_6.15.01, dated 2005-2026, and you read every word, which is honestly iconic of you. ✨🌺💖

📦 where this page comes from