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_r	address where the identifier of the new thread will be stored on success;
attr	thread attributes;
start	thread start routine;
arg	opaque 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

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

thread	identifier of the thread to wait for;
retval	address 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

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

thread	thread identifier;
sig	signal 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

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

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.

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

thread	target thread;
name	name of the thread.

Returns

0 on success;

an error number if:

• ESRCH, thread is invalid.

Tags

xthread-only