Add real-time scheduling helper functions and documentation#535
Add real-time scheduling helper functions and documentation#535srvald wants to merge 25 commits into
Conversation
…ions documentation.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #535 +/- ##
==========================================
+ Coverage 78.95% 79.09% +0.14%
==========================================
Files 115 115
Lines 6766 6788 +22
Branches 2986 3004 +18
==========================================
+ Hits 5342 5369 +27
+ Misses 1052 1044 -8
- Partials 372 375 +3
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. |
…removed from being executed with Apple
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
There are 4 total unresolved issues (including 3 from previous reviews).
Reviewed by Cursor Bugbot for commit 37599d1. Configure here.
| cpu_set_t cpuset; | ||
| CPU_ZERO(&cpuset); | ||
| CPU_SET(0, &cpuset); | ||
| EXPECT_DEATH(setThreadAffinity(thread, cpuset), ""); |
There was a problem hiding this comment.
Linux invalid handle expects death
Medium Severity
The Linux branch of setThreadAffinity_invalidHandle uses EXPECT_DEATH for a default-constructed pthread_t, but setThreadAffinity calls pthread_setaffinity_np and returns false on error (for example ESRCH) without terminating the process.
Reviewed by Cursor Bugbot for commit 37599d1. Configure here.
There was a problem hiding this comment.
@urfeex The expect death is set because when using an invalid handle on Ubuntu it will seg fault. Therefore if I use expect false it will raise an error.
|
@urfeex Regarding the missing Codecov lines, I'm not sure how to reproduce those failures. They were added as defensive checks, but so far I haven't been able to trigger those conditions or reproduce them in the tests. |
1 participant
Summary
This PR improves the real-time scheduling utilities in the client library and adds
documentation and examples for configuring scheduling priorities and CPU affinity
on both Linux and Windows.
Motivation
During internal tests on Windows, the RTDE example
rtde_client.cppwas executed while measuring cycle time and RTDE package parsing time.Without any explicit CPU affinity or scheduling configuration, the application
showed higher scheduling jitter and less predictable execution timing.
After configuring CPU affinity and high-priority scheduling using the helper
functions introduced in this PR, both jitter and worst-case latency were
significantly reduced.
Timing measurements on Windows
Key observations:
Parse time jitter was significantly reduced:
Cycle time became more predictable:
While the average cycle time remained essentially unchanged (~2 ms), the reduction in jitter and worst-case latency improves timing predictability.
Changes
Helper functions
Added platform-specific helper functions for configuring execution priorities and
CPU affinities.
The helpers are not simple wrappers around the operating system APIs. Where
supported by the underlying platform, they:
The function returns
trueonly when the requested configuration is successfullyapplied and verified. Otherwise, it returns
false.Windows
Added wrappers for:
setProcessPriority()SetPriorityClasssetProcessAffinity()SetProcessAffinityMasksetThreadPriority()SetThreadPrioritysetThreadAffinity()SetThreadAffinityMaskExtended
setFiFoScheduling()to configure:REALTIME_PRIORITY_CLASSAdditional improvements:
FormatMessage()Linux
setThreadAffinity()(pthread_setaffinity_np)Documentation
Added a new section to
real_time.rstcovering:Device ConfigurationReal Time ApplicationScheduling prioritiesRTDE example
Updated the RTDE client example to demonstrate:
Tests
Added unit tests covering:
Example output
Successful configuration may produce logs similar to:
If the application is executed without administrative privileges and attempts to
configure
REALTIME_PRIORITY_CLASS, the following warning and verificationmessages may be reported:
If an operation fails, the helper functions report both the operating system
error code and a readable error description:
[Error] Unsuccessful in setting process affinity to CPUs [] (mask=0x0). Error: 87 (The parameter is incorrect.)[INFO] Thread affinity successfully set to CPUs [7] [INFO] SCHED_FIFO OK, priority 99Note
Medium Risk
Changes OS scheduling and affinity at runtime (including
REALTIME_PRIORITY_CLASSon Windows), which can affect system responsiveness if misused; behavior is mostly additive with explicit failure paths and tests.Overview
Adds verified CPU affinity and priority helpers for Linux and Windows, documents Windows soft real-time setup, and wires the RTDE example to use them before communication starts.
On Windows, new APIs wrap process/thread priority and affinity (
setProcessPriority,setProcessAffinity,setThreadAffinity,setThreadPriority), pluspprocess_self(). Implementations read back OS state, log outcomes, restore priorities on mismatch, and warn whenREALTIME_PRIORITY_CLASSis requested without elevation.setFiFoSchedulingnow promotes the process toREALTIME_PRIORITY_CLASSand sets the thread priority instead of only callingSetThreadPriority.On Linux,
setThreadAffinityis added with post-apply verification; existingsetFiFoSchedulingbehavior is unchanged aside from living alongside the new helper.examples/rtde_client.cpppins CPUs (process mask on Windows, thread CPU 7 on Linux) and requests max FIFO scheduling at startup.doc/real_time.rstanddoc/examples/rtde_client.rstdescribe helper usage and Microsoft soft-RT guidance.tests/test_helpers.cppadds coverage for valid/invalid affinity and priority cases (Windows-only for process helpers).Reviewed by Cursor Bugbot for commit 41f371c. Bugbot is set up for automated code reviews on this repo. Configure here.