Threads management services. More...

Collaboration diagram for Threads management services.:

Modules
	Thread cancellation.
	Thread cancellation.

	Threads scheduling services.
	Thread scheduling services.

	Thread creation attributes.
	Thread creation attributes.

Enumerations
enum	init_step
	Execute an initialization routine. More...

Functions
int	pthread_create (pthread_t tid, const pthread_attr_t attr, void (start)(void ), void arg)
	Create a thread. More...

int	pthread_detach (pthread_t thread)
	Detach a running thread. More...

int	pthread_equal (pthread_t t1, pthread_t t2)
	Compare thread identifiers. More...

void	pthread_exit (void *value_ptr)
	Terminate the current thread. More...

int	pthread_join (pthread_t thread, void **value_ptr)
	Wait for termination of a specified thread. More...

pthread_t	pthread_self (void)
	Get the identifier of the calling thread. More...

int	pthread_make_periodic_np (pthread_t thread, struct timespec starttp, struct timespec periodtp)
	Make a thread periodic. More...

int	pthread_wait_np (unsigned long *overruns_r)
	Wait for current thread next period. More...

int	pthread_set_mode_np (int clrmask, int setmask)
	Set the mode of the current thread. More...

int	pthread_set_name_np (pthread_t thread, const char *name)
	Set a thread name. More...

Detailed Description

Threads management services.

See also: Specification.

Enumeration Type Documentation

enum init_step

Execute an initialization routine.

This service may be used by libraries which need an initialization function to be called only once.

The function init_routine will only be called, with no argument, the first time this service is called specifying the address once.

Returns

0 on success;

an error number if:

EINVAL, the object pointed to by once is invalid (it must have been initialized with PTHREAD_ONCE_INIT);
EPERM, the caller context is invalid.

Valid contexts:

Xenomai kernel-space thread.

See also: Specification.

Function Documentation

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

Create a thread.

This service create a thread. The created thread may be used with all POSIX skin services.

The new thread run the start routine, with the arg argument.

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. See Thread creation attributes. for a definition of thread creation attributes and their default values.

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

Parameters

tid	address where the identifier of the new thread will be stored on success;
attr	thread attributes;
start	thread routine;
arg	thread routine argument.

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 POSIX skin;

See also: Specification.

Note

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

If, however, you install a signal handler for SIGWINCH after creating or shadowing the first Xenomai thread, you have to explicitly call the function xeno_sigwinch_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). xeno_sigwinch_handler prototype is:

int xeno_sigwinch_handler(int sig, siginfo_t *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 xeno_sigwinch_handler.

References pthread_getschedparam_ex(), XNFPU, xnpod_init_thread(), xnpod_set_thread_tslice(), xnpod_start_thread(), XNSHADOW, and xnsynch_init().

int pthread_detach ( pthread_t thread )

Detach a running thread.

This service detaches a joinable thread. A detached thread is a thread which control block is automatically reclaimed when it terminates. The control block of a joinable thread, on the other hand, is only reclaimed when joined with the service pthread_join().

If some threads are currently blocked in the pthread_join() service with thread as a target, they are unblocked and pthread_join() returns EINVAL.

Parameters

thread target thread.

Returns

0 on success;

an error number if:

ESRCH, thread is an invalid thread identifier;
EINVAL, thread is not joinable.

See also: Specification.

References xnpod_schedule(), and xnsynch_flush().

int pthread_equal	(	pthread_t	t1,
		pthread_t	t2
	)

Compare thread identifiers.

This service compare the thread identifiers t1 and t2. No attempt is made to check the threads for existence. In order to check if a thread exists, the pthread_kill() service should be used with the signal number 0.

Parameters

t1	thread identifier;
t2	other thread identifier.

Returns: a non zero value if the thread identifiers are equal;; 0 otherwise.

See also: Specification.

void pthread_exit ( void * value_ptr )

Terminate the current thread.

This service terminate the current thread with the return value value_ptr. If the current thread is joinable, the return value is returned to any thread joining the current thread with the pthread_join() service.

When a thread terminates, cancellation cleanup handlers are executed in the reverse order that they were pushed. Then, thread-specific data destructors are executed.

Parameters

value_ptr thread return value.

See also: Specification.

Referenced by rt_task_delete().

int pthread_join	(	pthread_t	thread,
		void **	value_ptr
	)

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

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

Valid contexts, if this service has to block its caller:

Xenomai kernel-space thread;
kernel module initilization or cleanup routine;
Xenomai user-space thread (switches to primary mode).

See also: Specification.

References xnpod_schedule(), xnsynch_sleep_on(), and xnsynch_wakeup_one_sleeper().

Referenced by rt_task_create(), and rt_task_join().

int pthread_make_periodic_np	(	pthread_t	thread,
		struct timespec *	starttp,
		struct timespec *	periodtp
	)

Make a thread periodic.

This service make the POSIX skin thread thread periodic.

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

Parameters

thread	thread identifier. This thread is immediately delayed until the first periodic release point is reached.
starttp	start time, expressed as an absolute value of the CLOCK_REALTIME clock. The affected thread will be delayed until this point is reached.
periodtp	period, expressed as a time interval.

Returns

0 on success;

an error number if:

ESRCH, thread is invalid;
ETIMEDOUT, the start time has already passed.

Rescheduling: always, until the starttp start time has been reached.

References xnpod_set_thread_periodic().

pthread_t pthread_self ( void )

Get the identifier of the calling thread.

This service returns the identifier of the calling thread.

Returns: identifier of the calling thread;; NULL if the calling thread is not a POSIX skin thread.

See also: Specification.

Referenced by pthread_setschedparam_ex(), and rt_task_shadow().

int pthread_set_mode_np	(	int	clrmask,
		int	setmask
	)

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 by the scheduler until the scheduler is unlocked;
PTHREAD_RPIOFF, when set, prevents the root Linux thread from inheriting the priority of the calling thread, when this thread is running in secondary mode;
PTHREAD_WARNSW, when set, cause the signal SIGXCPU to be sent to the current thread, whenever it involontary switches to secondary mode;
PTHREAD_PRIMARY, cause the migration of the current thread to primary mode.

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

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

Parameters

clrmask	set of bits to be cleared;
setmask	set of bits to be set.

Returns

0 on success;

an error number if:

EINVAL, some bit in clrmask or setmask is invalid.

References XNLOCK, xnpod_schedule(), xnpod_set_thread_mode(), XNRPIOFF, XNSHADOW, xnshadow_relax(), and XNTRAPSW.

int pthread_set_name_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

thread	target thread;
name	name of the thread.

Returns

0 on success;

an error number if:

ESRCH, thread is invalid.

int pthread_wait_np ( unsigned long * overruns_r )

Wait for current thread next period.

If it is periodic, this service blocks the calling thread until the next period elapses.

This service is a cancelation point for POSIX skin threads.

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

Parameters

overruns_r address where the overruns count is returned in case of overrun.

Returns

0 on success;

an error number if:

EPERM, the calling context is invalid;
EWOULDBLOCK, the calling thread is not periodic;
EINTR, this service was interrupted by a signal;
ETIMEDOUT, at least one overrun occurred.

Valid contexts:

Xenomai kernel-space thread;
Xenomai user-space thread (switches to primary mode).

References xnpod_wait_thread_period().

Modules

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation