Xenomai  3.0.8
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

◆ pthread_create()

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 Cobalt core in a dual kernel configuration.

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 available from 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 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.

Tags api-tags "thread-unrestricted, switch-secondary"

◆ pthread_join()

int pthread_join ( pthread_t  thread,
void **  retval 
)

Wait for termination of a specified thread.

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
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.
Tags api-tags "xthread-only, switch-secondary, switch-primary"

◆ pthread_kill()

int pthread_kill ( pthread_t  thread,
int  sig 
)

Send a signal to a thread.

This service send the signal sig to the Cobalt 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.
Tags api-tags "thread-unrestricted, switch-primary"

◆ pthread_setmode_np()

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 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
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.
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.
Tags api-tags "xthread-only, switch-primary"

◆ pthread_setname_np()

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 Cobalt interface.

Parameters
threadtarget thread;
namename of the thread.
Returns
0 on success;
an error number if:
  • ESRCH, thread is invalid.
Tags api-tags "xthread-only"