Task Scheduling Interfaces

By default, NuttX performs strict priority scheduling: Tasks of higher priority have exclusive access to the CPU until they become blocked. At that time, the CPU is available to tasks of lower priority. Tasks of equal priority are scheduled FIFO.

Optionally, a NuttX task or thread can be configured with round-robin or sporadic scheduler. The round-robin is similar to priority scheduling except that tasks with equal priority and share CPU time via time-slicing. The time-slice interval is a constant determined by the configuration setting CONFIG_RR_INTERVAL to a positive, non-zero value. Sporadic scheduling scheduling is more complex, varying the priority of a thread over a replenishment period. Support for sporadic scheduling is enabled by the configuration option CONFIG_SCHED_SPORADIC.

The OS interfaces described in the following paragraphs provide a POSIX- compliant interface to the NuttX scheduler:

Functions

int sched_setparam(pid_t pid, FAR const struct sched_param *param)

This function sets the priority of the task specified by pid input parameter.

Parameters

  • pid – The task ID of the task. If pid is zero, the priority of the calling task is set.

  • param – A structure whose member sched_priority is the integer priority. The range of valid priority numbers is from SCHED_PRIORITY_MIN through SCHED_PRIORITY_MAX.

Returns

On success, sched_setparam() returns 0 (OK). On error, -1 (ERROR) is returned, and `errno <#ErrnoAccess>`__ is set appropriately.

  • EINVAL. The parameter param is invalid or does not make sense for the current scheduling policy.

  • EPERM. The calling task does not have appropriate privileges.

  • ESRCH. The task whose ID is pid could not be found.

POSIX Compatibility: Comparable to the POSIX interface of the same name. Differences from the full POSIX implementation include:

  • The range of priority values for the POSIX call is 0 to 255. The priority 0 is the lowest priority and 255 is the highest priority.

Note

Setting a task’s priority to the same value has the similar effect to sched_yield(): The task will be moved to after all other tasks with the same priority.

int sched_getparam(pid_t pid, FAR struct sched_param *param)

This function gets the scheduling priority of the task specified by pid.

Parameters

  • pid – The task ID of the task. If pid is zero, the priority of the calling task is returned.

  • param – A structure whose member sched_priority is the integer priority. The task’s priority is copied to the sched_priority element of this structure.

Returns

0 (OK) if successful, otherwise -1 (ERROR).

POSIX Compatibility: Comparable to the POSIX interface of the same name.

int sched_setscheduler(pid_t pid, int policy, const struct sched_param *param)

sched_setscheduler() sets both the scheduling policy and the priority for the task identified by pid. If pid equals zero, the scheduler of the calling thread will be set. The parameter param holds the priority of the thread under the new policy.

Parameters

  • pid – The task ID of the task. If pid is zero, the priority of the calling task is set.

  • policy – Scheduling policy requested (either SCHED_FIFO or SCHED_RR).

  • param – A structure whose member sched_priority is the integer priority. The range of valid priority numbers is from SCHED_PRIORITY_MIN through SCHED_PRIORITY_MAX.

Returns

On success, sched_setscheduler() returns OK (zero). On error, ERROR (-1) is returned, and errno is set appropriately:

  • EINVAL: The scheduling policy is not one of the recognized policies.

  • ESRCH: The task whose ID is pid could not be found.

POSIX Compatibility: Comparable to the POSIX interface of the same name.

int sched_getscheduler(pid_t pid)

sched_getscheduler() returns the scheduling policy currently applied to the task identified by pid. If pid equals zero, the policy of the calling process will be retrieved.

Parameters

  • pid – The task ID of the task to query. If pid is zero, the calling task is queried.

Returns

On success, sched_getscheduler() returns the policy for the task (either SCHED_FIFO or SCHED_RR). On error, ERROR (-1) is returned, and errno is set appropriately:

  • ESRCH: The task whose ID is pid could not be found.

POSIX Compatibility: Comparable to the POSIX interface of the same name.

int sched_yield(void)

This function forces the calling task to give up the CPU (only to other tasks at the same priority).

Returns

0 (OK) or -1 (ERROR)

POSIX Compatibility: Comparable to the POSIX interface of the same name.

int sched_get_priority_max(int policy)

This function returns the value of the highest possible task priority for a specified scheduling policy.

Parameters

  • policy – Scheduling policy requested.

Returns

The maximum priority value or -1 (ERROR).

POSIX Compatibility: Comparable to the POSIX interface of the same name.

int sched_get_priority_min(int policy)

This function returns the value of the lowest possible task priority for a specified scheduling policy.

Parameters

  • policy – Scheduling policy requested.

Returns

The minimum priority value or -1 (ERROR)

POSIX Compatibility: Comparable to the POSIX interface of the same name.

int sched_get_rr_interval(pid_t pid, struct timespec *interval)

sched_rr_get_interval() writes the timeslice interval for task identified by pid into the timespec structure pointed to by interval. If pid is zero, the timeslice for the calling process is written into ‘interval. The identified process should be running under the SCHED_RR scheduling policy.’

Parameters

  • pid – The task ID of the task. If pid is zero, the priority of the calling task is returned.

  • interval – A structure used to return the time slice.

Returns

On success, sched_rr_get_interval() returns OK (0). On error, ERROR (-1) is returned, and errno is set to:

  • EFAULT: Cannot copy to interval

  • EINVAL: Invalid pid.

  • ENOSYS: The system call is not yet implemented.

  • ESRCH: The process whose ID is pid could not be found.

POSIX Compatibility: Comparable to the POSIX interface of the same name.