N3924: WIP wording for “Thread-safe signals handling rev 4”

Preamble

contributing

Niall Douglas (rationale, history)

Niall Douglas, Jens Gustedt (wording)

Related documents

Revision history

Changes since N3872:

• Renamed threadsafe_signals_* to sig*. There is a sigInstall() in use in open source C++ code, but no siginstall() that I could find.
• Renamed thrd_signal_invoke to sigguarded.
• Renamed thrd_signal_raise to stdc_raise.
• Renamed thrd_signal_* to sig_*.
• Renamed thrd_raised_signal_info* to stdc_siginfo*.
• Renamed fill_synchronous_sigset et al to sigfillset_synchronous.
• Moved the siginvoke and stdc_raise functions from 7.30 which was the wrong section to 7.14 which is the correct section.
• ‘invoked’ => ‘called’.
• Add sigfence() to remove the dependency on <stdatomic.h>.

LaTeX document branch

none

Liaison

WG21, Austin Group

Relevant polls

Proposed wording

Legend

Deletions in the shown standard text are as shown here, additions, as shown here. These may render differently according to the style in which the document is shown by your browser, but should always be well distinguishable. In the provided style there are two visual distinctions:

• A high contrast color palete (Okabe and Ito) namely using colors black, orange, teal green and light yellow
• normal text, strike through, underlining and typewriter font.

Close to each other proposed changes resemble like this.

Modifications in clause 5.2.2.4 p5:

When the processing of the abstract machine is interrupted by receipt of a signal, the values of objects that are neither lock-free atomic objects nor of type volatile sig_atomic_t

not one of these categories:

1. A lock-free atomic object.
2. Of type volatile sig_atomic_t.
3. Modified since a sigfence().
4. The void * returned by tss_async_signal_safe_get().

are unspecified, as is the state of the dynamic floating-point environment. The representation of any object modified by the handler that is neither a lock-free atomic object nor of type volatile sig_atomic_t

not one of these categories:

1. A lock-free atomic object.
2. Of type volatile sig_atomic_t.
3. Accessed before a sigfence().

becomes indeterminate when the handler exits, as does the state of the dynamic floating-point environment if it is modified by the handler and not restored to its original state.

Modifications in clause 7.14.1

The header <signal.h> declares a type and two functions and defines several macros types, functions and macros, for handling various signals (conditions that may be reported during program execution).

A signal can be received by a thread within the program. When a signal is received, execution is interrupted and the currently installed signal handler for that signal is executed.

There are the following categories of signal:

1. Synchronous: these are caused by a thread doing something. Standard signals are:

   1. abnormal termination
   2. erroneous arithmetic operation
   3. detection of an invalid function image
   4. invalid access to storage.

   The implementation may define additional synchronous category signals.

2. Asynchronous nondebug: these are generated by the environment and are not usually generated by testing. Standard signals are:

   1. receipt of an interactive attention signal
   2. termination request sent to the program.

   The implementation may define additional asynchronous nondebug category signals.

3. Asynchronous debug: these are generated by the environment and are usually generated by testing.

   The implementation may define asynchronous debug category signals.

Async-signal-safe functions and macros are those safe to call during the handling of a signal. Only the functions of clause 7 listed below are required to be async-signal-safe, all other functions can be not async-signal-safe. The following functions are required to be async-signal-safe:

• the functions in <stdatomic.h> (except where explicitly stated otherwise) when the atomic arguments are lock-free,
• the atomic_is_lock_free function with any atomic argument,
• the signal function with the first argument equal to the signal number corresponding to the signal that caused the invocation of the handler. Furthermore, if such a call to the signal function results in a SIG_ERR return, the object designated by errno has an indeterminate representation, or
• any function within this standard explicitly described as async-signal-safe.

There are two ways to change the currently installed signal handler:

1. The signal function globally installs a single signal handler for the whole program execution, overwriting any previously set handler.

2. The siginstall function enables an alternative signal handling mechanism which implements thread-safe composable signal handling¹.

If siginstall has not been called in the current program execution, then the following sequence occurs on signal receipt:

1. If there is such a handler, the last most recently installed handler by signal for that signal number is called, unless that handler was set to SIG_IGN, in which case the signal is ignored. The thread in which the handler is called is unspecified.
2. Otherwise, if no call of signal for the signal number was performed, the handler has SIG_DFL semantics, which is the default action for that signal number on that implementation.

If siginstall has been called in the current program execution, then the following sequence occurs on signal receipt:

1. For synchronous category signals, the handler shall be called within the thread which caused the signal. For asynchronous category signals, the thread in which the handler is called is unspecified.

2. For each thread in a program, an ordered sequence of signal deciders is sequentially invoked to decide how to handle the signal. The ordered sequence begins with thread-locally installed signal deciders with a signal set matching the signal number in order of most recently installed last for that thread, followed by signal deciders installed globally with a signal set matching the signal number:

   • For thread-locally installed signal handlers, each decider function is called with a pointer to a populated stdc_siginfo, with its value member set to the value that was specified when that decider was installed. If a decider function returns:

     • sig_decision_resume_execution: execution of the interrupted thread is resumed.
     • sig_decision_call_recovery: the environment is restored to what it was when that thread-local decider was installed as if setjmp had been called during installation and a longjmp to restore that saved environment had been performed, and the recovery function as specified at that time shall be called to implement recovery from the signal raise for that thread.
     • sig_decision_next_decider: the next decider in the sequence is called.
       
       

   • For globally installed signal handlers, each decider function is called with a pointer to a populated stdc_siginfo, with its value set to the value as was specified when that decider was installed. The deciders are called in order of:

     • those with callfirst == true most recently installed last, and then
     • those with callfirst == false in order of most recently installed first.

     If any decider function returns:

     • sig_decision_resume_execution: execution of the interrupted thread is resumed.
     • sig_decision_call_recovery: An implementation-defined action is performed.
     • sig_decision_next_decider: The next decider in the sequence is called.

It is permitted for a signal decider to never return. Signal deciders shall meet the same requirements as for a signal handler as specified for the signal function (7.14.2.1). If every signal decider returns sig_decision_next_decider the behavior is implementation-defined.

siginstall may be called multiple times, and for each a corresponding siguninstall should be present in the program. Each call to siginstall takes a set of signals for which the threadsafe implementation is to be activated. The threadsafe implementation shall not be deactivated for that signal number until the last uninstallation for that signal number is performed.

Recommended practice

EXAMPLE 1: Use sigguarded to recover from a SIGFPE:

/* Recovery function for SIGFPE */
static union stdc_siginfo_value
sigfpe_recovery_func(const struct stdc_siginfo *rsi)
{
  /* Recover from the signal raise */
  return rsi->value;
}

/* Decider function for SIGFPE */
static enum sig_decision_t
sigfpe_decider_func(struct stdc_siginfo *rsi)
{
  /* Verify we got SIGFPE */
  if(rsi->signo != SIGFPE)
  {
    abort();
  }
  rsi->value.int_value = SIGFPE;
  /* Please recover */
  return sig_decision_call_recovery;
}

/* Guarded function that triggers SIGFPE via division by zero */
static union stdc_siginfo_value
sigfpe_func(union stdc_siginfo_value value)
{
  /* volatile is needed to prevent elision under optimization */
  volatile int divisor = 0;
  /* This should trigger SIGFPE */
  volatile int result = 42 / divisor;
  /* If we get here, this architecture doesn't trap integer divide by zero */
  stdc_raise(SIGFPE, nullptr, nullptr);
  return value;
}
...
int main() {
  union stdc_siginfo_value value = { .int_value = 0 };
  sigset_t guarded;
  sigemptyset(&guarded);
  sigaddset(&guarded, SIGFPE);
  value = sigguarded(&guarded,
                    sigfpe_func,
                    sigfpe_recovery_func,
                    sigfpe_decider_func,
                    value);
  assert(value.int_value == SIGFPE);
}

The type defined istypes defined are

stdc_siginfo_error_code_t which is an implementation-defined complete native error code type.

The stdc_siginfo_value union shall contain at least a member void *ptr_value, and if the implementation has intptr_t (7.23.2.5), then also a member intptr_t int_value, in any order.

stdc_siginfo_siginfo_t which is an implementation-defined possibly incomplete signal information type.

stdc_siginfo_context_t which is an implementation-defined possibly incomplete context type.

The stdc_siginfo structure shall contain at least the following members, in any order. The semantics of the members are expressed in the comments.

// The signal raised
int signo;

// The system specific error code for this signal
stdc_siginfo_error_code_t error_code;

// Memory location which caused fault, if appropriate
void *addr;

// A user-defined value
union stdc_siginfo_value value;

// The system specific information. Can be null if the
// value was not supplied, or was supplied as null.
stdc_siginfo_siginfo_t *raw_info;

// The system specific context. Can be null if the
// value was not supplied, or was supplied as null.
stdc_siginfo_context_t *raw_context;

The sig_func_t type is a function type with a single argument stdc_siginfo_value and which returns stdc_siginfo_value.

The sig_recover_t type is a function type with a single argument const stdc_siginfo * and which returns stdc_siginfo_value.

The sig_decision_t enumeration shall contain at least the following members, in any order. The semantics of the members are expressed in the comments:

// We have decided to do nothing
sig_decision_next_decider

// We have fixed the cause of the signal, please resume execution
sig_decision_resume_execution

// thread-local signal deciders only: reset the stack and local
// state to entry to `sigguarded()`, and call the recovery
// function.
sig_decision_call_recovery

The sig_decide_t type is a function type with a single argument stdc_siginfo * and which returns sig_decision_t, this being the type of the function invocable by sigguarded() and globally installed signal deciders to decide how to handle a raised exception.

sig_atomic_t

which is the (possibly volatile-qualified) integer type of an object that can be accessed as an atomic entity, even in the presence of asynchronous interrupts.

sigset_t

which is an implementation-defined complete type able to represent a set of signals on this platform, and for which this code is valid:

sigset_t a;
sigemptyset(&a);
sigset_t b = a;

The macros defined are

SIG_DFL
SIG_ERR
SIG_IGN

which expand to constant expressions with distinct values that have type compatible with the second argument to, and the return value of, the signal function, and whose values compare unequal to the address of any declarable function; and the following, which expand to positive integer constant expressions with type int and distinct values that are the signal numbers, each corresponding to the specified condition:

SIGABRT abnormal termination, such as is initiated by the abort function, which is of synchronous signal category

SIGFPE an erroneous arithmetic operation, such as zero divide or an operation resulting in overflow, which is of synchronous signal category

SIGILL detection of an invalid function image, such as an invalid instruction, which is of synchronous signal category

SIGINT receipt of an interactive attention signal, which is of asynchronous nondebug signal category

SIGSEGV an invalid access to storage, which is of synchronous signal category

SIGTERM a termination request sent to the program, which is of asynchronous nondebug signal category

Insert new clause after 7.14.1 as 7.14.2 moving remainder downwards

7.14.2.1 Signal set initialization

The sigemptyset function

The sigfillset function

The sigfillset_synchronous function

The sigfillset_asynchronous_nondebug function

The sigfillset_asynchronous_debug function

7.14.2.2 Signal set manipulation

The sigaddset function

The sigdelset function

In 7.14.1.5: The sigismember function

Modifications in clause 7.14.2.1

…

Description

…

5 If the signal occurs other than as the result of calling the abort or raise function, the behavior is undefined if the signal handler refers to any object with static or thread storage duration that is not a lock-free atomic object and that is not declared with the constexpr storage-class specifier other than by assigning a value to an object declared as volatile sig_atomic_t, or the signal handler calls any function in the standard library other thanor the signal handler calls any function in the standard library not described as async-signal-safe other than:

• the abort function,
• the _Exit function,
• the quick_exit function,
• the functions in <stdatomic.h> (except where explicitly stated otherwise) when the atomic arguments are lock-free,
• the atomic_is_lock_free function with any atomic argument, or
• the signal function with the first argument equal to the signal number corresponding to the signal that caused the invocation of the handler. Furthermore, if such a call to the signal function results in a SIG_ERR return, the object designated by errno has an indeterminate representation.

6 …

7 Use of this function in a multi-threaded program results in undefined behavior. The implementation shall behave as if no library function calls the signal function.

Modifications in clause 7.14.2

In 7.14.2.5: The siginstall function

In 7.14.2.6: The siguninstall function

In 7.14.2.7: The signal_decider_create function

In 7.14.2.8: The signal_decider_destroy function

In 7.14.3.2: The stdc_raise function

Note to implementers: For your information the reference implementation library does not raise a real signal on POSIX, but simulates raising one instead because there is no other way to pass in a custom siginfo_t and ucontext_t. If it reaches the end of all lists, it calls the signal handler which was installed before threadsafe signals was installed. On Microsoft Windows, it does actually raise a real Win32 exception as for those you can specify a custom EXCEPTION_RECORD and CONTEXT. As both thread local and globally installed signal handlers are directly installed with Windows, it will perform its default action when it runs out of handlers. Suggestion to implementers: I think it would be preferable if a real signal was initially raised where possible, then debuggers get notified. You may be able to persuade your standard C library to implement this e.g. on Linux one can use syscall rt_tgsigqueueinfo.

Add 7.14.3 Recover from signal

Add 7.14.4.1: The sigguarded function

Modifications in clause 7.25.5.1

In 7.25.5.1: The abort function

The abort function causes abnormal program termination to occur, unless the signal SIGABRT is being caught and the signal handler does not return. Whether open streams with unwritten buffered data are flushed, open streams are closed, or temporary files are removed is implementation-defined. An implementation-defined form of the status unsuccessful termination is returned to the host environment by means of the function call raise(SIGABRT).

Calling this function is async-signal-safe.

Modifications in clause 7.25.5.5

In 7.25.5.5: The _Exit function

The _Exit function causes normal program termination to occur and control to be returned to the host environment. No functions registered by the atexit function, the at_quick_exit function, or signal handlers registered by the signal function are called. The status returned to the host environment is determined in the same way as for the exit function. Whether open streams with unwritten buffered data are flushed, open streams are closed, or temporary files are removed is implementation-defined.

Calling this function is async-signal-safe.

Modifications in clause 7.25.5.7

In 7.25.5.7: The quick_exit function

The quick_exit function causes normal program termination to occur. No functions registered by the atexit function or signal handlers registered by the signal function are called. If a program calls the quick_exit function more than once, or calls the exit function in addition to the quick_exit function, the behavior is undefined. If a signal is raised while the quick_exit function is executing, the behavior is undefined.

Calling this function is async-signal-safe.

Modifications in clause 7.30 Threads <threads.h>

In 7.30.1 Introduction

In 7.30.6.5: The tss_async_signal_safe_create function

In 7.30.6.6: The tss_async_signal_safe_destroy function

In 7.30.6.7: The tss_async_signal_safe_thread_init function

In 7.30.6.8: The tss_async_signal_safe_thread_get function