`sigevent`

Structure that describes an event

Synopsis:

The sigevent structure, which is defined in <sys/siginfo.h>, is complicated; see below.

Description:

This structure describes an event. The int sigev_notify member indicates how the notification is to occur, as well as which of the other members are used:

sigev_notify	sigev_signo	sigev_coid	sigev_priority	sigev_code	sigev_value
SIGEV_INTR
SIGEV_NONE
SIGEV_PULSE		Connection	Priority	Code	Value
SIGEV_SIGNAL	Signal
SIGEV_SIGNAL_CODE	Signal			Code	Value
SIGEV_SIGNAL_THREAD	Signal			Code	Value
SIGEV_THREAD (special — see below)					Value
SIGEV_UNBLOCK

The <sys/siginfo.h> file also defines some macros to make initializing the sigevent structure easier. All the macros take a pointer to a sigevent structure as their first argument, event, and set the sigev_notify member to the appropriate value.

These macros are QNX Neutrino extensions.
The library might use hidden bits in the sigev_notify member of the sigevent structure. If you ever test the value of this member after creating a sigevent, don't compare it directly to a value; use the SIGEV_GET_TYPE() macro. For example, instead of:
```
if( my_event.sigev_notify == SIGEV_PULSE) 
  
```
use:
```
if( SIGEV_GET_TYPE(&my_event) == SIGEV_PULSE) 
  
```

SIGEV_INTR

Send an interrupt notification to a specific thread. No other fields in the structure are used.

The initialization macro is:

SIGEV_INTR_INIT( &event )

SIGEV_NONE

Don't send any notification. No other fields in the structure are used.

The initialization macro is:

SIGEV_NONE_INIT( &event )

SIGEV_PULSE

Send a pulse. The following fields are used:

int sigev_coid: The connection ID. This should be attached to the channel with which the pulse will be received.
short sigev_priority: The priority of the pulse.
If you want the thread that receives the pulse to run at the initial priority of the process, set sigev_priority to SIGEV_PULSE_PRIO_INHERIT.
short sigev_code: A code to be interpreted by the pulse handler. Although sigev_code can be any 8-bit signed value, you should avoid sigev_code values less than zero in order to avoid conflict with kernel or pulse codes generated by a QNX manager. These codes all start with _PULSE_CODE_ and are defined in <sys/neutrino.h>; for more information, see the documentation for the _pulse structure. A safe range of pulse values is _PULSE_CODE_MINAVAIL to _PULSE_CODE_MAXAVAIL.
void *sigev_value.sival_int: A 32-bit value to be interpreted by the pulse handler.

The initialization macro is:

SIGEV_PULSE_INIT( &event, coid, priority, code, value )

SIGEV_SIGNAL

Send a signal to a process. The following fields are used:

int sigev_signo: The signal to raise. This must be in the range from 1 through NSIG − 1.

The initialization macro is:

SIGEV_SIGNAL_INIT( &event, signal )

If you need to set the sigev_value for a SIGEV_SIGNAL event (for example if SA_SIGINFO is set), you can use this macro:

SIGEV_SIGNAL_VALUE_INIT( &event, signal, value )

SIGEV_SIGNAL_CODE

This is similar to SIGEV_SIGNAL, except that SIGEV_SIGNAL_CODE also includes a value and a code. The following fields are used:

int sigev_signo: The signal to raise. This must be in the range from 1 through NSIG − 1.
short sigev_code: A code to be interpreted by the signal handler. This must be in the range from SI_MINAVAIL through SI_MAXAVAIL.
void *sigev_value.sival_int: A 32-bit value to be interpreted by the signal handler.

The initialization macro is:

SIGEV_SIGNAL_CODE_INIT( &event, signal, value, code )

SIGEV_SIGNAL_THREAD

Send a signal to a specific thread, depending on the situation:

If used with MsgSend*(), MsgReceive*(), and MsgDeliverEvent(), the thread is the one identified by the rcvid that MsgReceive*() returns.
For timers, it's the thread that called timer_settime().
For InterruptAttach() and InterruptAttachEvent(), it's the thread attaching to the interrupt.
For asyncmsg_channel_create(), it's a random thread in the process.
For SyncMutexEvent(), it's the thread that called the function.

In the case of timers, SyncMutexEvent(), and interrupts, if the thread dies before the event gets delivered, the kernel sends the signal to a random thread in the same process.

The following fields are used:

int sigev_signo: The signal to raise. This must be in the range from 1 through NSIG − 1.
short sigev_code: A code to be interpreted by the signal handler. This must be in the range from SI_MINAVAIL through SI_MAXAVAIL.
void *sigev_value.sival_int: A 32-bit value to be interpreted by the signal handler.

The initialization macro is:

SIGEV_SIGNAL_THREAD_INIT( &event, signal, value, code )

SIGEV_THREAD

Create a new thread.

We don't recommend using this type of event. Pulses are more efficient.

The following fields are used:

void (*sigev_notify_function) (union sigval): A pointer to the function to be notified.
pthread_attr *sigev_notify_attributes: A pointer to thread attributes. This must be NULL, or point to a structure initialized by pthread_attr_init() at the time of delivery.
void *sigev_value.sival_ptr: A value that's to be passed to the notification function.

The initialization macro is:

SIGEV_THREAD_INIT( &event, fn, value, attr )

The sigval union is defined as follows:

union sigval {
    int        sival_int;
    void     * sival_ptr;
};

SIGEV_UNBLOCK

Force a thread to become unblocked. No other fields in the structure are used.

The initialization macro is:

SIGEV_UNBLOCK_INIT( &event )

Critical threads

If you're using adaptive partitioning, you can use a sigevent to make a thread run as critical or not.

This feature was added in the QNX Neutrino Core OS 6.3.2. For more information, see the Adaptive Partitioning User's Guide.

After setting up the sigevent structure as appropriate, use these macros to set or clear the hidden bit that makes a thread run as critical or not:

SIGEV_MAKE_CRITICAL( &event ): Make the targeted thread run as critical.
SIGEV_CLEAR_CRITICAL( &event ): Make the targeted thread not run as critical.

The receiving thread doesn't have to do anything to make itself critical or noncritical; the adaptive partitioning scheduler does this automatically.

These macros use hidden bits in the sigev_notify member of the sigevent structure. Don't compare this member directly to a value; use the SIGEV_GET_TYPE() macro instead, as described above.

Classification:

QNX Neutrino