src/OSspecific/Unix/timer.H

   1 /*---------------------------------------------------------------------------*\
   2   =========                 |
   3   \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
   4    \\    /   O peration     |
   5     \\  /    A nd           | Copyright (C) 1991-2008 OpenCFD Ltd.
   6      \\/     M anipulation  |
   7 -------------------------------------------------------------------------------
   8 License
   9     This file is part of OpenFOAM.
  10
  11     OpenFOAM is free software; you can redistribute it and/or modify it
  12     under the terms of the GNU General Public License as published by the
  13     Free Software Foundation; either version 2 of the License, or (at your
  14     option) any later version.
  15
  16     OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
  17     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  18     FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  19     for more details.
  20
  21     You should have received a copy of the GNU General Public License
  22     along with OpenFOAM; if not, write to the Free Software Foundation,
  23     Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
  24
  25 Class
  26     Foam::timer
  27
  28 Description
  29     Implements a timeout mechanism via sigalarm.
  30
  31     Example usage:
  32     @code
  33         timer myTimer(5);     // 5 sec
  34         ..
  35         if (timedOut(myTimer))
  36         {
  37             // timed out
  38         }
  39         else
  40         {
  41             // do something possible blocking
  42         }
  43     @endcode
  44
  45     Constructor set signal handler on sigalarm and alarm(). Destructor
  46     clears these.
  47
  48     timedOut is macro because setjmp can't be in member function of timer.
  49     ?something to do with stack frames.
  50
  51 Warning
  52     The setjmp restores complete register state so including local vars
  53     held in regs. So if in blocking part something gets calced in a stack
  54     based variable make sure it is declared 'volatile'.
  55
  56 SourceFiles
  57     timer.C
  58
  59 \*---------------------------------------------------------------------------*/
  60
  61 #ifndef timer_H
  62 #define timer_H
  63
  64 #include "className.H"
  65
  66 #include <signal.h>
  67 #include <setjmp.h>
  68
  69 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
  70
  71 //- check it a timeout has occured
  72 //  keep setjmp in same stack frame so no function calls
  73 #define timedOut(x) \
  74     (((x).newTimeOut_ > 0) ? setjmp(Foam::timer::envAlarm) : false)
  75
  76 namespace Foam
  77 {
  78
  79 /*---------------------------------------------------------------------------*\
  80                            Class timer Declaration
  81 \*---------------------------------------------------------------------------*/
  82
  83 class timer
  84 {
  85     // Private data
  86
  87         //- old signal masks
  88         static struct sigaction oldAction_;
  89
  90         //- old alarm() value
  91         static unsigned int oldTimeOut_;
  92
  93
  94     // Private Member Functions
  95
  96         //- alarm handler
  97         static void signalHandler(int);
  98
  99
 100 public:
 101
 102     // Public data
 103
 104         //- Declare name of the class and its debug switch
 105         ClassName("timer");
 106
 107         //- current time out value. Needed by macro timedOut
 108         unsigned int newTimeOut_;
 109
 110         //- state for setjmp. Needed by macro timedOut
 111         static jmp_buf envAlarm;
 112
 113
 114     // Constructors
 115
 116         //- Construct from components.
 117         //  newTimeOut=0 makes it do nothing.
 118         timer(const unsigned int newTimeOut);
 119
 120
 121     // Destructor
 122
 123         ~timer();
 124 };
 125
 126
 127 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 128
 129 } // End namespace Foam
 130
 131 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 132
 133 #endif
 134
 135 // ************************************************************************* //