Xenomai  3.0-rc3
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. clrmask and setmask are two bit masks which are respectively cleared and set in the calling thread status. They are a bitwise OR of the following values:

  • PTHREAD_LOCK_SCHED, when set, locks the scheduler, which prevents the current thread from being switched out until the scheduler is unlocked;
  • PTHREAD_WARNSW, when set, causes the signal SIGDEBUG to be sent to the current thread, whenever it involontary switches to secondary mode;
  • 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 shadow back to primary mode. Any other use leads to a nop.
  • PTHREAD_DISABLE_LOCKBREAK disallows breaking the scheduler lock. In the default case, a thread which holds the scheduler lock is allowed to drop it temporarily for sleeping. If this mode bit is set, such thread would return with EINTR immediately from any blocking call.

PTHREAD_LOCK_SCHED and PTHREAD_DISABLE_LOCKBREAK are valid for any Xenomai thread, other bits are valid for Xenomai user-space threads only.

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;
an error number if:
  • 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.
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.