Xenomai  3.0-rc7
Thread management

Cobalt/POSIX thread management services. More...

Collaboration diagram for Thread management:

Functions

int pthread_create (pthread_t *ptid_r, const pthread_attr_t *attr, void *(*start)(void *), void *arg)
 Create a new thread. More...
 
int pthread_setmode_np (int clrmask, int setmask, int *mode_r)
 Set the mode of the current thread. More...
 
int pthread_setname_np (pthread_t thread, const char *name)
 Set a thread name. More...
 
int pthread_kill (pthread_t thread, int sig)
 Send a signal to a thread. More...
 
int pthread_join (pthread_t thread, void **retval)
 Wait for termination of a specified thread. More...
 

Detailed Description

Cobalt/POSIX thread management services.

See also
Specification.

Function Documentation

int pthread_create ( pthread_t *  ptid_r,
const pthread_attr_t *  attr,
void *(*)(void *)  start,
void *  arg 
)

Create a new thread.

This service creates a thread managed by the Xenomai nucleus in dual kernel configuration.

The new thread signal mask is inherited from the current thread, if it was also created with pthread_create(), otherwise the new thread signal mask is empty.

Other attributes of the new thread depend on the attr argument. If attr is NULL, default values for these attributes are used.

Returning from the start routine has the same effect as calling pthread_exit() with the return value.

Parameters
ptid_raddress where the identifier of the new thread will be stored on success;
attrthread attributes;
startthread start routine;
argopaque user-supplied argument passed to start;
Returns
0 on success;
an error number if:
  • EINVAL, attr is invalid;
  • EAGAIN, insufficient memory exists in the system heap to create a new thread, increase CONFIG_XENO_OPT_SYS_HEAPSZ;
  • EINVAL, thread attribute inheritsched is set to PTHREAD_INHERIT_SCHED and the calling thread does not belong to the Cobalt interface;
See also
Specification.
Note

When creating or shadowing a Xenomai thread for the first time in user-space, Xenomai installs a handler for the SIGSHADOW signal. If you had installed a handler before that, it will be automatically called by Xenomai for SIGSHADOW signals that it has not sent.

If, however, you install a signal handler for SIGSHADOW after creating or shadowing the first Xenomai thread, you have to explicitly call the function cobalt_sigshadow_handler at the beginning of your signal handler, using its return to know if the signal was in fact an internal signal of Xenomai (in which case it returns 1), or if you should handle the signal (in which case it returns 0). cobalt_sigshadow_handler prototype is:

int cobalt_sigshadow_handler(int sig, struct siginfo *si, void *ctxt);

Which means that you should register your handler with sigaction, using the SA_SIGINFO flag, and pass all the arguments you received to cobalt_sigshadow_handler.

int pthread_join ( pthread_t  thread,
void **  retval 
)

Wait for termination of a specified thread.

If the thread thread is running and joinable, this service blocks the calling thread until the thread thread terminates or detaches. In this case, the calling context must be a blockable context (i.e. a Xenomai thread without the scheduler locked) or the root thread (i.e. a module initilization or cleanup routine). When thread terminates, the calling thread is unblocked and its return value is stored at* the address value_ptr.

If, on the other hand, the thread thread has already finished execution, its return value is stored at the address value_ptr and this service returns immediately. In this case, this service may be called from any context.

This service is a cancelation point for POSIX skin 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
threadidentifier of the thread to wait for;
retvaladdress where the target thread return value will be stored on success.
Returns
0 on success;
an error number if:
  • ESRCH, thread is invalid;
  • EDEADLK, attempting to join the calling thread;
  • EINVAL, thread is detached;
  • EPERM, the caller context is invalid.
See also
Specification.

Referenced by rt_task_join().

int pthread_kill ( pthread_t  thread,
int  sig 
)

Send a signal to a thread.

This service send the signal sig to the Xenomai POSIX skin thread thread (created with pthread_create()). If sig is zero, this service check for existence of the thread thread, but no signal is sent.

Parameters
threadthread identifier;
sigsignal number.
Returns
0 on success;
an error number if:
  • EINVAL, sig is an invalid signal number;
  • EAGAIN, the maximum number of pending signals has been exceeded;
  • ESRCH, thread is an invalid thread identifier.
See also
Specification.
int pthread_setmode_np ( int  clrmask,
int  setmask,
int *  mode_r 
)

Set the mode of the current thread.

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 user-space task 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 POSIX interface.

Parameters
clrmaskset of bits to be cleared.
setmaskset of bits to be set.
mode_rIf 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.

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

int pthread_setname_np ( pthread_t  thread,
const char *  name 
)

Set a thread name.

This service set to name, the name of thread. This name is used for displaying information in /proc/xenomai/sched.

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

Parameters
threadtarget thread;
namename of the thread.
Returns
0 on success;
an error number if:
  • ESRCH, thread is invalid.