ATMI C Function Reference
|
 |
 |
|
 |
 |
Usignal(3c)
Name
Usignal()—Signal handling in a BEA Tuxedo ATMI system environment.
Synopsis
#include "Usignal.h"
UDEFERSIGS()
UENSURESIGS()
UGDEFERLEVEL()
URESUMESIGS()
USDEFERLEVEL(level)
int (*Usignal(sig,func)()
int sig;
int (*func)();
void Usiginit()
Description
Many of the facilities provided by the BEA Tuxedo ATMI system software require concurrent access to data structures in shared memory. Processes accessing the shared data structures run in user mode, and are thus interruptible by signals sent to them. In order to ensure the consistency of the shared data structures, it is important that the operations which access them not be interrupted by the receipt of certain UNIX signals. The functions described in this section provide protection against the most common signals, and are used internally by much of the BEA Tuxedo ATMI system code. Additionally, they are available to applications to prevent the untimely arrival of a signal.
The idea behind the BEA Tuxedo ATMI system signal handling package is that signals should be deferrable while in critical code sections. To this end, signals are not immediately processed when received. Instead, a BEA Tuxedo ATMI system routine first catches the sent signal. If it is safe to process the signal, the specified action for the signal is taken. If it is not safe to process the signal when it arrives, the arrival is noted, but the processing is deferred until the user indicates that the critical section of code has been terminated.
We recommend against any use of signals in multithreaded programs, although the software does not prevent such usage. If signals are used, however, a thread in a multithreaded application may issue a call to Usignal() while running in any context state, including TPINVALIDCONTEXT.
Catching Signals
User code that uses calls rmopen() or tpinit() should catch signals through the use of the Usignal() function. Usignal() behaves like the UNIX signal() system call, except that Usignal() first arranges for the signal to be caught by an internal routine before dispatching the user routine.
Deferring and Restoring Signals
The calls described in this section need only be used if application code wishes to defer signals. In general, these routines are called automatically by BEA Tuxedo ATMI system routines to protect themselves from untimely signal arrival.
Before deferring or restoring signals, the mechanism must be initialized. This is done automatically for BEA Tuxedo ATMI system clients when they call tpinit() and for BEA Tuxedo ATMI system servers. It is also done the first time that the application calls Usignal(). It can be done explicitly by calling Usiginit().
The UDEFERSIGS() macro should be used when entering a section of critical code. After UDEFERSIGS() is called, signals are held in a pending state. The URESUMESIGS() macro should be invoked when the critical section is exited. Note that signal deferrals stack. The stack is implemented via a counter which is initially set to zero. When signals are deferred by a call to UDEFERSIGS(), the counter is incremented. When signals are resumed, by a call to URESUMESIGS(), the counter is decremented. If a signal arrives while the counter is non-zero, the processing of the signal is deferred. If the counter is zero when the signal arrives, the signal is processed immediately. If signal resumption causes the counter to be become zero (that is, prior to the resumption it had value 1), any signals that arrived during the deferral period are processed. In general, each call to UDEFERSIGS() should have a counterpart call to URESUMESIGS().
UDEFERSIGS increments the deferral counter, but returns the value of the counter prior to its incrementation. The macro UENSURESIGS() may be used to explicitly set the deferral counter to zero (and thus force the processing of deferred signals), in case the user wishes to protect against unmatching UDEFERSIGS() and URESUMESIGS().
The function UGDEFERLEVEL() returns the current setting of the deferral counter. The macro USDEFERLEVEL(level) allows the setting of a specific deferral level. UGDEFERLEVEL() and USDEFERLEVEL() are useful to set the counter appropriately in setjmp/longjmp situations where a set of deferrals/resumes are bypassed. The idea is to save the value of the counter when setjmp() is called, via a call to UGDEFERLEVEl(), and to restore it via a call to USDEFERLEVel() when the longjmp() is performed.
Notices
Usignal provides signal deferral for the following signals: SIGHUP,SIGINT, SIGQUIT, SIGALRM, SIGTERM, SIGUSR1, and SIGUSR2. Handling requests for all other signal numbers are passed directly to signaL() by Usignal(). Signals may be deferred for a considerable time. For this reason, during signal deferral, individual signal arrivals are counted. When it is safe to process a signal that may have arrived many times, the signal's processing routine is iteratively called to process each arrival of the signal. Before each call the default action for the signal is instantiated. The idea is to handle the deferred occurrences of the signal as if they happened in quick succession in safe code.
In general, users should not mix calls to signaL() and UsignaL() for the same signal. The recommended procedure is to go through Usignal(), so that it is always aware of the state of the signal. Sometimes it may be necessary, such as when an application wants to use alarms within BEA Tuxedo ATMI system services. To do this, UsiginiT() should be called to initialize the signal deferring mechanism. Then signaL() can be called to override the mechanism for the desired signal. To restore the deferring mechanism for the signal, it is necessary to call UsignaL() for the signal with SIG_IGN, and then again with the desired signal-handling function.
The shell variable UIMMEDSIGS can be used to override the deferral of signals. If the value of this variable begins with the letter y as in:
UIMMEDSIGS=y
signals are not intercepted (and thus not deferred) by the Usignal() code. In such a case, a call to Usignal() is passed immediately to signaL().
Usignal is not available under DOS operating systems.
