| 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: |
| |
| - :c:func:`sched_setparam` |
| - :c:func:`sched_getparam` |
| - :c:func:`sched_setscheduler` |
| - :c:func:`sched_getscheduler` |
| - :c:func:`sched_yield` |
| - :c:func:`sched_get_priority_max` |
| - :c:func:`sched_get_priority_min` |
| - :c:func:`sched_get_rr_interval` |
| |
| Functions |
| --------- |
| |
| .. c:function:: 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. |
| |
| :param pid: The task ID of the task. If ``pid`` is zero, the priority of |
| the calling task is set. |
| :param 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``. |
| |
| :return: 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. |
| |
| .. c:function:: int sched_getparam(pid_t pid, FAR struct sched_param *param) |
| |
| This function gets the scheduling priority of the task |
| specified by pid. |
| |
| :param pid: The task ID of the task. If pid is zero, the priority of the |
| calling task is returned. |
| :param 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. |
| |
| :return: 0 (``OK``) if successful, otherwise -1 (``ERROR``). |
| |
| **POSIX Compatibility:** Comparable to the POSIX interface of the same |
| name. |
| |
| .. c:function:: 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. |
| |
| :param pid: The task ID of the task. If ``pid`` is zero, the priority of |
| the calling task is set. |
| :param policy: Scheduling policy requested (either ``SCHED_FIFO`` or |
| ``SCHED_RR``). |
| :param 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``. |
| |
| :return: 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. |
| |
| .. c:function:: 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. |
| |
| :param pid: The task ID of the task to query. If ``pid`` is zero, the |
| calling task is queried. |
| |
| :return: 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. |
| |
| .. c:function:: int sched_yield(void) |
| |
| This function forces the calling task to give up the |
| CPU (only to other tasks at the same priority). |
| |
| :return: 0 (``OK``) or -1 (``ERROR``) |
| |
| **POSIX Compatibility:** Comparable to the POSIX interface of the same |
| name. |
| |
| .. c:function:: int sched_get_priority_max (int policy) |
| |
| This function returns the value of the highest possible |
| task priority for a specified scheduling policy. |
| |
| :param policy: Scheduling policy requested. |
| |
| :return: The maximum priority value or -1 (``ERROR``). |
| |
| **POSIX Compatibility:** Comparable to the POSIX interface of the same |
| name. |
| |
| .. c:function:: int sched_get_priority_min (int policy) |
| |
| This function returns the value of the lowest possible |
| task priority for a specified scheduling policy. |
| |
| :param policy: Scheduling policy requested. |
| |
| :return: The minimum priority value or -1 (``ERROR``) |
| |
| **POSIX Compatibility:** Comparable to the POSIX interface of the same |
| name. |
| |
| .. c:function:: 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.' |
| |
| :param pid: The task ID of the task. If pid is zero, the priority of the |
| calling task is returned. |
| :param interval: A structure used to return the time slice. |
| |
| :return: 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. |
