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 BlackBerry 10 OS 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 BlackBerry 10 OS 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:

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 )

Classification:

QNX Neutrino

Last modified: 2013-12-23

comments powered by Disqus