/usr/share/doc/libbobcat4-dev/man/signal.3.html

<!DOCTYPE html><html><head>
<meta charset="UTF-8">
<title>FBB::Signal(3bobcat)</title>
<style type="text/css">
    figure {text-align: center;}
    img {vertical-align: center;}
    .XXfc {margin-left:auto;margin-right:auto;}
    .XXtc {text-align: center;}
    .XXtl {text-align: left;}
    .XXtr {text-align: right;}
    .XXvt {vertical-align: top;}
    .XXvb {vertical-align: bottom;}
</style>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr/>
<h1 id="title">FBB::Signal(3bobcat)</h1>
<h2 id="author">signal handler<br/>(libbobcat-dev_4.08.02-x.tar.gz)</h2>
<h2 id="date">2005-2017</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 (2) or SIGTERM (15) ... 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_4.08.02-x.dsc</em>: detached signature;
    <li> <em >bobcat_4.08.02-x.tar.gz</em>: source archive;
    <li> <em >bobcat_4.08.02-x_i386.changes</em>: change log;
    <li> <em >libbobcat1_4.08.02-x_*.deb</em>: debian package holding the
            libraries;
    <li> <em >libbobcat1-dev_4.08.02-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>
</body>
</html>
libbobcat-dev 4.08.02-2build1 / usr / share / doc / libbobcat4-dev / man / signal.3.html
