123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181 |
- 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.
|