/usr/share/doc/libbobcat3/man/signal.3.html

<html><head>
<title>FBB::Signal</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::Signal</h1>
<h2>libbobcat-dev_3.23.01-x.tar.gz</h2>
<h2>2005-2014</h2>

<html><head>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1></h1>

<html><head>
<title>FBB::Signal(3bobcat)</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::Signal(3bobcat)</h1>
<h2>libbobcat-dev_3.23.01-x.tar.gz signal handler</h2>
<h2>2005-2014</h2>


<p>
<h2>NAME</h2>FBB::Signal - Signal Handler
<p>
<h2>SYNOPSIS</h2>
    <strong>#include &lt;bobcat/signal&gt;</strong><br>
    Linking option: <em>-lbobcat</em> 
<p>
<h2>DESCRIPTION</h2>
<p>
Signals have the well known drawback that signals arrive free of
context. E.g., assume a program runs a flow control loop like this:
    <pre>

void Class::run()
{
    while (d_continue)
        handleTasks();
    cleanup();
}
    
</pre>

    then if the program needs to recognize  a termination signal then the
typical signal handler looks like this:
    <pre>

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

    Since the <em>signalHandler</em> is called asynchronically, there is no context
available, and the usual way of communicating between objects and signal
handlers is via static variables, like this:
    <pre>

// 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;
}
    
</pre>

    The class <em>Signal</em> allows the signal handler to 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. 
<p>
The signal is now handled by an object, whose class must define a member 
        <pre>

    void signalHandler(size_t signum) override;
        
</pre>

    and this function is responsible for handling the received signal. Since
it is 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 (see below for an example).
<p>
Note that, as the signal may arrive at unpredicable times data members
that can be modified by <em>signalHandler</em> should be declared using the
<em>volatile</em> modifier. Moreover, data that can be modified by
the <em>signalHandler</em> member and by other class members should be protected
by <em>mutexes</em> (cf. the <strong>C++-11</strong> class <em>std::mutex</em> or
<strong>pthread_mutex_lock</strong>(3posix)). 
<p>
<h2>NAMESPACE</h2>
    <strong>FBB</strong><br>
    All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace <strong>FBB</strong>.
<p>
<h2>INHERITS FROM</h2>
    <em>Signal</em> is not derived from other classes, but the classes for which
signals must be handled by <em>Signal</em> must themselves publicly be derived from
the class <em>FBB::SignalHandler</em> and must implement a member 
        <pre>

    void signalHandler(size_t signum) override;
        
</pre>

    handling the received signal.
<p>
<h2>CONSTRUCTORS AND OVERLOADED OPERATORS</h2>
    <em>Signal</em> is defined as a <em>singleton</em>, and does not offer public or
protected constructors, nor does it offer overloaded operators.
<p>
<h2>STATIC MEMBER FUNCTION</h2>
    <ul>
    <li> <strong>static Signal &amp;instance()</strong>:<br><br>
        This static member can be used to access a reference to the program's
single <em>Signal</em> object.
    </ul>
<p>
<h2>MEMBER FUNCTIONS</h2>
    All of <em>Signal</em>'s member functions can only be called through a
reference to the program's <em>Signal</em> object, returning a reference to the
program's single <em>Signal</em> object:
    <ul>
    <li> <strong>void add(size_t signum, SignalHandler &amp;object)</strong>:<br><br> 
       <em>SignalHandler object</em> is activated on arrival of signal
        <em>signum</em>. If multiple <em>SignalHandler</em> objects must be called then
        multiple <em>Signal::add</em> calls can be provided, and the various
        <em>SignalHandler::signalHandler</em> members are called in the same
        sequence as their respective <em>Signal::add</em> calls. If one of the
        earlier <em>signalHandler</em> members terminates the program then later
        <em>signalHandler</em> members are not activated anymore. If
        <em>Signal::add</em> is called by, e.g., an object's constructor, then its
        destructor should call <em>Signal::remove</em> to prevent the object's
        signal handler from being called after its destruction.
    <li> <strong>void remove(size_t signum, SignalHandler &amp;object)</strong>:<br><br> 
       <em>SignalHandler object</em> for signal <em>signum</em> is removed from the
        <em>Signal</em> object. It is the responsibility of <em>object</em> to
        deregister itself from <em>Signal</em> just before <em>object</em> goes out of
        scope. Objects can only deregister themselves if they've previously
        registered themselves using <em>add</em>.
    <li> <strong>void ignore(size_t signum)</strong>:<br><br>
       Any previously installed <em>SignalHandler</em> object is no longer
        activated on arrival of signal <em>signum</em>. In addition, if possible,
        signal <em>signum</em> is completely ignored (some signals cannot be
        caught, blocked, of ignored, like <em>SIGKILL</em> and <em>SIGSTOP</em>
        (cf. <strong>signal</strong>(7))).
    <li> <strong>void reset(size_t signum)</strong>:<br><br>
       Any previously installed <em>SignalHandler</em> object is no longer
        activated on arrival of signal <em>signum</em>. In addition, the default
        action the program takes on arrival of signal <em>signum</em> is
        reinstalled (cf. <strong>signal</strong>(7)).
    </ul>
<p>
If the <em>signum</em> value that is passed to <em>Signal</em>'s members is not a
defined signal value, then an <strong>FBB::Exception</strong> exception is thrown. 
<p>
<h2>EXAMPLE</h2>
    <pre>
#include &lt;sys/types.h&gt;
#include &lt;unistd.h&gt;

#include &lt;iostream&gt;

#include "../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 &lt;&lt; "Send a SIGINT or SIGTERM... to process " &lt;&lt; d_pid &lt;&lt; endl;
        sleep(1);
    }
    cout &lt;&lt; "Ending `run' after receiving signal " &lt;&lt; d_signal &lt;&lt; endl;
}

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

int main()
{
    SignalDemo signalDemo;

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

    signalDemo.run();
}





</pre>

<p>
<h2>FILES</h2>
    <em>bobcat/signal</em> - defines the class interface
<p>
<h2>SEE ALSO</h2>
    <strong>bobcat</strong>(7), <strong>pthread_mutex_lock</strong>(3posix), <strong>signal</strong>(7),<br>
    and the <strong>C++-11</strong> class <em>std::mutex</em>.
<p>
<h2>BUGS</h2>
    None Reported.
<p>

<h2>DISTRIBUTION FILES</h2>
    <ul>
    <li> <em>bobcat_3.23.01-x.dsc</em>: detached signature;
    <li> <em>bobcat_3.23.01-x.tar.gz</em>: source archive;
    <li> <em>bobcat_3.23.01-x_i386.changes</em>: change log;
    <li> <em>libbobcat1_3.23.01-x_*.deb</em>: debian package holding the
            libraries;
    <li> <em>libbobcat1-dev_3.23.01-x_*.deb</em>: debian package holding the
            libraries, headers and manual pages;
    <li> <em>http://sourceforge.net/projects/bobcat</em>: public archive location;
    </ul>
<p>
<h2>BOBCAT</h2>
    Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
<p>
<h2>COPYRIGHT</h2>
    This is free software, distributed under the terms of the 
    GNU General Public License (GPL).
<p>
<h2>AUTHOR</h2>
    Frank B. Brokken (<strong>f.b.brokken@rug.nl</strong>).
<p>
libbobcat-dev 3.23.01-1 / usr / share / doc / libbobcat3 / man / signal.3.html
