    interrupt
      Copyright (c)  2015,2016 John Abbott
      GNU Free Documentation License, Version 1.2
%!includeconf: ../aux-txt2tags/config.t2t
      TeXTitle{interrupt}{John Abbott}


== Examples ==[examples]
%----------------------------------------------------------------------
- [ex-interrupt1.C ../../examples/index.html#ex-interrupt1.C]
-

== User documentation ==
%======================================================================

This file offers the 1-ary procedure ``CheckForInterrupt`` which
takes a string (indicating the "context" of the call).  It does
nothing unless the interrupt signal monitor has been set, in which
case it throws a ``CoCoA::InterruptReceived``.  Normally it makes
sense to call ``CheckForInterrupt`` only inside loops which may take
a long time to complete.

Since ``CheckForInterrupt`` may throw a ``CoCoA::InterruptReceived``
object, this exception should be caught and handled (unless you want
the program to exit).

The address of the interrupt signal monitor is given to the [[GlobalManager]]
via a call to the member function ``myNewInterruptSignalReceivedPtr``.
If no signal monitor has been specified then ``CheckForInterrupt`` will
never throw.

One way to allow signals to interrupt CoCoA computations is the following:
- ``SignalInterruptsCoCoA(sig)`` the signal ``sig`` will set the signal monitor
  which will trigger an interrupt when ``CheckForInterrupt`` is called.


Note: ``SignalInterruptsCoCoA`` calls ``myNewInterruptSignalReceivedPtr``
internally, and sets it to a "private" monitor (a global variable inside
the source file "interrupt.C").


=== Constructors and pseudo-constructors ===[constructors]
%----------------------------------------------------------------------

An object of the class ``InterruptReceived`` is thrown as an exception
when an interrupt has been detected (by calling ``CheckForInterrupt``).
The class has one data member for storing the signal which triggered
the interrupt:
- ``InterruptReceived(sig, context)`` where ``sig`` is the signal (integer),
  and ``context`` is a string


The class ``InterruptReceived`` is derived from [[exception]].

The destructor of an ``InterruptReceived`` has the side-effect of resetting
the interrupt signal monitor (if the [[GlobalManager]] still exists).

- ``TriggeredBySignal(intr)`` gives the signal stored inside the ``InterruptReceived``
- ``context(intr)`` gives the string stored inside (inherited from [[exception]])


== Maintainer documentation ==
%======================================================================

See also the documentation for [[GlobalManager]].

The implementation is extremely simple.  ``CheckForInterrupt`` does
nothing unless an interrupt signal monitor has been specified to the
``GlobalManager`` and the monitor has been set, in which case it throws
an ``InterruptReceived`` object (passing the signal and the context
string as constructor args).

``CheckForInterrupt`` is not inline because I do not think it needs to be.

The ``InterruptReceived`` is derived from ``exception``; the exception
subobject contains the message "External interrupt", and the context
string (which was given to the call to ``CheckForInterrupt``, and
which should indicate the location of that call).

The only "tricky" part is that its destructor resets the interrupt flag
if one has been specified.



== Bugs, shortcomings and other ideas ==
%======================================================================

JAA is slightly uneasy about the "tricky" destructor which resets the
interrupt flag (but cannot see how it could cause trouble).


== Main changes ==
%======================================================================

**2016**
- November (v0.99544): added field to store the triggering signal.


**2015**
- May (v0.99536): first release


