Xenomai  3.0-rc7
Collaboration diagram for Task Services:

Typedefs

typedef void(* rtdm_task_proc_t) (void *arg)
 Real-time task procedure. More...
 

Functions

int rtdm_task_init (rtdm_task_t *task, const char *name, rtdm_task_proc_t task_proc, void *arg, int priority, nanosecs_rel_t period)
 Initialise and start a real-time task. More...
 
void rtdm_task_destroy (rtdm_task_t *task)
 Destroy a real-time task. More...
 
int rtdm_task_should_stop (void)
 Check for pending termination request. More...
 
void rtdm_task_set_priority (rtdm_task_t *task, int priority)
 Adjust real-time task priority. More...
 
int rtdm_task_set_period (rtdm_task_t *task, nanosecs_rel_t period)
 Adjust real-time task period. More...
 
int rtdm_task_wait_period (void)
 Wait on next real-time task period. More...
 
int rtdm_task_unblock (rtdm_task_t *task)
 Activate a blocked real-time task. More...
 
rtdm_task_t * rtdm_task_current (void)
 Get current real-time task. More...
 
int rtdm_task_sleep (nanosecs_rel_t delay)
 Sleep a specified amount of time. More...
 
int rtdm_task_sleep_until (nanosecs_abs_t wakeup_time)
 Sleep until a specified absolute time. More...
 
int rtdm_task_sleep_abs (nanosecs_abs_t wakeup_time, enum rtdm_timer_mode mode)
 Sleep until a specified absolute time. More...
 
int rtdm_task_busy_wait (bool condition, nanosecs_rel_t spin_ns, nanosecs_rel_t sleep_ns)
 Safe busy waiting. More...
 
void rtdm_task_join (rtdm_task_t *task)
 Wait on a real-time task to terminate. More...
 
void rtdm_task_busy_sleep (nanosecs_rel_t delay)
 Busy-wait a specified amount of time. More...
 

Task Priority Range

Maximum and minimum task priorities

#define RTDM_TASK_LOWEST_PRIORITY   0
 
#define RTDM_TASK_HIGHEST_PRIORITY   99
 

Task Priority Modification

Raise or lower task priorities by one level

#define RTDM_TASK_RAISE_PRIORITY   (+1)
 
#define RTDM_TASK_LOWER_PRIORITY   (-1)
 

Detailed Description

Typedef Documentation

typedef void(* rtdm_task_proc_t) (void *arg)

Real-time task procedure.

Parameters
[in,out]argargument as passed to rtdm_task_init()

Function Documentation

void rtdm_task_busy_sleep ( nanosecs_rel_t  delay)

Busy-wait a specified amount of time.

This service does not schedule out the caller, but rather spins in a tight loop, burning CPU cycles until the timeout elapses.

Parameters
[in]delayDelay in nanoseconds. Note that a zero delay does not have the meaning of RTDM_TIMEOUT_INFINITE here.
Note
The caller must not be migratable to different CPUs while executing this service. Otherwise, the actual delay will be undefined.
Tags
unrestricted
int rtdm_task_busy_wait ( bool  condition,
nanosecs_rel_t  spin_ns,
nanosecs_rel_t  sleep_ns 
)

Safe busy waiting.

This service alternates active spinning and sleeping within a wait loop, until a condition is satisfied. While sleeping, a task is scheduled out and does not consume any CPU time.

rtdm_task_busy_wait() is particularly useful for waiting for a state change reading an I/O register, which usually happens shortly after the wait starts, without incurring the adverse effects of long busy waiting if it doesn't.

Parameters
[in]conditionThe C expression to be tested for detecting completion.
[in]spin_nsThe time to spin on condition before sleeping, expressed as a count of nanoseconds.
[in]sleep_nsThe time to sleep for before spinning again, expressed as a count of nanoseconds.
Returns
0 on success if condition is satisfied, otherwise:
  • -EINTR is returned if the calling task has been unblocked by a Linux signal or explicitly via rtdm_task_unblock().
  • -EPERM may be returned if an illegal invocation environment is detected.
Tags
primary-only, might-switch
rtdm_task_t* rtdm_task_current ( void  )

Get current real-time task.

Returns
Pointer to task handle
Tags
mode-unrestricted
void rtdm_task_destroy ( rtdm_task_t *  task)

Destroy a real-time task.

This call sends a termination request to task, then waits for it to exit. All RTDM task should check for pending termination requests by calling rtdm_task_should_stop() from their work loop.

If task is current, rtdm_task_destroy() terminates the current context, and does not return to the caller.

Parameters
[in,out]taskTask handle as returned by rtdm_task_init()
Note
Passing the same task handle to RTDM services after the completion of this function is not allowed.
Tags
secondary-only, might-switch
int rtdm_task_init ( rtdm_task_t *  task,
const char *  name,
rtdm_task_proc_t  task_proc,
void *  arg,
int  priority,
nanosecs_rel_t  period 
)

Initialise and start a real-time task.

After initialising a task, the task handle remains valid and can be passed to RTDM services until either rtdm_task_destroy() or rtdm_task_join() was invoked.

Parameters
[in,out]taskTask handle
[in]nameOptional task name
[in]task_procProcedure to be executed by the task
[in]argCustom argument passed to task_proc() on entry
[in]priorityPriority of the task, see also Task Priority Range
[in]periodPeriod in nanoseconds of a cyclic task, 0 for non-cyclic mode. Waiting for the first and subsequent periodic events is done using rtdm_task_wait_period().
Returns
0 on success, otherwise negative error code
Tags
secondary-only, might-switch

References xnthread_cancel(), xnthread_init(), xnthread_set_periodic(), and xnthread_start().

void rtdm_task_join ( rtdm_task_t *  task)

Wait on a real-time task to terminate.

Parameters
[in,out]taskTask handle as returned by rtdm_task_init()
Note
Passing the same task handle to RTDM services after the completion of this function is not allowed.
This service does not trigger the termination of the targeted task. The user has to take of this, otherwise rtdm_task_join() will never return.
Tags
mode-unrestricted

References xnthread_join().

int rtdm_task_set_period ( rtdm_task_t *  task,
nanosecs_rel_t  period 
)

Adjust real-time task period.

Parameters
[in,out]taskTask handle as returned by rtdm_task_init()
[in]periodNew period in nanoseconds of a cyclic task, 0 for non-cyclic mode
Tags
task-unrestricted
void rtdm_task_set_priority ( rtdm_task_t *  task,
int  priority 
)

Adjust real-time task priority.

Parameters
[in,out]taskTask handle as returned by rtdm_task_init()
[in]priorityNew priority of the task, see also Task Priority Range
Tags
task-unrestricted, might-switch
int rtdm_task_should_stop ( void  )

Check for pending termination request.

Check whether a termination request was received by the current RTDM task. Termination requests are sent by calling rtdm_task_destroy().

Returns
Non-zero indicates that a termination request is pending, in which case the caller should wrap up and exit.
Tags
rtdm-task, might-switch
int rtdm_task_sleep ( nanosecs_rel_t  delay)

Sleep a specified amount of time.

Parameters
[in]delayDelay in nanoseconds, see RTDM_TIMEOUT_xxx for special values.
Returns
0 on success, otherwise:
  • -EINTR is returned if calling task has been unblock by a signal or explicitly via rtdm_task_unblock().
  • -EPERM may be returned if an illegal invocation environment is detected.
Tags
primary-only, might-switch
int rtdm_task_sleep_abs ( nanosecs_abs_t  wakeup_time,
enum rtdm_timer_mode  mode 
)

Sleep until a specified absolute time.

Parameters
[in]wakeup_timeAbsolute timeout in nanoseconds
[in]modeSelects the timer mode, see RTDM_TIMERMODE_xxx for details
Returns
0 on success, otherwise:
  • -EINTR is returned if calling task has been unblock by a signal or explicitly via rtdm_task_unblock().
  • -EPERM may be returned if an illegal invocation environment is detected.
  • -EINVAL is returned if an invalid parameter was passed.
Tags
primary-only, might-switch
int rtdm_task_sleep_until ( nanosecs_abs_t  wakeup_time)

Sleep until a specified absolute time.

Deprecated:
Use rtdm_task_sleep_abs instead!
Parameters
[in]wakeup_timeAbsolute timeout in nanoseconds
Returns
0 on success, otherwise:
  • -EINTR is returned if calling task has been unblock by a signal or explicitly via rtdm_task_unblock().
  • -EPERM may be returned if an illegal invocation environment is detected.
Tags
primary-only, might-switch
int rtdm_task_unblock ( rtdm_task_t *  task)

Activate a blocked real-time task.

Returns
Non-zero is returned if the task was actually unblocked from a pending wait state, 0 otherwise.
Tags
unrestricted, might-switch
int rtdm_task_wait_period ( void  )

Wait on next real-time task period.

Returns
0 on success, otherwise:
  • -EINVAL is returned if calling task is not in periodic mode.
  • -ETIMEDOUT is returned if a timer overrun occurred, which indicates that a previous release point has been missed by the calling task.
Tags
primary-only, might-switch