Originální popis anglicky:
sigtimedwait, sigwaitinfo - wait for queued signals (
REALTIME)
Návod, kniha: POSIX Programmer's Manual
#include <signal.h>
int sigtimedwait(const sigset_t *restrict
set,
siginfo_t *restrict
info ,
const struct timespec *restrict
timeout);
int sigwaitinfo(const sigset_t *restrict
set,
siginfo_t *restrict
info );
The
sigtimedwait() function shall be equivalent to
sigwaitinfo()
except that if none of the signals specified by
set are pending,
sigtimedwait() shall wait for the time interval specified in the
timespec structure referenced by
timeout. If the
timespec
structure pointed to by
timeout is zero-valued and if none of the
signals specified by
set are pending, then
sigtimedwait() shall
return immediately with an error. If
timeout is the NULL pointer, the
behavior is unspecified. If the Monotonic Clock option is supported,
the CLOCK_MONOTONIC clock shall be used to measure the time interval specified
by the
timeout argument.
The
sigwaitinfo() function selects the pending signal from the set
specified by
set. Should any of multiple pending signals in the range
SIGRTMIN to SIGRTMAX be selected, it shall be the lowest numbered one. The
selection order between realtime and non-realtime signals, or between multiple
pending non-realtime signals, is unspecified. If no signal in
set is
pending at the time of the call, the calling thread shall be suspended until
one or more signals in
set become pending or until it is interrupted by
an unblocked, caught signal.
The
sigwaitinfo() function shall be equivalent to the
sigwait()
function if the
info argument is NULL. If the
info argument is
non-NULL, the
sigwaitinfo() function shall be equivalent to
sigwait(), except that the selected signal number shall be stored in
the
si_signo member, and the cause of the signal shall be stored in the
si_code member. If any value is queued to the selected signal, the
first such queued value shall be dequeued and, if the
info argument is
non-NULL, the value shall be stored in the
si_value member of
info. The system resource used to queue the signal shall be released
and returned to the system for other use. If no value is queued, the content
of the
si_value member is undefined. If no further signals are queued
for the selected signal, the pending indication for that signal shall be
reset.
Upon successful completion (that is, one of the signals specified by
set
is pending or is generated)
sigwaitinfo() and
sigtimedwait()
shall return the selected signal number. Otherwise, the function shall return
a value of -1 and set
errno to indicate the error.
The
sigtimedwait() function shall fail if:
- EAGAIN
- No signal specified by set was generated within the
specified timeout period.
The
sigtimedwait() and
sigwaitinfo() functions may fail if:
- EINTR
- The wait was interrupted by an unblocked, caught signal. It
shall be documented in system documentation whether this error causes
these functions to fail.
The
sigtimedwait() function may also fail if:
- EINVAL
- The timeout argument specified a tv_nsec
value less than zero or greater than or equal to 1000 million.
An implementation only checks for this error if no signal is pending in
set and it is necessary to wait.
The following sections are informative.
None.
The
sigtimedwait() function times out and returns an [EAGAIN] error.
Application writers should note that this is inconsistent with other functions
such as
pthread_cond_timedwait() that return [ETIMEDOUT].
Existing programming practice on realtime systems uses the ability to pause
waiting for a selected set of events and handle the first event that occurs
in-line instead of in a signal-handling function. This allows applications to
be written in an event-directed style similar to a state machine. This style
of programming is useful for largescale transaction processing in which the
overall throughput of an application and the ability to clearly track states
are more important than the ability to minimize the response time of
individual event handling.
It is possible to construct a signal-waiting macro function out of the realtime
signal function mechanism defined in this volume of
IEEE Std 1003.1-2001. However, such a macro has to include the
definition of a generalized handler for all signals to be waited on. A
significant portion of the overhead of handler processing can be avoided if
the signal-waiting function is provided by the kernel. This volume of
IEEE Std 1003.1-2001 therefore provides two signal-waiting
functions-one that waits indefinitely and one with a timeout-as part of the
overall realtime signal function specification.
The specification of a function with a timeout allows an application to be
written that can be broken out of a wait after a set period of time if no
event has occurred. It was argued that setting a timer event before the wait
and recognizing the timer event in the wait would also implement the same
functionality, but at a lower performance level. Because of the performance
degradation associated with the user-level specification of a timer event and
the subsequent cancellation of that timer event after the wait completes for a
valid event, and the complexity associated with handling potential race
conditions associated with the user-level method, the separate function has
been included.
Note that the semantics of the
sigwaitinfo() function are nearly
identical to that of the
sigwait() function defined by this volume of
IEEE Std 1003.1-2001. The only difference is that
sigwaitinfo() returns the queued signal value in the
value
argument. The return of the queued value is required so that applications can
differentiate between multiple events queued to the same signal number.
The two distinct functions are being maintained because some implementations may
choose to implement the POSIX Threads Extension functions and not implement
the queued signals extensions. Note, though, that
sigwaitinfo() does
not return the queued value if the
value argument is NULL, so the POSIX
Threads Extension
sigwait() function can be implemented as a macro on
sigwaitinfo().
The
sigtimedwait() function was separated from the
sigwaitinfo()
function to address concerns regarding the overloading of the
timeout
pointer to indicate indefinite wait (no timeout), timed wait, and immediate
return, and concerns regarding consistency with other functions where the
conditional and timed waits were separate functions from the pure blocking
function. The semantics of
sigtimedwait() are specified such that
sigwaitinfo() could be implemented as a macro with a NULL pointer for
timeout.
The
sigwait functions provide a synchronous mechanism for threads to wait
for asynchronously-generated signals. One important question was how many
threads that are suspended in a call to a
sigwait() function for a
signal should return from the call when the signal is sent. Four choices were
considered:
- 1.
- Return an error for multiple simultaneous calls to
sigwait functions for the same signal.
- 2.
- One or more threads return.
- 3.
- All waiting threads return.
- 4.
- Exactly one thread returns.
Prohibiting multiple calls to
sigwait() for the same signal was felt to
be overly restrictive. The "one or more" behavior made
implementation of conforming packages easy at the expense of forcing POSIX
threads clients to protect against multiple simultaneous calls to
sigwait() in application code in order to achieve predictable behavior.
There was concern that the "all waiting threads" behavior would
result in "signal broadcast storms", consuming excessive CPU
resources by replicating the signals in the general case. Furthermore, no
convincing examples could be presented that delivery to all was either simpler
or more powerful than delivery to one.
Thus, the consensus was that exactly one thread that was suspended in a call to
a
sigwait function for a signal should return when that signal occurs.
This is not an onerous restriction as:
- *
- A multi-way signal wait can be built from the single-way
wait.
- *
- Signals should only be handled by application-level code,
as library routines cannot guess what the application wants to do with
signals generated for the entire process.
- *
- Applications can thus arrange for a single thread to wait
for any given signal and call any needed routines upon its arrival.
In an application that is using signals for interprocess communication, signal
processing is typically done in one place. Alternatively, if the signal is
being caught so that process cleanup can be done, the signal handler thread
can call separate process cleanup routines for each portion of the
application. Since the application main line started each portion of the
application, it is at the right abstraction level to tell each portion of the
application to clean up.
Certainly, there exist programming styles where it is logical to consider
waiting for a single signal in multiple threads. A simple
sigwait_multiple() routine can be constructed to achieve this goal. A
possible implementation would be to have each
sigwait_multiple() caller
registered as having expressed interest in a set of signals. The caller then
waits on a thread-specific condition variable. A single server thread calls a
sigwait() function on the union of all registered signals. When the
sigwait() function returns, the appropriate state is set and condition
variables are broadcast. New
sigwait_multiple() callers may cause the
pending
sigwait() call to be canceled and reissued in order to update
the set of signals being waited for.
None.
Realtime Signals ,
pause() ,
pthread_sigmask() ,
sigaction() ,
sigpending() ,
sigsuspend() ,
sigwait() , the Base Definitions volume of
IEEE Std 1003.1-2001,
<signal.h>,
<time.h>
Portions of this text are reprinted and reproduced in electronic form from IEEE
Std 1003.1, 2003 Edition, Standard for Information Technology -- Portable
Operating System Interface (POSIX), The Open Group Base Specifications Issue
6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics
Engineers, Inc and The Open Group. In the event of any discrepancy between
this version and the original IEEE and The Open Group Standard, the original
IEEE and The Open Group Standard is the referee document. The original
Standard can be obtained online at http://www.opengroup.org/unix/online.html
.
