When creating a Cobalt thread for the first time, libcobalt installs an internal handler for the SIGSHADOW signal. If you had previously installed a handler for such signal before that point, such handler will be exclusively called for any SIGSHADOW occurrence Xenomai did not send.

If, however, an application-defined handler for SIGSHADOW is installed afterwards, overriding the libcobalt handler, the new handler is required to call cobalt_sigshadow_handler() on entry. This routine returns a non-zero value for every occurrence of SIGSHADOW issued by the Cobalt core. If zero instead, the application-defined handler should process the signal.

int cobalt_sigshadow_handler(int sig, siginfo_t *si, void *ctxt);

You should register your handler with sigaction(2), setting the SA_SIGINFO flag.

If thread is running and joinable, this service blocks the caller until thread terminates or detaches. When thread terminates, the caller is unblocked and its return value is stored at the address value_ptr.

On the other hand, if thread has already finished execution, its return value collected earlier is stored at the address value_ptr and this service returns immediately.

This service is a cancelation point for Cobalt threads: if the calling thread is canceled while blocked in a call to this service, the cancelation request is honored and thread remains joinable.

Multiple simultaneous calls to pthread_join() specifying the same running target thread block all the callers until the target thread terminates.

Parameters

thread

identifier of the thread to wait for;

retval

address where the target thread return value will be stored on success.

This service sets the mode of the calling thread, which affects its behavior under particular circumstances. clrmask and setmask are two masks of mode bits which are respectively cleared and set by pthread_setmode_np():

PTHREAD_LOCK_SCHED, when set, locks the scheduler, which prevents the current thread from being switched out until the scheduler is unlocked. Unless PTHREAD_DISABLE_LOCKBREAK is also set, the thread may still block, dropping the lock temporarily, in which case, the lock will be reacquired automatically when the thread resumes execution. When PTHREAD_LOCK_SCHED is cleared, the current thread drops the scheduler lock, and the rescheduling procedure is initiated.

When set, PTHREAD_WARNSW enables debugging notifications for the current thread. A SIGDEBUG (Linux-originated) signal is sent when the following atypical or abnormal behavior is detected:

the current thread switches to secondary mode. Such notification comes in handy for detecting spurious relaxes, with one of the following reason codes:

SIGDEBUG_MIGRATE_SYSCALL, if the thread issued a regular Linux system call.

SIGDEBUG_MIGRATE_SIGNAL, if the thread had to leave real-time mode for handling a Linux signal.

SIGDEBUG_MIGRATE_FAULT, if the thread had to leave real-time mode for handling a processor fault/exception.

the current thread is sleeping on a Cobalt mutex currently owned by a thread running in secondary mode, which reveals a priority inversion. In such an event, the reason code passed to the signal handler will be SIGDEBUG_MIGRATE_PRIOINV.

the current thread is about to sleep while holding a Cobalt mutex, and CONFIG_XENO_OPT_DEBUG_MUTEX_SLEEP is enabled in the kernel configuration. In such an event, the reason code passed to the signal handler will be SIGDEBUG_MUTEX_SLEEP. Blocking for acquiring a mutex does not trigger such signal though.

the current thread has enabled PTHREAD_DISABLE_LOCKBREAK and PTHREAD_LOCK_SCHED, then attempts to block on a Cobalt service, which would cause a lock break. In such an event, the reason code passed to the signal handler will be SIGDEBUG_LOCK_BREAK.

PTHREAD_DISABLE_LOCKBREAK disallows breaking the scheduler lock. Normally, the scheduler lock is dropped implicitly when the current owner blocks, then reacquired automatically when the owner resumes execution. If PTHREAD_DISABLE_LOCKBREAK is set, the scheduler lock owner would return with EINTR immediately from any blocking call instead (see PTHREAD_WARNSW notifications).

PTHREAD_CONFORMING can be passed in setmask to switch the current Cobalt thread to its preferred runtime mode. The only meaningful use of this switch is to force a real-time thread back to primary mode eagerly. Other usages have no effect.

This service is a non-portable extension of the Cobalt interface.

Parameters

clrmask

set of bits to be cleared.

setmask

set of bits to be set.

mode_r

If non-NULL, mode_r must be a pointer to a memory location which will be written upon success with the previous set of active mode bits. If NULL, the previous set of active mode bits will not be returned.

Returns

0 on success, otherwise:

EINVAL, some bit in clrmask or setmask is invalid.

Note

Setting clrmask and setmask to zero leads to a nop, only returning the previous mode if mode_r is a valid address.

Attention

Issuing PTHREAD_CONFORMING is most likely useless or even introduces pure overhead in regular applications, since the Cobalt core performs the necessary mode switches, only when required.