.. _set_rt_thread_priority:

set_rt_thread_priority
------------------------------------------
This function sets the operating system scheduling priority that the library uses to receive real-time data and run real-time callbacks. The setting applies from the next :ref:`connect_rt_control <connect_rt_control>`. Without this call, the library uses the operating system's default scheduling.

**Definition** |br|
``DRFLEx.h`` within class `CDRFLEx`, public section

.. code-block:: cpp

   bool set_rt_thread_priority(int nPolicy, int nPriority) { return _set_rt_thread_priority(_rbtCtrlUDP, nPolicy, nPriority); };

**Parameter**

.. list-table::
   :widths: 20 20 60
   :header-rows: 1

   * - **Parameter Name**
     - **Data Type**
     - **Description**
   * - nPolicy
     - int
     - Scheduling policy. |br| Linux: ``SCHED_FIFO``, ``SCHED_RR`` or ``SCHED_OTHER``. |br| Windows: ``0``. |br| ``-1`` restores the default scheduling on both systems.
   * - nPriority
     - int
     - Scheduling priority. |br| Linux: with ``SCHED_FIFO`` or ``SCHED_RR``, a value from ``sched_get_priority_min`` to ``sched_get_priority_max`` for that policy (1 to 99); with ``SCHED_OTHER``, ``0``. |br| Windows: a ``THREAD_PRIORITY_*`` level: ``THREAD_PRIORITY_IDLE`` (-15), ``THREAD_PRIORITY_LOWEST`` (-2), ``THREAD_PRIORITY_BELOW_NORMAL`` (-1), ``THREAD_PRIORITY_NORMAL`` (0), ``THREAD_PRIORITY_ABOVE_NORMAL`` (1), ``THREAD_PRIORITY_HIGHEST`` (2) or ``THREAD_PRIORITY_TIME_CRITICAL`` (15). |br| Ignored when ``nPolicy`` is ``-1``.

**Return**

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - **Value**
     - **Description**
   * - 1
     - The setting is stored and applies from the next :ref:`connect_rt_control <connect_rt_control>`.
   * - 0
     - Nothing changed. Real-time control is connected, the policy or priority is not valid, or (Linux) the process is not allowed to use the requested real-time priority. For an invalid or disallowed value, the library prints the reason to standard error.

.. Caution::

   - Call this function before :ref:`connect_rt_control <connect_rt_control>` or after :ref:`disconnect_rt_control <disconnect_rt_control>`. While real-time control is connected, it returns 0.
   - If the priority cannot be applied when :ref:`connect_rt_control <connect_rt_control>` runs, ``connect_rt_control`` returns 0 and closes the real-time connection.
   - On Linux, ``SCHED_FIFO`` and ``SCHED_RR`` need permission to use real-time scheduling: the ``CAP_SYS_NICE`` capability, or an ``RLIMIT_RTPRIO`` limit of at least ``nPriority`` (for example set with ``ulimit -r``).

**Example**

.. code-block:: cpp

   #include <sched.h>

   // Receive RT data and run RT callbacks at SCHED_FIFO priority 80 (Linux).
   if (!drfl.set_rt_thread_priority(SCHED_FIFO, 80)) {
       printf("SCHED_FIFO 80 is not available.\n");
   }
   if (drfl.connect_rt_control("192.168.137.100", 12347)) {
       drfl.start_rt_control();
   }

In this example, the priority is set before the RT channel is connected, so it applies to that connection.

**Tips**

- Use ``set_rt_thread_priority(-1, 0)`` to return to the default scheduling for the next connection.