From 72b49bf140c9e93176250f0d2cdd84e88e4bc899 Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Thu, 9 Jul 2026 10:33:31 -0600 Subject: [PATCH] Deprecate legacy job scheduler The feature flag is renamed to legacy_sched_deprecated so any users get a signal - they will have to rename the flag once in their build, and will find out it will vanish in the next release. Manpage updated to show deprecation status, and flag name change. Signed-off-by: Mats Wichmann --- CHANGES.txt | 2 ++ RELEASE.txt | 7 +++++++ SCons/Script/SConsOptions.py | 3 ++- SCons/Taskmaster/Job.py | 15 +++++++++------ SCons/Taskmaster/JobTests.py | 6 +++--- doc/man/scons.xml | 29 ++++++++++++++++++++++++----- test/Interactive/taskmastertrace.py | 2 +- test/option/option--experimental.py | 8 ++++---- test/option/taskmastertrace.py | 4 ++-- 9 files changed, 54 insertions(+), 22 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index bfd3eb18a9..b991c5dd54 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -131,6 +131,8 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER - zip tool now uses zipfile module's "from_file" method to populate ZipInfo records, rather than doing manually. - Some cleanups in Subst.py. Functionality does not change. + - Deprecate the legacy job scheduler and feature flag. The feature flag + is renamed to "legacy_sched_deprecated". - Reference manual improvements: * More clarifications in Builder Methods section. * Clarify VariantDir behavior when switching from duplicate=True (the diff --git a/RELEASE.txt b/RELEASE.txt index 50438076cb..02565fa456 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -28,6 +28,13 @@ DEPRECATED FUNCTIONALITY - Deprecated using signature-file-per-directory (aka old-style SConsign) via the SConsignFile(name=None) call. +- The legacy job scheduler, which was superseded by a new scheduler in + SCons 4.7 but remained available as a fallback, is deprecated and + will be removed in the next release. The --experimental feature flag + to select the legacy scheduler is renamed to "legacy_sched_deprecated" + to give a clear indication of the status change; the flag will also + be removed in the next release. + REMOVED FUNCTIONALITY --------------------- diff --git a/SCons/Script/SConsOptions.py b/SCons/Script/SConsOptions.py index 74949c0599..b6b23782d1 100644 --- a/SCons/Script/SConsOptions.py +++ b/SCons/Script/SConsOptions.py @@ -42,7 +42,8 @@ diskcheck_all = SCons.Node.FS.diskcheck_types() -experimental_features = {'warp_speed', 'transporter', 'ninja', 'legacy_sched'} +# legacy_sched renamed legacy_sched_deprecated in 4.11, scheduled for removal +experimental_features = {'warp_speed', 'transporter', 'ninja', 'legacy_sched_deprecated'} def diskcheck_convert(value): diff --git a/SCons/Taskmaster/Job.py b/SCons/Taskmaster/Job.py index a24742ed65..b538b27490 100644 --- a/SCons/Taskmaster/Job.py +++ b/SCons/Taskmaster/Job.py @@ -72,12 +72,15 @@ class Jobs: """ def __init__(self, num, taskmaster) -> None: - """ - Create 'num' jobs using the given taskmaster. The exact implementation - used varies with the number of jobs requested and the state of the `legacy_sched` flag - to `--experimental`. - """ + """Create *num* jobs using the given taskmaster. + The exact implementation used varies with the number of jobs + requested and the scheduler selected - the old scheduler is + available through CLI ``--experimental=legacy_sched_deprecated``. + + .. versionchanged: NEXT_RELEASE + Legacy scheduler deprecated, flag renamed to ``legacy_sched_deprecated`` + """ # Importing GetOption here instead of at top of file to avoid # circular imports # pylint: disable=import-outside-toplevel @@ -88,7 +91,7 @@ def __init__(self, num, taskmaster) -> None: stack_size = default_stack_size experimental_option = GetOption('experimental') or [] - if 'legacy_sched' in experimental_option: + if 'legacy_sched_deprecated' in experimental_option: if num > 1: self.job = LegacyParallel(taskmaster, num, stack_size) else: diff --git a/SCons/Taskmaster/JobTests.py b/SCons/Taskmaster/JobTests.py index 59cfe78adc..93d1ce0254 100644 --- a/SCons/Taskmaster/JobTests.py +++ b/SCons/Taskmaster/JobTests.py @@ -313,7 +313,7 @@ def get(self): try: taskmaster = Taskmaster(3, self, SleepTask) - OptionsParser.values.experimental.append('legacy_sched') + OptionsParser.values.experimental.append('legacy_sched_deprecated') jobs = SCons.Taskmaster.Job.Jobs(2, taskmaster) OptionsParser.values.experimental.pop() jobs.run() @@ -529,7 +529,7 @@ def runTest(self) -> None: self._test_seq(1) # Now run test with LegacyParallel - OptionsParser.values.experimental=['legacy_sched'] + OptionsParser.values.experimental=['legacy_sched_deprecated'] self._test_seq(1) class ParallelTaskTest(_SConsTaskTest): @@ -538,7 +538,7 @@ def runTest(self) -> None: self._test_seq(num_jobs) # Now run test with LegacyParallel - OptionsParser.values.experimental=['legacy_sched'] + OptionsParser.values.experimental=['legacy_sched_deprecated'] self._test_seq(num_jobs) diff --git a/doc/man/scons.xml b/doc/man/scons.xml index a689960bac..1d2d3b2324 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -1258,14 +1258,33 @@ the mechanisms in the specified order. the special tokens all or none. A comma-separated string can be used to select multiple features. The default setting is none. - Current available features are: - ninja (New in version 4.2), - legacy_sched (New in version 4.6.0). + + Current available features are + ninja (new in version 4.2) + and + legacy_sched_deprecated + (new in, and deprecated since, version NEXT_RELEASE). + + + The legacy scheduler is not strictly an experimental feature. + The feature flag selects the job scheduler which was + the &SCons; default prior to version 4.7. + The feature flag was introduced as legacy_sched + in version 4.7. + The legacy scheduler is due to be removed in a future release, + so the feature flag is now deprecated. In version NEXT_RELEASE, + it was renamed to legacy_sched_deprecated, + so that existing users will receive a signal - due to the nature + of experimental feature flags it is not possible to use the + standard &SCons; deprecation warning mechanism here. + - No Support offered for any features or tools enabled by this flag. + Experimental features come with no compatibility promises - + a given feature could change significantly in a future release, + or disappear completely. - New in version 4.2 (experimental). + Option added in version 4.2. diff --git a/test/Interactive/taskmastertrace.py b/test/Interactive/taskmastertrace.py index c7196f6e84..6066fe10a2 100644 --- a/test/Interactive/taskmastertrace.py +++ b/test/Interactive/taskmastertrace.py @@ -46,7 +46,7 @@ test.write('foo.in', "foo.in 1\n") -scons = test.start(arguments = '-Q --interactive --experimental=legacy_sched') +scons = test.start(arguments = '-Q --interactive --experimental=legacy_sched_deprecated') scons.send("build foo.out 1\n") diff --git a/test/option/option--experimental.py b/test/option/option--experimental.py index 2b1bda53c2..d17d1aaf38 100755 --- a/test/option/option--experimental.py +++ b/test/option/option--experimental.py @@ -36,13 +36,13 @@ tests = [ ('.', []), ('--experimental=ninja', ['ninja']), - ('--experimental=legacy_sched', ['legacy_sched']), - ('--experimental=all', ['legacy_sched', 'ninja', 'transporter', 'warp_speed']), + ('--experimental=legacy_sched_deprecated', ['legacy_sched_deprecated']), + ('--experimental=all', ['legacy_sched_deprecated', 'ninja', 'transporter', 'warp_speed']), ('--experimental=none', []), ] for args, exper in tests: - read_string = """All Features=legacy_sched,ninja,transporter,warp_speed + read_string = """All Features=legacy_sched_deprecated,ninja,transporter,warp_speed Experimental=%s """ % (exper) test.run(arguments=args, @@ -51,7 +51,7 @@ test.run(arguments='--experimental=warp_drive', stderr="""usage: scons [OPTIONS] [VARIABLES] [TARGETS] -SCons Error: option --experimental: invalid choice: 'warp_drive' (choose from 'all','none','legacy_sched','ninja','transporter','warp_speed') +SCons Error: option --experimental: invalid choice: 'warp_drive' (choose from 'all','none','legacy_sched_deprecated','ninja','transporter','warp_speed') """, status=2) diff --git a/test/option/taskmastertrace.py b/test/option/taskmastertrace.py index 5b1047bbec..223ca011cc 100755 --- a/test/option/taskmastertrace.py +++ b/test/option/taskmastertrace.py @@ -42,7 +42,7 @@ expect_stdout = test.wrap_stdout(test.read('taskmaster_expected_stdout_1.txt', mode='r')) -test.run(arguments='--experimental=legacy_sched --taskmastertrace=- .', stdout=expect_stdout) +test.run(arguments='--experimental=legacy_sched_deprecated --taskmastertrace=- .', stdout=expect_stdout) test.run(arguments='-c .') @@ -52,7 +52,7 @@ """) # Test LegacyParallel Job implementation -test.run(arguments='--experimental=legacy_sched --taskmastertrace=trace.out .', stdout=expect_stdout) +test.run(arguments='--experimental=legacy_sched_deprecated --taskmastertrace=trace.out .', stdout=expect_stdout) test.must_match_file('trace.out', 'taskmaster_expected_file_1.txt', mode='r') # Test NewParallel Job implementation