Parallel scheduler documentation by filikat · Pull Request #3449 · ERGO-Code/HiGHS

filikat · 2026-10-20T12:01:48Z

Description

Add documentation about the parallel scheduler, in particular about initialisation, shutdown and thread safety.
Update comments related to thread safety of resetGlobalScheduler in C and Cpp API.
Change name of resetGlobalScheduler to resetThreadScheduler, since the scheduler is not global but is owned by the thread that created it. I am open to other names if people have better ideas. resetGlobalScheduler is retained for compatibility, but I put it in the list of deprecated methods. I cannot give a deprecationMessage though, as it's a static function.
Add a test checking that different threads have independent schedulers.

There is a large diff because many tests call resetGlobalScheduler.
@galabovaa I added resetThreadScheduler to the python binding in the same way as resetGlobalScheduler. I'm not sure if something else is needed.

Checklist

I have read the contributing guidelines
This PR targets the latest branch
Tests are passing
Documentation was updated where relevant
This PR is not primarily AI-generated (per the AI contributions policy in CONTRIBUTING.md)

codecov · 2026-10-20T12:15:43Z

Codecov Report

❌ Patch coverage is 98.20359% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.14%. Comparing base (d5e8e73) to head (b3e7094).
⚠️ Report is 76 commits behind head on latest.

Files with missing lines	Patch %	Lines
check/TestHighsParallel.cpp	95.58%	3 Missing ⚠️
highs/interfaces/highs_c_api.cpp	50.00%	2 Missing ⚠️
highs/lp_data/Highs.cpp	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           latest    #3449      +/-   ##
==========================================
+ Coverage   75.10%   75.14%   +0.04%     
==========================================
  Files         460      460              
  Lines      112008   112233     +225     
  Branches    17757    17792      +35     
==========================================
+ Hits        84125    84341     +216     
- Misses      27601    27610       +9     
  Partials      282      282

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Opt-Mucca

I like the new documentation! It's clear and addresses everything that I imagine a user would be interested in. Thanks for fixing some outdated lines on parallel MIP too.

galabovaa

Looks good to me! Thank you, @filikat

jajhall · 2026-10-21T15:02:31Z

- * undefined behavior and may cause crashes, but cannot be detected and hence
- * is fully in the callers responsibility.
+ * this function while on a worker thread or during the execution of a Highs
+ * function may cause crashes, but cannot be detected and hence is fully in the


Better and correct: "fully the caller's resonsibility."

jajhall · 2026-10-21T15:17:37Z

+
+- The first time an application thread calls `run()` or `presolve()`, HiGHS creates a scheduler for that thread. The thread becomes its owning thread.
+- All `Highs` instances used on the same application thread share that thread's scheduler.
+- Application threads never share a scheduler. If several application threads each use HiGHS, each gets its own scheduler and its own worker threads. They do not interfere with each other.


Better "If several application threads use HiGHS, each gets ..." or (possibly) "If each of several application threads uses HiGHS, each gets..." or

jajhall

I'm unable to create the documentation locally to see how it looks in a browser, but I've previewed the changes to partallel.md and solvers.md in GitHub.

Other than the couple of grammatical corrections, I thought that just presenting the general documentation for the scheduler might be intimidating for someone whose code is serial and they are simply calling run() for a single Highs instance. Perhaps there could be a documentation section explaining the use of the scheduler in this simplest (but common) special case.

filikat · 2026-10-21T17:11:34Z

Other than the couple of grammatical corrections, I thought that just presenting the general documentation for the scheduler might be intimidating for someone whose code is serial and they are simply calling run() for a single Highs instance. Perhaps there could be a documentation section explaining the use of the scheduler in this simplest (but common) special case.

Yes, it is indeed a bit daunting to see so many details.
I split the documentation in two. The first section is for the average user and it tells them that they don't need to do anything about the scheduler, apart from potentially choosing the number of threads. The second section is labelled as advanced, with a list of reasons why a user may be interested. I made the second section shorter, since it is intended only for advanced users, so we can use more advanced terminology.

fwesselm

Thanks, @filikat!

fwesselm · 2026-10-22T08:33:01Z

+
+- An **application thread** is any thread not created by HiGHS. A **worker thread** is created by HiGHS as part of a scheduler. The **owning thread** is the application thread that created a scheduler, and it participates in the parallel work.
+- The scheduler is `thread_local`. It is created lazily by the first `run()` or `presolve()` on an application thread, and is shared by all `Highs` instances used on that thread. It is never visible to other application threads.
+- A scheduler of size `N` consists of the owning thread and `N - 1` workers. `N` is fixed at creation, so later changes to the `threads` option have no effect until the scheduler is reset. The default is the number of physical cores in the process's CPU affinity mask.


... changes to the threads option have no effect ...

If threads is changed, doesn't the code print a log message and return an error?

fwesselm · 2026-10-22T08:34:11Z

    def readSolution(self, file_path: str, style: int) -> HighsStatus: ...
    @staticmethod
+    def resetThreadScheduler(blocking: bool) -> None: ...
    def resetGlobalScheduler(blocking: bool) -> None: ...


I think the line @staticmethod has be repeated for the resetGlobalScheduler?

jajhall · 2026-10-23T10:38:36Z

+
+All of this applies to the C API and to other languages as well.
+
+You only need the advanced section below if you run HiGHS from several threads of your own, or if you need to stop HiGHS's threads explicitly, for example before unloading a library.


HiGHS': no s after the apostrophe when a singular noun ends in "s"

Otherwise this is great!

I think we'll see the benefit of taking time over composing this documentation

filikat · 2026-10-23T11:13:12Z

Great.
Not sure if we want to merge it now and have it in the next release, or discuss this more at the next meeting.
@jajhall I leave the choice to you.

filikat added 9 commits October 19, 2026 13:20

Add scheduler documentation

908f4b6

Update docs

dcea327

Update c and cpp api comments about scheduler

5b945b5

Deprecate resetGlobalScheduler in favour of resetThreadScheduler

9ca8c7e

Update docs to resetThreadScheduler

ccf4d72

Update to resetThreadScheduler in python

93d6c97

Remove outdated test

4bcb28a

Add test to check that schedulers in different threads are independent

679556e

Change wording about callback

c203c4a

filikat requested review from Opt-Mucca, fwesselm, galabovaa and jajhall October 20, 2026 12:02

filikat self-assigned this Oct 20, 2026

filikat added Documentation Parallel labels Oct 20, 2026

Opt-Mucca approved these changes Oct 20, 2026

View reviewed changes

galabovaa approved these changes Oct 21, 2026

View reviewed changes

jajhall reviewed Oct 21, 2026

View reviewed changes

jajhall requested changes Oct 21, 2026

View reviewed changes

Split and shorten scheduler docs

5e6332e

fwesselm approved these changes Oct 22, 2026

View reviewed changes

Comments by Franz

53199ce

filikat requested a review from jajhall October 23, 2026 09:02

jajhall requested changes Oct 23, 2026

View reviewed changes

Apostrophe

b3e7094

filikat marked this pull request as ready for review October 23, 2026 11:10

jajhall merged commit dfbd76a into latest Oct 23, 2026
603 of 607 checks passed

jajhall deleted the parallel-docs branch October 23, 2026 13:46

Navigation Menu

Repository navigation

Parallel scheduler documentation - #3449

Parallel scheduler documentation#3449
jajhall merged 12 commits into
latestfrom
parallel-docs

filikat commented Oct 20, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Oct 20, 2026 •

edited

Loading

Uh oh!

Opt-Mucca left a comment

Uh oh!

galabovaa left a comment

Uh oh!

jajhall Oct 21, 2026

Uh oh!

jajhall Oct 21, 2026

Uh oh!

jajhall left a comment

Uh oh!

filikat commented Oct 21, 2026 •

edited

Loading

Uh oh!

fwesselm left a comment

Uh oh!

fwesselm Oct 22, 2026

Uh oh!

fwesselm Oct 22, 2026

Uh oh!

jajhall Oct 23, 2026 •

edited

Loading

Uh oh!

filikat commented Oct 23, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants


		All of this applies to the C API and to other languages as well.

		You only need the advanced section below if you run HiGHS from several threads of your own, or if you need to stop HiGHS's threads explicitly, for example before unloading a library.

Conversation

filikat commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

codecov Bot commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Opt-Mucca left a comment

Choose a reason for hiding this comment

Uh oh!

galabovaa left a comment

Choose a reason for hiding this comment

Uh oh!

jajhall Oct 21, 2026

Choose a reason for hiding this comment

Uh oh!

jajhall Oct 21, 2026

Choose a reason for hiding this comment

Uh oh!

jajhall left a comment

Choose a reason for hiding this comment

Uh oh!

filikat commented Oct 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fwesselm left a comment

Choose a reason for hiding this comment

Uh oh!

fwesselm Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

fwesselm Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

jajhall Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

filikat commented Oct 23, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

filikat commented Oct 20, 2026 •

edited

Loading

codecov Bot commented Oct 20, 2026 •

edited

Loading

filikat commented Oct 21, 2026 •

edited

Loading

jajhall Oct 23, 2026 •

edited

Loading