/[ascend]/trunk/base/generic/utilities/ascSignal.h
ViewVC logotype

Contents of /trunk/base/generic/utilities/ascSignal.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 526 - (show annotations) (download) (as text)
Fri Apr 21 13:47:31 2006 UTC (14 years, 7 months ago) by johnpye
File MIME type: text/x-chdr
File size: 11680 byte(s)
Fixed up a problem with ordering of headers with Python.h.
Removed psyco initialisation, pending evidence that it actually does something :-)
Disabled python 'director' error message callbacks, trying to debug a segfault.
Added ability to disable GCC Visibility, scons WITH_GCCVISIBILITY=0.
Turned off runtime signal tests for SIG_INT and SIG_FPE (makes using GDB a pain), see base/generic/utilities/ascSignal.[ch].
1 /* ASCEND modelling environment
2 Copyright (C) 1997 Benjamin Andrew Allan
3 Copyright (C) 2006 Carnegie Mellon University
4
5 This program is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published by
7 the Free Software Foundation; either version 2, or (at your option)
8 any later version.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 GNU General Public License for more details.
14
15 You should have received a copy of the GNU General Public License
16 along with this program; if not, write to the Free Software
17 Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
19 *//**
20 @file
21 Signal handling protocol definitions for ASCEND.
22
23 This file standardizes the handling of signals because some OS
24 reset signals to SIG_DFL when a trap goes off while others
25 process the signal but leave the trapping function in place.
26 We want the second behavior and this gives it to us.
27
28 This module implements limited support for managing signal handlers.
29 This includes:
30 - a standard signal handler - Asc_SignalTrap()
31 - global jmp_buf's for use with Asc_SignalTrap()
32 - functions for managing nested signal handlers
33
34 The following signal types are currently supported:
35 - SIGFPE - floating point exception
36 - SIGINT - CTRL-C interactive attention request
37 - SIGSEGV - segmentation fault
38
39 A simple use of these facilities to trap floating point exceptions
40 might be as follows:
41 <pre>
42 Asc_SignalInit();
43 Asc_SignalHandlerPush(SIGFPE, Asc_SignalTrap);
44 if (setjmp(g_fpe_env)==0) {
45 y = sqrt(x);
46 } else {
47 y = sqrt(-x);
48 }
49 Asc_SignHandlerPop(SIGFPE,Asc_SignalTrap);
50 Asc_SignalDestroy();
51 </pre>
52 * This example uses the built-in signal handler Asc_SignalTrap()
53 * and the global <code>jmp_buf</code> g_fpe_env. After initializing
54 * the signal manager and registering the handler, <code>setjmp</code>
55 * is used to select normal and exception paths. The <code>setjmp</code>
56 * returns 0 when initially called and the sqrt(x) is calculated. If
57 * x is negative, a SIGFPE exception occurs and the handler is called. It
58 * uses <code>lngjmp</code> and returns to the if statement, and now
59 * <setjmp> returns non-zero and the <code>else</code> clause is executed.
60 * Finally, the handler is removed and the signal manager cleaned up.<br><br>
61 *
62 * The stack mechanism also allows nested handlers to be registered. It is
63 * important to note that nested handlers for the same signal type cannot
64 * both use Asc_SignalTrap() as the handler. This is because different
65 * <code>jmp_buf</code> variables must be used and Asc_SignalTrap() uses
66 * the same global <code>jmp_buf</code> each time. However, you can use
67 * custome <code>jmp_buf</code>'s and handlers:
68 * <pre>
69 * Asc_SignalInit();
70 * Asc_SignalHandlerPush(SIGFPE, Asc_SignalTrap);
71 * if (setjmp(g_fpe_env) == 0) {
72 * y = sqrt(x);
73 * Asc_SignalHandlerPush(SIGFPE, my_handler);
74 * if (setjmp(my_jmp_buf) == 0) {
75 * y = z/x;
76 * } else {
77 * Asc_Panic(1, NULL, "Div by zero error.");
78 * }
79 * Asc_SignHandlerPop(SIGFPE, my_handler);
80 * } else {
81 * y = sqrt(-x);
82 * }
83 * Asc_SignHandlerPop(SIGFPE,Asc_SignalTrap);
84 * Asc_SignalDestroy();
85 * </pre>
86 * Here, exceptions in the sqrt(x) calculation are handled by the standard
87 * Asc_SignalTrap(), while the division is handled by my_handler.<br><br>
88 *
89 * Avoid mixing use of the signal manager with direct calls to signal().
90 * Once Asc_SignalInit() has been called, use of signal() directly is likely
91 * to be lost or to corrupt the managed handlers.<br><br>
92 *
93 * Another warning: setjmp is expensive if called inside a fast loop.
94
95 Requires:
96 #include "utilities/ascConfig.h"
97 *//*
98 Signal handling protocol definitions for ASCEND
99 May 27, 1997
100 By Benjamin Andrew Allan
101 Version: $Revision: 1.6 $
102 Version control file: $RCSfile: ascSignal.h,v $
103 Date last modified: $Date: 1998/01/10 18:00:05 $
104 Last modified by: $Author: ballan $
105 */
106
107 #ifndef ASC_ASCSIGNAL_H
108 #define ASC_ASCSIGNAL_H
109
110 #ifndef lint
111 static CONST char ascSignalRCS[] = "$Id: ascSignal.h,v 1.6 1998/01/10 18:00:05 ballan Exp $";
112 #endif
113
114 #include <signal.h>
115 #include <setjmp.h>
116 #include <utilities/ascConfig.h>
117 #ifdef __WIN32__
118 # include <process.h>
119 #else
120 # include <unistd.h>
121 #endif
122
123 typedef void (*SigHandler)(int);
124 /**< Signature of a signal handling function. */
125
126 #define MAX_TRAP_DEPTH 40L
127 /**< The maximum number of traps that can be nested. */
128
129 ASC_DLLSPEC(jmp_buf ) g_fpe_env; /**< Standard signal jmp_buf - floating point error. */
130 extern jmp_buf g_seg_env; /**< Standard signal jmp_buf - segmentation fault. */
131 extern jmp_buf g_int_env; /**< Standard signal jmp_buf - interactive attention (<CTRL>C). */
132
133 extern jmp_buf g_foreign_code_call_env;
134 /**<
135 * Not currently in use. Should be when we get to a unified
136 * standard for signal handling.
137 * @todo Implement use of g_foreign_code_call_env?
138 */
139
140 ASC_DLLSPEC(void ) Asc_SignalTrap(int sigval);
141 /**<
142 * Standard signal handler.
143 * This is the trap that should be used for most applications in
144 * ASCEND. It prints a message then calls longjmp(GLOBAL, sigval)
145 * where GLOBAL is one of g_fpe_env, g_seg_env, or g_int_env.
146 * Because the jmp_buf is global, so you can't nest calls to
147 * setjmp where both use this trap function.<br><br>
148 *
149 * Trivial Example:
150 * <pre>
151 * Asc_SignalHandlerPush(SIGFPE,Asc_SignalTrap);
152 * if (setjmp(g_fpe_env)==0) {
153 * y = sqrt(x);
154 * } else {
155 * y = sqrt(-x);
156 * }
157 * Asc_SignHandlerPop(SIGFPE,Asc_SignalTrap);
158 *
159 * For x < 0 the else is called because setjmp returns nonzero
160 * when the body of the 'if' signals range error.
161 * </pre>
162 * Remember always to use Asc_SignalHandlerPush() and
163 * Asc_SignalHandlerPop(). You can write an alternate function
164 * to use instead of AscSignalTrap() if need be. The signals
165 * SIGFPE, SIGINT, SIGSEGV are understood.<br><br>
166 *
167 * Note - this handler does not reinstall itself. After an exception,
168 * you need to reinstall the handler (if desired) using
169 * Asc_SignalRecover().
170 *
171 * @todo Should utilities/ascSignal.c:Asc_SignalTrap() reinstall itself
172 * after it catches an expection using Asc_SignalRecover()?
173 * @param sigval Holds the signal type code when called during
174 * an exception.
175 */
176
177 extern int Asc_SignalInit(void);
178 /**<
179 * Initializes the signal manager.
180 * This should be called before using any of the signal handling
181 * functions in this module. It initializes the internal stacks
182 * for mangaging signal handlers. This function does not install
183 * any signal handlers (although any existing handlers are left
184 * in place). Calling this function more than once will have no
185 * effect and an error code will be returned.<br><br>
186 *
187 * @return Returns 0 if successful, 1 if memory could not be
188 * allocated, and 2 if an error occurred.
189 */
190
191 extern void Asc_SignalDestroy(void);
192 /**<
193 * Cleans up and destroys the stacks of signal handlers.
194 * It does not change the status of any registered signal handlers
195 * That is, any handlers registered when this function is called
196 * will still be registered. It is important to call
197 * Asc_SignalHandlerPop() for each occurrence of Asc_SignalHandlerPush()
198 * before calling this function. Otherwise, any signal handlers
199 * that were installed before Asc_SignalInit() was called will be lost.
200 */
201
202 ASC_DLLSPEC(void ) Asc_SignalRecover(int force);
203 /**<
204 * Reinstalls the most recently pushed handler that has been
205 * installed for each supported signal type. This should be called
206 * after every trapped exception and at any other time when the
207 * status of exception handlers may have become not well-defined.
208 * If no handler has been pushed for a given signal type, SIG_DFL is
209 * installed. Note that the standard handler function Asc_SignalTrap()
210 * does not call this function. If you use the standard handler and
211 * you want it reinstalled after an exception, be sure to call this
212 * function after the longjmp return. This call is not particularly
213 * cheap if it does the reinstallation.<br><br>
214 *
215 * This module tests on startup for whether the OS reverts to
216 * SIG_DFL when a trap function is called. If it does NOT then
217 * this function will simply return unless force != 0. You don't
218 * want to call this function with force == 1 normally after a
219 * caught exception. However, if you're not sure of the handler
220 * installation status and want to make sure the handlers are
221 * installed, call with force == 1. Also, gdb or other
222 * debuggers which intercept and screw up signals may require
223 * applying force (manually) to ensure that the signals get
224 * reinstalled.
225 *
226 * @param force If non-zero, the most recent handlers are
227 * reinstalled even if not required by the
228 * compiler/platform.
229 */
230
231 ASC_DLLSPEC(int ) Asc_SignalHandlerPush(int signum, SigHandler func);
232 /**<
233 * Adds a handler to the stack of signal handlers for the given signal.
234 * There is a maximum stack limit, so returns 1 if limit exceeded.
235 * Returns -1 if stack of signal requested does not exist.
236 * Pushing a NULL handler func does NOT change anything at all.
237 * On a successful return, the handler has been installed and will
238 * remain installed until a Asc_SignalHandlerPop() or another push.
239 * The handler will remain installed as long as Asc_SignalRecover()
240 * is used properly after every exception.
241 *
242 * @param signum The signal type that func should handle.
243 * @param func The signal handler to register for signum signal types.
244 * @return Returns 1 if the stack limit is exceeded, -1 if managing
245 * of signals for the specified signum is not supported or
246 * initialized, or 0 if the function completes successfully.
247 * @todo Shouldn't utilities/ascSignal.c:Asc_SignalHandlerPush() return
248 * an error code on a NULL func? It seems too easy for someone to
249 * accidentally push a NULL without realizing it, and then later
250 * popping an unintended handler.
251 */
252
253 ASC_DLLSPEC(int ) Asc_SignalHandlerPop(int signum, SigHandler func);
254 /**<
255 * Removes the last-pushed handler from the stack for signum signal types.
256 * If the removed handler is the same as func, it is uninstalled and
257 * replaced with the handler now at the top of the stack. If not, non-zero
258 * is returned and you need to call Asc_SignalRecover() to uninstall the
259 * current handler if desired. Note that the top handler is popped off
260 * the stack whether it matches func or not. Non-zero is also returned if
261 * the stack is empty. A side effect is that all managed signal types will
262 * have the registered handlers reinstalled.
263 *
264 * @param signum The signal type whose top-most handler should be replaced.
265 * @param func The handler function that should be at the top of the
266 * stack (and currently installed) for signals of type signum.
267 * @return Returns non-zero if func is not the replaced handler or if
268 * the stack is empty, 0 if the function completed successfully.
269 * @todo Does it make more sense for utilities/ascSignal.c:Asc_SignalHanderPop()
270 * to fail completely if func is not the top-most handler? It is not
271 * clear why the function should pop the top handler no matter what, but
272 * only call Asc_SignalRecover() if it matches func.
273 */
274
275 #endif /* ASC_ASCSIGNAL_H */
276

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22