Services dealing with preemptive multi-tasking. More...

Collaboration diagram for Task management services:

Data Structures
struct	RT_TASK_INFO
	Task status descriptor. More...

Macros
#define	T_LOPRIO 0
	Task priorities. More...

#define	T_LOCK __THREAD_M_LOCK
	Task mode bits. More...

#define	T_WARNSW __THREAD_M_WARNSW
	Cobalt only, nop over Mercury. More...

Functions
int	rt_task_delete (RT_TASK *task)
	Delete a real-time task. More...

int	rt_task_set_affinity (RT_TASK task, const cpu_set_t cpus)
	Set CPU affinity of real-time task. More...

int	rt_task_start (RT_TASK task, void(entry)(void arg), void arg)
	Start a real-time task. More...

int	rt_task_shadow (RT_TASK task, const char name, int prio, int mode)
	Turn caller into a real-time task. More...

int	rt_task_join (RT_TASK *task)
	Wait on the termination of a real-time task. More...

int	rt_task_wait_period (unsigned long *overruns_r)
	Wait for the next periodic release point. More...

int	rt_task_sleep (RTIME delay)
	Delay the current real-time task (with relative delay). More...

int	rt_task_sleep_until (RTIME date)
	Delay the current real-time task (with absolute wakeup date). More...

int	rt_task_same (RT_TASK task1, RT_TASK task2)
	Compare real-time task descriptors. More...

int	rt_task_suspend (RT_TASK *task)
	Suspend a real-time task. More...

int	rt_task_resume (RT_TASK *task)
	Resume a real-time task. More...

RT_TASK *	rt_task_self (void)
	Retrieve the current task descriptor. More...

int	rt_task_set_priority (RT_TASK *task, int prio)
	Change the base priority of a real-time task. More...

int	rt_task_set_mode (int clrmask, int setmask, int *mode_r)
	Change the current task mode. More...

int	rt_task_yield (void)
	Manual round-robin. More...

int	rt_task_unblock (RT_TASK *task)
	Unblock a real-time task. More...

int	rt_task_slice (RT_TASK *task, RTIME quantum)
	Set a task's round-robin quantum. More...

int	rt_task_inquire (RT_TASK task, RT_TASK_INFO info)
	Retrieve information about a real-time task. More...

ssize_t	rt_task_send_timed (RT_TASK task, RT_TASK_MCB mcb_s, RT_TASK_MCB mcb_r, const struct timespec abs_timeout)
	Send a message to a real-time task. More...

static ssize_t	rt_task_send_until (RT_TASK task, RT_TASK_MCB mcb_s, RT_TASK_MCB *mcb_r, RTIME timeout)
	Send a message to a real-time task (with absolute scalar timeout). More...

static ssize_t	rt_task_send (RT_TASK task, RT_TASK_MCB mcb_s, RT_TASK_MCB *mcb_r, RTIME timeout)
	Send a message to a real-time task (with relative scalar timeout). More...

int	rt_task_receive_timed (RT_TASK_MCB mcb_r, const struct timespec abs_timeout)
	Receive a message from a real-time task. More...

static int	rt_task_receive_until (RT_TASK_MCB *mcb_r, RTIME timeout)
	Receive a message from a real-time task (with absolute scalar timeout). More...

static int	rt_task_receive (RT_TASK_MCB *mcb_r, RTIME timeout)
	Receive a message from a real-time task (with relative scalar timeout). More...

int	rt_task_reply (int flowid, RT_TASK_MCB *mcb_s)
	Reply to a remote task message. More...

int	rt_task_bind (RT_TASK task, const char name, RTIME timeout)
	Bind to a task. More...

int	rt_task_unbind (RT_TASK *task)
	Unbind from a task. More...

int	rt_task_create (RT_TASK task, const char name, int stksize, int prio, int mode)
	Create a task with Alchemy personality. More...

int	rt_task_set_periodic (RT_TASK *task, RTIME idate, RTIME period)
	Make a real-time task periodic. More...

int	rt_task_spawn (RT_TASK task, const char name, int stksize, int prio, int mode, void(entry)(void arg), void *arg)
	Create and start a real-time task. More...

Detailed Description

Services dealing with preemptive multi-tasking.

Each Alchemy task is an independent portion of the overall application code embodied in a C procedure, which executes on its own stack context.

Macro Definition Documentation

◆ T_LOCK

#define T_LOCK __THREAD_M_LOCK

Task mode bits.

Referenced by rt_task_set_mode().

◆ T_LOPRIO

#define T_LOPRIO 0

Task priorities.

◆ T_WARNSW

#define T_WARNSW __THREAD_M_WARNSW

Cobalt only, nop over Mercury.

Referenced by rt_task_set_mode().

Function Documentation

◆ rt_task_bind()

int rt_task_bind	(	RT_TASK *	task,
		const char *	name,
		RTIME	timeout
	)

Bind to a task.

This routine creates a new descriptor to refer to an existing Alchemy task identified by its symbolic name. If the object does not exist on entry, the caller may block until a task of the given name is created.

Parameters

task	The address of a task descriptor filled in by the operation. Contents of this memory is undefined upon failure.
name	A valid NULL-terminated name which identifies the task to bind to. This string should match the object name argument passed to rt_task_create(), or rt_task_shadow().
timeout	The number of clock ticks to wait for the registration to occur (see note). Passing TM_INFINITE causes the caller to block indefinitely until the object is registered. Passing TM_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry.

Returns: Zero is returned upon success. Otherwise:

-EINTR is returned if rt_task_unblock() was called for the current task before the retrieval has completed.
-EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the searched object is not registered on entry.
-ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time.
-EPERM is returned if this service should block, but was not called from a Xenomai thread.

Tags: xthread-nowait, switch-primary

Note: The timeout value is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

◆ rt_task_create()

int rt_task_create	(	RT_TASK *	task,
		const char *	name,
		int	stksize,
		int	prio,
		int	mode
	)

Create a task with Alchemy personality.

This service creates a task with access to the full set of Alchemy services. If prio is non-zero, the new task belongs to Xenomai's real-time FIFO scheduling class, aka SCHED_FIFO. If prio is zero, the task belongs to the regular SCHED_OTHER class.

Creating tasks with zero priority is useful for running non real-time processes which may invoke blocking real-time services, such as pending on a semaphore, reading from a message queue or a buffer, and so on.

Once created, the task is left dormant until it is actually started by rt_task_start().

Parameters

task	The address of a task descriptor which can be later used to identify uniquely the created object, upon success of this call.
name	An ASCII string standing for the symbolic name of the task. When non-NULL and non-empty, a copy of this string is used for indexing the created task into the object registry.
stksize	The size of the stack (in bytes) for the new task. If zero is passed, a system-dependent default size will be substituted.
prio	The base priority of the new task. This value must be in the [0 .. 99] range, where 0 is the lowest effective priority.
mode	The task creation mode. The following flags can be OR'ed into this bitmask:

T_JOINABLE allows another task to wait on the termination of the new task. rt_task_join() shall be called for this task to clean up any resources after its termination.
T_LOCK causes the new task to lock the scheduler prior to entering the user routine specified by rt_task_start(). A call to rt_task_set_mode() from the new task is required to drop this lock.
When running over the Cobalt core, T_WARNSW causes the SIGDEBUG signal to be sent to the current task whenever it switches to the secondary mode. This feature is useful to detect unwanted migrations to the Linux domain. This flag has no effect over the Mercury core.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if either prio, mode or stksize are invalid.
-ENOMEM is returned if the system fails to get memory from the main heap in order to create the task.
-EEXIST is returned if the name is conflicting with an already registered task.

Tags: mode-unrestricted, switch-secondary

Side effects

When running over the Cobalt core:
- calling rt_task_create() causes SCHED_FIFO tasks to switch to secondary mode.
- members of Xenomai's SCHED_FIFO class running in the primary domain have utmost priority over all Linux activities in the system, including Linux interrupt handlers.
When running over the Mercury core, the new task belongs to the regular POSIX SCHED_FIFO class.

Note: Tasks can be referred to from multiple processes which all belong to the same Xenomai session.

Examples:: cross-link.c.

◆ rt_task_delete()

int rt_task_delete ( RT_TASK * task )

Delete a real-time task.

This call terminates a task previously created by rt_task_create().

Tasks created with the T_JOINABLE flag shall be joined by a subsequent call to rt_task_join() once successfully deleted, to reclaim all resources.

Parameters

task	The task descriptor.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if task is not a valid task descriptor.
-EPERM is returned if task is NULL and this service was called from an invalid context. In addition, this error is always raised when this service is called from asynchronous context, such as a timer/alarm handler.

Tags: mode-unrestricted, switch-secondary

Note: The caller must be an Alchemy task if task is NULL.

Examples:: cross-link.c.

◆ rt_task_inquire()

int rt_task_inquire	(	RT_TASK *	task,
		RT_TASK_INFO *	info
	)

Retrieve information about a real-time task.

Return various information about an Alchemy task. This service may also be used to probe for task existence.

Parameters

task	The task descriptor. If task is NULL, the information about the current task is returned.
info	The address of a structure the task information will be written to. Passing NULL is valid, in which case the system is only probed for existence of the specified task.

Returns: Zero is returned if the task exists. In addition, if info is non-NULL, it is filled in with task information.

-EINVAL is returned if task is not a valid task descriptor, or if prio is invalid.
-EPERM is returned if task is NULL and this service was called from an invalid context.

Tags: mode-unrestricted, switch-primary

Note: The caller must be an Alchemy task if task is NULL.

◆ rt_task_join()

int rt_task_join ( RT_TASK * task )

Wait on the termination of a real-time task.

This service blocks the caller in non-real-time context until task has terminated. All resources are released after successful completion of this service.

The specified task must have been created by the same process that wants to join it, and the T_JOINABLE mode flag must have been set on creation to rt_task_create().

Tasks created with the T_JOINABLE flag shall be joined by a subsequent call to rt_task_join() once successfully deleted, to reclaim all resources.

Parameters

task	The task descriptor.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if task is not a valid task descriptor.
-EINVAL is returned if the task was not created with T_JOINABLE set or some other task is already waiting on the termination.
-EDEADLK is returned if task refers to the caller.
-ESRCH is returned if task no longer exists or refers to task created by a different process.

Tags: mode-unrestricted, switch-primary

Note: After successful completion of this service, it is neither required nor valid to additionally invoke rt_task_delete() on the same task.

◆ rt_task_receive()

ssize_t rt_task_receive	(	RT_TASK_MCB *	mcb_r,
		RTIME	timeout
	)

inlinestatic

Receive a message from a real-time task (with relative scalar timeout).

This routine is a variant of rt_task_receive_timed() accepting a relative timeout specification expressed as a scalar value.

Parameters

mcb_r	The address of a message control block referring to the receive message area.
timeout	A delay expressed in clock ticks.

Tags: xthread-only, switch-primary

References rt_task_receive_timed().

◆ rt_task_receive_timed()

int rt_task_receive_timed	(	RT_TASK_MCB *	mcb_r,
		const struct timespec *	abs_timeout
	)

Receive a message from a real-time task.

This service is part of the synchronous message passing support available to Alchemy tasks. The caller receives a variable-sized message from another task. The sender is blocked until the caller invokes rt_task_reply() to finish the transaction.

A basic message control block is used to store the location and size of the data area to receive from the client, in addition to a user-defined operation code.

Parameters

mcb_r The address of a message control block referring to the receive message area. The fields from this control block should be set as follows:

mcb_r->data should contain the address of a buffer large enough to collect the data sent by the remote task;
mcb_r->size should contain the size in bytes of the buffer space pointed at by mcb_r->data. If mcb_r->size is lower than the actual size of the received message, no data copy takes place and -ENOBUFS is returned to the caller. See note.

Upon return, mcb_r->opcode will contain the operation code sent from the remote task using rt_task_send().

Parameters

abs_timeout The number of clock ticks to wait for receiving a message (see note). Passing NULL causes the caller to block indefinitely until a remote task eventually sends a message. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return immediately without waiting if no remote task is currently waiting for sending a message.

Returns: A strictly positive value is returned upon success, representing a flow identifier for the opening transaction; this token should be passed to rt_task_reply(), in order to send back a reply to and unblock the remote task appropriately. Otherwise:

-EPERM is returned if this service was called from an invalid context.
-EINTR is returned if rt_task_unblock() was called for the current task before a message was received.
-ENOBUFS is returned if mcb_r does not point at a message area large enough to collect the remote task's message.
-EWOULDBLOCK is returned if abs_timeout is { .tv_sec = 0, .tv_nsec = 0 } and no remote task is currently waiting for sending a message to the caller.
-ETIMEDOUT is returned if no message was received within the timeout.

Tags: xthread-only, switch-primary

Note: abs_timeout is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

Referenced by rt_task_receive(), and rt_task_receive_until().

◆ rt_task_receive_until()

ssize_t rt_task_receive_until	(	RT_TASK_MCB *	mcb_r,
		RTIME	abs_timeout
	)

inlinestatic

Receive a message from a real-time task (with absolute scalar timeout).

This routine is a variant of rt_task_receive_timed() accepting an absolute timeout specification expressed as a scalar value.

Parameters

mcb_r	The address of a message control block referring to the receive message area.
abs_timeout	An absolute date expressed in clock ticks.

Tags: xthread-only, switch-primary

References rt_task_receive_timed().

◆ rt_task_reply()

int rt_task_reply	(	int	flowid,
		RT_TASK_MCB *	mcb_s
	)

Reply to a remote task message.

This service is part of the synchronous message passing support available to Alchemy tasks. The caller sends a variable-sized message back to a remote task, in response to this task's initial message received by a call to rt_task_receive(). As a consequence of calling rt_task_reply(), the remote task will be unblocked from the rt_task_send() service.

A basic message control block is used to store the location and size of the data area to send back, in addition to a user-defined status code.

Parameters

flowid	The flow identifier returned by a previous call to rt_task_receive() which uniquely identifies the current transaction.
mcb_s	The address of an optional message control block referring to the message to be sent back. If mcb_s is NULL, the remote will be unblocked without getting any reply data. When mcb_s is valid, the fields from this control block should be set as follows:

mcb_s->data should contain the address of the payload data to send to the remote task.
mcb_s->size should contain the size in bytes of the payload data pointed at by mcb_s->data. Zero is a legitimate value, and indicates that no payload data will be transferred. In the latter case, mcb_s->data will be ignored.
mcb_s->opcode is an opaque status code carried during the message transfer the caller can fill with any appropriate value. It will be made available "as is" to the remote task into the status code field by the rt_task_send() service. If mcb_s is NULL, Zero will be returned to the remote task into the status code field.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if flowid is invalid.
-ENXIO is returned if flowid does not match the expected identifier returned from the latest call of the current task to rt_task_receive(), or if the remote task stopped waiting for the reply in the meantime (e.g. the remote could have been deleted or forcibly unblocked).
-ENOBUFS is returned if the reply data referred to by mcb_s is larger than the reply area mentioned by the remote task when calling rt_task_send(). In such a case, the remote task also receives -ENOBUFS on return from rt_task_send().
-EPERM is returned if this service was called from an invalid context.

Tags: xthread-only, switch-primary

◆ rt_task_resume()

int rt_task_resume ( RT_TASK * task )

Resume a real-time task.

Forcibly resume the execution of a task which was previously suspended by a call to rt_task_suspend(), if the suspend nesting count decrements to zero.

Parameters

task	The task descriptor.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if task is not a valid task descriptor.

Tags: unrestricted, switch-primary

Note: Blocked and suspended task states are cumulative. Therefore, resuming a task currently waiting on a synchronization object (e.g. semaphore, queue) does not make it eligible for scheduling until the awaited resource is eventually acquired, or a timeout elapses.

◆ rt_task_same()

int rt_task_same	(	RT_TASK *	task1,
		RT_TASK *	task2
	)

Compare real-time task descriptors.

This predicate returns true if task1 and task2 refer to the same task.

Parameters

task1	First task descriptor to compare.
task2	Second task descriptor to compare.

Returns: A non-zero value is returned if both descriptors refer to the same task, zero otherwise.

Tags: unrestricted

◆ rt_task_self()

RT_TASK * rt_task_self ( void )

Retrieve the current task descriptor.

Return the address of the current Alchemy task descriptor.

Returns: The address of the task descriptor referring to the current Alchemy task is returned upon success, or NULL if not called from a valid Alchemy task context.

Tags: xthread-only

◆ rt_task_send()

ssize_t rt_task_send	(	RT_TASK *	task,
		RT_TASK_MCB *	mcb_s,
		RT_TASK_MCB *	mcb_r,
		RTIME	timeout
	)

inlinestatic

Send a message to a real-time task (with relative scalar timeout).

This routine is a variant of rt_task_send_timed() accepting a relative timeout specification expressed as a scalar value.

Parameters

task	The task descriptor.
mcb_s	The address of the message control block referring to the message to be sent.
mcb_r	The address of an optional message control block referring to the reply message area.
timeout	A delay expressed in clock ticks.

Tags: xthread-only, switch-primary

References rt_task_send_timed().

◆ rt_task_send_timed()

ssize_t rt_task_send_timed	(	RT_TASK *	task,
		RT_TASK_MCB *	mcb_s,
		RT_TASK_MCB *	mcb_r,
		const struct timespec *	abs_timeout
	)

Send a message to a real-time task.

This service is part of the synchronous message passing support available to Alchemy tasks. The caller sends a variable-sized message to another task, waiting for the remote to receive the initial message by a call to rt_task_receive(), then reply to it using rt_task_reply().

A basic message control block is used to store the location and size of the data area to send or retrieve upon reply, in addition to a user-defined operation code.

Parameters

task	The task descriptor.
mcb_s	The address of the message control block referring to the message to be sent. The fields from this control block should be set as follows:

mcb_s->data should contain the address of the payload data to send to the remote task.
mcb_s->size should contain the size in bytes of the payload data pointed at by mcb_s->data. Zero is a legitimate value, and indicates that no payload data will be transferred. In the latter case, mcb_s->data will be ignored.
mcb_s->opcode is an opaque operation code carried during the message transfer, the caller can fill with any appropriate value. It will be made available "as is" to the remote task into the operation code field by the rt_task_receive() service.

Parameters

mcb_r The address of an optional message control block referring to the reply message area. If mcb_r is NULL and a reply is sent back by the remote task, the reply message will be discarded, and -ENOBUFS will be returned to the caller. When mcb_r is valid, the fields from this control block should be set as follows:

mcb_r->data should contain the address of a buffer large enough to collect the reply data from the remote task.
mcb_r->size should contain the size in bytes of the buffer space pointed at by mcb_r->data. If mcb_r->size is lower than the actual size of the reply message, no data copy takes place and -ENOBUFS is returned to the caller.

Upon return, mcb_r->opcode will contain the status code sent back from the remote task using rt_task_reply(), or zero if unspecified.

Parameters

abs_timeout An absolute date expressed in clock ticks, specifying a time limit to wait for the recipient task to reply to the initial message (see note). Passing NULL causes the caller to block indefinitely until a reply is received. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return without blocking in case the recipient task is not waiting for messages at the time of the call.

Returns: A positive value is returned upon success, representing the length (in bytes) of the reply message returned by the remote task. Zero is a success status, meaning either that mcb_r was NULL on entry, or that no actual message was passed to the remote call to rt_task_reply(). Otherwise:

-EINVAL is returned if task is not a valid task descriptor.
-EPERM is returned if this service was called from an invalid context.
-ENOBUFS is returned if mcb_r does not point at a message area large enough to collect the remote task's reply. This includes the case where mcb_r is NULL on entry, despite the remote task attempts to send a reply message.
-EWOULDBLOCK is returned if abs_timeout is { .tv_sec = 0, .tv_nsec = 0 } and the recipient task is not currently waiting for a message on the rt_task_receive() service.
-EIDRM is returned if task has been deleted while waiting for a reply.
-EINTR is returned if rt_task_unblock() was called for the current task before any reply was received from the recipient task.

Tags: xthread-only, switch-primary

Note: abs_timeout is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

Referenced by rt_task_send(), and rt_task_send_until().

◆ rt_task_send_until()

ssize_t rt_task_send_until	(	RT_TASK *	task,
		RT_TASK_MCB *	mcb_s,
		RT_TASK_MCB *	mcb_r,
		RTIME	abs_timeout
	)

inlinestatic

Send a message to a real-time task (with absolute scalar timeout).

This routine is a variant of rt_task_send_timed() accepting an absolute timeout specification expressed as a scalar value.

Parameters

task	The task descriptor.
mcb_s	The address of the message control block referring to the message to be sent.
mcb_r	The address of an optional message control block referring to the reply message area.
abs_timeout	An absolute date expressed in clock ticks.

Tags: xthread-only, switch-primary

References rt_task_send_timed().

◆ rt_task_set_affinity()

int rt_task_set_affinity	(	RT_TASK *	task,
		const cpu_set_t *	cpus
	)

Set CPU affinity of real-time task.

This calls makes task affine to the set of CPUs defined by cpus.

Parameters

task	The task descriptor. If task is NULL, the CPU affinity of the current task is changed.
cpus	The set of CPUs task should be affine to.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if task is NULL but the caller is not a Xenomai task, or if task is non-NULL but not a valid task descriptor.
-EINVAL is returned if cpus contains no processors that are currently physically on the system and permitted to the process according to any restrictions that may be imposed by the "cpuset" mechanism described in cpuset(7).

Tags: mode-unrestricted, switch-secondary

Note: The caller must be an Alchemy task if task is NULL.

◆ rt_task_set_mode()

int rt_task_set_mode	(	int	clrmask,
		int	setmask,
		int *	mode_r
	)

Change the current task mode.

Each Alchemy task has a set of internal flags determining several operating conditions. rt_task_set_mode() takes a bitmask of mode bits to clear for disabling the corresponding modes for the current task, and another one to set for enabling them. The mode bits which were previously in effect before the change can be returned upon request.

The following bits can be part of the bitmask:

T_LOCK causes the current task to lock the scheduler on the current CPU, preventing all further involuntary task switches on this CPU. Clearing this bit unlocks the scheduler.
Only when running over the Cobalt core:
- T_WARNSW causes the SIGDEBUG signal to be sent to the current task whenever it switches to the secondary mode. This feature is useful to detect unwanted migrations to the Linux domain.
- T_CONFORMING can be passed in setmask to switch the current Alchemy task to its preferred runtime mode. The only meaningful use of this switch is to force a real-time task back to primary mode (see note). Any other use leads to a nop.

These two last flags have no effect over the Mercury core, and are simply ignored.

Parameters

clrmask	A bitmask of mode bits to clear for the current task, before setmask is applied. Zero is an acceptable value which leads to a no-op.
setmask	A bitmask of mode bits to set for the current task. Zero is an acceptable value which leads to a no-op.
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: Zero is returned upon success. Otherwise:

-EINVAL is returned if task is not a valid task descriptor, or if any bit from clrmask or setmask is invalid.
-EPERM is returned if this service was called from an invalid context.

Tags: xthread-only, switch-primary

Note: The caller must be an Alchemy task.; Forcing the task mode using the T_CONFORMING bit from user code is almost always wrong, since the Xenomai/cobalt core handles mode switches internally when/if required. Most often, manual mode switching from applications introduces useless overhead. This mode bit is part of the API only to cover rare use cases in middleware code based on the Alchemy interface.

References T_LOCK, and T_WARNSW.

◆ rt_task_set_periodic()

int rt_task_set_periodic	(	RT_TASK *	task,
		RTIME	idate,
		RTIME	period
	)

Make a real-time task periodic.

Make a task periodic by programing its first release point and its period in the processor time line. task should then call rt_task_wait_period() to sleep until the next periodic release point in the processor timeline is reached.

Parameters

task	The task descriptor. If task is NULL, the current task is made periodic. task must belong the current process.
idate	The initial (absolute) date of the first release point, expressed in clock ticks (see note). If idate is equal to TM_NOW, the current system date is used.
period	The period of the task, expressed in clock ticks (see note). Passing TM_INFINITE stops the task's periodic timer if enabled, then returns successfully.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if task is NULL but the caller is not a Xenomai task, or if task is non-NULL but not a valid task descriptor.
-ETIMEDOUT is returned if idate is different from TM_INFINITE and represents a date in the past.

Tags: mode-unrestricted, switch-primary

Note: The caller must be an Alchemy task if task is NULL.; Over Cobalt, -EINVAL is returned if period is different from TM_INFINITE but shorter than the user scheduling latency value for the target system, as displayed by /proc/xenomai/latency.; The idate and period values are interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

Attention: Unlike its Xenomai 2.x counterpart, rt_task_set_periodic() will NOT block task until idate is reached. The first beat in the periodic timeline should be awaited for by a call to rt_task_wait_period().

Examples:: cross-link.c.

◆ rt_task_set_priority()

int rt_task_set_priority	(	RT_TASK *	task,
		int	prio
	)

Change the base priority of a real-time task.

The base priority of a task defines the relative importance of the work being done by each task, which gains conrol of the CPU accordingly.

Changing the base priority of a task does not affect the priority boost the target task might have obtained as a consequence of a priority inheritance undergoing.

Parameters

task	The task descriptor. If task is NULL, the priority of the current task is changed.
prio	The new priority. This value must range from [T_LOPRIO .. T_HIPRIO] (inclusive) where T_LOPRIO is the lowest effective priority.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if task is not a valid task descriptor, or if prio is invalid.
-EPERM is returned if task is NULL and this service was called from an invalid context.

Tags: mode-unrestricted, switch-primary

Note: The caller must be an Alchemy task if task is NULL.; Assigning the same priority to a running or ready task moves it to the end of its priority group, thus causing a manual round-robin.

◆ rt_task_shadow()

int rt_task_shadow	(	RT_TASK *	task,
		const char *	name,
		int	prio,
		int	mode
	)

Turn caller into a real-time task.

Set the calling thread personality to the Alchemy API, enabling the full set of Alchemy services. Upon success, the caller is no more a regular POSIX thread, but a Xenomai-extended thread.

If prio is non-zero, the new task moves to Xenomai's real-time FIFO scheduling class, aka SCHED_FIFO. If prio is zero, the task moves to the regular SCHED_OTHER class.

Running Xenomai tasks with zero priority is useful for running non real-time processes which may invoke blocking real-time services, such as pending on a semaphore, reading from a message queue or a buffer, and so on.

Parameters

task	If non-NULL, the address of a task descriptor which can be later used to identify uniquely the task, upon success of this call. If NULL, no descriptor is returned.
name	An ASCII string standing for the symbolic name of the task. When non-NULL and non-empty, a copy of this string is used for indexing the task into the object registry.
prio	The base priority of the task. This value must be in the [0 .. 99] range, where 0 is the lowest effective priority.
mode	The task shadowing mode. The following flags can be OR'ed into this bitmask:

T_LOCK causes the current task to lock the scheduler before returning to the caller, preventing all further involuntary task switches on the current CPU. A call to rt_task_set_mode() from the current task is required to drop this lock.
When running over the Cobalt core, T_WARNSW causes the SIGDEBUG signal to be sent to the current task whenever it switches to the secondary mode. This feature is useful to detect unwanted migrations to the Linux domain. This flag has no effect over the Mercury core.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if prio is invalid.
-ENOMEM is returned if the system fails to get memory from the main heap in order to create the task extension.
-EEXIST is returned if the name is conflicting with an already registered task.
-EBUSY is returned if the caller is not a regular POSIX thread.

Tags: pthread-only, switch-secondary, switch-primary

Side effects: Over Cobalt, if the caller is a plain POSIX thread, it is turned into a Xenomai shadow thread, with full access to all Cobalt services. The caller always returns from this service in primary mode.

Note: Tasks can be referred to from multiple processes which all belong to the same Xenomai session.

Examples:: rtcanrecv.c, and rtcansend.c.

◆ rt_task_sleep()

int rt_task_sleep ( RTIME delay )

Delay the current real-time task (with relative delay).

This routine is a variant of rt_task_sleep_until() accepting a relative timeout specification.

Parameters

delay A relative delay expressed in clock ticks (see note). A zero delay causes this service to return immediately to the caller with a success status.

Returns: See rt_task_sleep_until().

Tags: xthread-only, switch-primary

Note: The delay value is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

Examples:: cross-link.c, and rtcansend.c.

◆ rt_task_sleep_until()

int rt_task_sleep_until ( RTIME date )

Delay the current real-time task (with absolute wakeup date).

Delay the execution of the calling task until a given date is reached. The caller is put to sleep, and does not consume any CPU time in such a state.

Parameters

date An absolute date expressed in clock ticks, specifying a wakeup date (see note). As a special case, TM_INFINITE is an acceptable value that causes the caller to block indefinitely, until rt_task_unblock() is called against it. Otherwise, any wake up date in the past causes the task to return immediately.

Returns: Zero is returned upon success. Otherwise:

-EINTR is returned if rt_task_unblock() was called for the current task.
-ETIMEDOUT is returned if date has already elapsed.
-EPERM is returned if this service was called from an invalid context.

Tags: xthread-only, switch-primary

Note: The caller must be an Alchemy task if task is NULL.; The date value is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

◆ rt_task_slice()

int rt_task_slice	(	RT_TASK *	task,
		RTIME	quantum
	)

Set a task's round-robin quantum.

Set the time credit allotted to a task undergoing the round-robin scheduling. If quantum is non-zero, rt_task_slice() also refills the current quantum for the target task, otherwise, time-slicing is stopped for that task.

In other words, rt_task_slice() should be used to toggle round-robin scheduling for an Alchemy task.

Parameters

task	The task descriptor. If task is NULL, the time credit of the current task is changed. task must belong to the current process.
quantum	The round-robin quantum for the task expressed in clock ticks (see note).

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if task is not a valid task descriptor, or if prio is invalid.
-EPERM is returned if task is NULL and this service was called from an invalid context.

Tags: mode-unrestricted, switch-primary

Note: The caller must be an Alchemy task if task is NULL.; The quantum value is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

◆ rt_task_spawn()

int rt_task_spawn	(	RT_TASK *	task,
		const char *	name,
		int	stksize,
		int	prio,
		int	mode,
		void()(void arg)	entry,
		void *	arg
	)

Create and start a real-time task.

This service spawns a task by combining calls to rt_task_create() and rt_task_start() for the new task.

Parameters

task	The address of a task descriptor which can be later used to identify uniquely the created object, upon success of this call.
name	An ASCII string standing for the symbolic name of the task. When non-NULL and non-empty, a copy of this string is used for indexing the created task into the object registry.
stksize	The size of the stack (in bytes) for the new task. If zero is passed, a system-dependent default size will be substituted.
prio	The base priority of the new task. This value must be in the [0 .. 99] range, where 0 is the lowest effective priority.
mode	The task creation mode. See rt_task_create().
entry	The address of the task entry point.
arg	A user-defined opaque argument entry will receive.

Returns: See rt_task_create().

Tags: mode-unrestricted, switch-secondary

Side effects: see rt_task_create().

◆ rt_task_start()

int rt_task_start	(	RT_TASK *	task,
		void()(void arg)	entry,
		void *	arg
	)

Start a real-time task.

This call starts execution of a task previously created by rt_task_create(). This service causes the started task to leave the initial dormant state.

Parameters

task	The task descriptor.
entry	The address of the task entry point.
arg	A user-defined opaque argument entry will receive.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if task is not a valid task descriptor.

Tags: mode-unrestricted, switch-primary

Note: Starting an already started task leads to a nop, returning a success status.

Examples:: cross-link.c.

◆ rt_task_suspend()

int rt_task_suspend ( RT_TASK * task )

Suspend a real-time task.

Forcibly suspend the execution of a task. This task will not be eligible for scheduling until it is explicitly resumed by a call to rt_task_resume(). In other words, the suspended state caused by a call to rt_task_suspend() is cumulative with respect to the delayed and blocked states caused by other services, and is managed separately from them.

A nesting count is maintained so that rt_task_suspend() and rt_task_resume() must be used in pairs.

Receiving a Linux signal causes the suspended task to resume immediately.

Parameters

task	The task descriptor. If task is NULL, the current task is suspended.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if task is NULL but the caller is not a Xenomai task, or if task is non-NULL but not a valid task descriptor.
-EINTR is returned if a Linux signal has been received by the caller if suspended.
-EPERM is returned if task is NULL and this service was called from an invalid context.

Tags: mode-unrestricted, switch-primary

Note: The caller must be an Alchemy task if task is NULL.; Blocked and suspended task states are cumulative. Therefore, suspending a task currently waiting on a synchronization object (e.g. semaphore, queue) holds its execution until it is resumed, despite the awaited resource may have been acquired, or a timeout has elapsed in the meantime.

◆ rt_task_unbind()

int rt_task_unbind ( RT_TASK * task )

Unbind from a task.

Parameters

task	The task descriptor.

This routine releases a previous binding to an Alchemy task. After this call has returned, the descriptor is no more valid for referencing this object.

Tags: thread-unrestricted

◆ rt_task_unblock()

int rt_task_unblock ( RT_TASK * task )

Unblock a real-time task.

Break the task out of any wait it is currently in. This call clears all delay and/or resource wait condition for the target task.

However, rt_task_unblock() does not resume a task which has been forcibly suspended by a previous call to rt_task_suspend(). If all suspensive conditions are gone, the task becomes eligible anew for scheduling.

Parameters

task	The task descriptor.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if task is not a valid task descriptor.

Tags: unrestricted, switch-primary

◆ rt_task_wait_period()

int rt_task_wait_period ( unsigned long * overruns_r )

Wait for the next periodic release point.

Delay the current task until the next periodic release point is reached. The periodic timer should have been previously started for task by a call to rt_task_set_periodic().

Parameters

overruns_r If non-NULL, overruns_r shall be a pointer to a memory location which will be written with the count of pending overruns. This value is written to only when rt_task_wait_period() returns -ETIMEDOUT or success. The memory location remains unmodified otherwise. If NULL, this count will not be returned.

Returns: Zero is returned upon success. If overruns_r is non-NULL, zero is written to the pointed memory location. Otherwise:

-EWOULDBLOCK is returned if rt_task_set_periodic() was not called for the current task.
-EINTR is returned if rt_task_unblock() was called for the waiting task before the next periodic release point was reached. In this case, the overrun counter is also cleared.
-ETIMEDOUT is returned if a timer overrun occurred, which indicates that a previous release point was missed by the calling task. If overruns_r is non-NULL, the count of pending overruns is written to the pointed memory location.
-EPERM is returned if this service was called from an invalid context.

Tags: xthread-only, switch-primary

Note: If the current release point has already been reached at the time of the call, the current task immediately returns from this service with no delay.

Examples:: cross-link.c.

◆ rt_task_yield()

int rt_task_yield ( void )

Manual round-robin.

Move the current task to the end of its priority group, so that the next equal-priority task in ready state is switched in.

Returns: Zero is returned upon success. Otherwise:

-EPERM is returned if this service was called from an invalid context.

Tags: xthread-only, switch-primary

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ T_LOCK

◆ T_LOPRIO

◆ T_WARNSW

Function Documentation

◆ rt_task_bind()

◆ rt_task_create()

◆ rt_task_delete()

◆ rt_task_inquire()

◆ rt_task_join()

◆ rt_task_receive()

◆ rt_task_receive_timed()

◆ rt_task_receive_until()

◆ rt_task_reply()

◆ rt_task_resume()

◆ rt_task_same()

◆ rt_task_self()

◆ rt_task_send()

◆ rt_task_send_timed()

◆ rt_task_send_until()

◆ rt_task_set_affinity()

◆ rt_task_set_mode()

◆ rt_task_set_periodic()

◆ rt_task_set_priority()

◆ rt_task_shadow()

◆ rt_task_sleep()

◆ rt_task_sleep_until()

◆ rt_task_slice()

◆ rt_task_spawn()

◆ rt_task_start()

◆ rt_task_suspend()

◆ rt_task_unbind()

◆ rt_task_unblock()

◆ rt_task_wait_period()

◆ rt_task_yield()