Feature/par search worker adjustments

.gitignore

@@ -111,5 +111,6 @@ test/test
 # Ignore build tree outputs (version metadata lives in top-level
 # gecode-version.m4).
 build/
+/results/
 CMakeUserPresets.json
 CMakePresets.json.user

CMakeLists.txt

@@ -1354,6 +1354,64 @@ if(GECODE_ENABLE_FLATZINC)
 endif()
 
 if(BUILD_TESTING)
+  unset(GECODE_CURRENT_META_HOOKS_COMPILE CACHE)
+  unset(GECODE_REMOVED_MASTER_HOOK_COMPILES CACHE)
+  unset(GECODE_REMOVED_SLAVE_HOOK_COMPILES CACHE)
+  set(GECODE_HAD_TRY_COMPILE_TARGET_TYPE FALSE)
+  if(DEFINED CMAKE_TRY_COMPILE_TARGET_TYPE)
+    set(GECODE_HAD_TRY_COMPILE_TARGET_TYPE TRUE)
+  endif()
+  set(GECODE_SAVED_TRY_COMPILE_TARGET_TYPE
+    "${CMAKE_TRY_COMPILE_TARGET_TYPE}")
+  set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)
+  try_compile(
+    GECODE_CURRENT_META_HOOKS_COMPILE
+    "${CMAKE_CURRENT_BINARY_DIR}/origin-variant-api-pass"
+    SOURCES
+      "${CMAKE_CURRENT_SOURCE_DIR}/test/search/origin-variant-api-pass.cpp"
+    CMAKE_FLAGS
+      "-DINCLUDE_DIRECTORIES=${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}"
+      "-DCMAKE_CXX_STANDARD=17"
+      "-DCMAKE_CXX_STANDARD_REQUIRED=ON")
+  if(NOT GECODE_CURRENT_META_HOOKS_COMPILE)
+    message(FATAL_ERROR
+      "Current origin/variant Space hooks do not compile")
+  endif()
+
+  try_compile(
+    GECODE_REMOVED_MASTER_HOOK_COMPILES
+    "${CMAKE_CURRENT_BINARY_DIR}/origin-variant-api-fail-master"
+    SOURCES
+      "${CMAKE_CURRENT_SOURCE_DIR}/test/search/origin-variant-api-fail.cpp"
+    COMPILE_DEFINITIONS
+      -DGECODE_TEST_REMOVED_MASTER
+    CMAKE_FLAGS
+      "-DINCLUDE_DIRECTORIES=${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}"
+      "-DCMAKE_CXX_STANDARD=17"
+      "-DCMAKE_CXX_STANDARD_REQUIRED=ON")
+  try_compile(
+    GECODE_REMOVED_SLAVE_HOOK_COMPILES
+    "${CMAKE_CURRENT_BINARY_DIR}/origin-variant-api-fail-slave"
+    SOURCES
+      "${CMAKE_CURRENT_SOURCE_DIR}/test/search/origin-variant-api-fail.cpp"
+    COMPILE_DEFINITIONS
+      -DGECODE_TEST_REMOVED_SLAVE
+    CMAKE_FLAGS
+      "-DINCLUDE_DIRECTORIES=${CMAKE_CURRENT_SOURCE_DIR};${CMAKE_CURRENT_BINARY_DIR}"
+      "-DCMAKE_CXX_STANDARD=17"
+      "-DCMAKE_CXX_STANDARD_REQUIRED=ON")
+  if(GECODE_REMOVED_MASTER_HOOK_COMPILES OR
+     GECODE_REMOVED_SLAVE_HOOK_COMPILES)
+    message(FATAL_ERROR
+      "Removed meta-search Space hooks unexpectedly compile")
+  endif()
+  if(GECODE_HAD_TRY_COMPILE_TARGET_TYPE)
+    set(CMAKE_TRY_COMPILE_TARGET_TYPE
+      "${GECODE_SAVED_TRY_COMPILE_TARGET_TYPE}")
+  else()
+    unset(CMAKE_TRY_COMPILE_TARGET_TYPE)
+  endif()
+
   set(GECODE_CAN_BUILD_TESTS TRUE)
   foreach(required search int minimodel driver)
     if(NOT TARGET gecode${required})
@@ -1399,6 +1457,13 @@ if(BUILD_TESTING)
       list(APPEND GECODE_TEST_LINK_LIBS gecodeflatzinc)
     endif()
     target_link_libraries(gecode-test PRIVATE ${GECODE_TEST_LINK_LIBS})
+    if(GECODE_ENABLE_THREAD)
+      add_executable(gecode-worker-control-benchmark EXCLUDE_FROM_ALL
+        test/benchmark-worker-control.cpp)
+      target_compile_features(gecode-worker-control-benchmark PRIVATE cxx_std_17)
+      target_link_libraries(gecode-worker-control-benchmark
+        PRIVATE gecodeminimodel)
+    endif()
     if(GECODE_ENABLE_FAULT_INJECTION)
       add_executable(gecode-fault-test EXCLUDE_FROM_ALL
         ${GECODE_FAULT_TEST_SOURCES})
@@ -1500,6 +1565,17 @@ if(BUILD_TESTING)
         ENVIRONMENT "${GECODE_TEST_BLACKBOX_ENV}")
     endif()
     set(GECODE_CHECK_DEPENDS gecode-test)
+    add_executable(gecode-verify-origin-variant-terminology EXCLUDE_FROM_ALL
+      test/search/verify-origin-variant-terminology.cpp)
+    target_compile_features(gecode-verify-origin-variant-terminology
+      PRIVATE cxx_std_17)
+    add_custom_target(verify-origin-variant-terminology
+      COMMAND $<TARGET_FILE:gecode-verify-origin-variant-terminology>
+        ${CMAKE_CURRENT_SOURCE_DIR}
+        ${CMAKE_CURRENT_SOURCE_DIR}/test/search/origin-variant-terminology.expected
+      DEPENDS gecode-verify-origin-variant-terminology
+      VERBATIM)
+    list(APPEND GECODE_CHECK_DEPENDS verify-origin-variant-terminology)
     if(GECODE_ENABLE_FLOAT_VARS)
       add_custom_target(verify-gecode-check-tests
         COMMAND ${CMAKE_COMMAND}

Makefile.in

@@ -266,10 +266,10 @@ SEARCHSRC0 = \
 	dfs bab lds \
 	seq/rbs seq/dead seq/pbs par/pbs \
 	rbs pbs nogoods exception tracer \
-	cpprofiler/tracer
+	cpprofiler/tracer worker-control
 SEARCHHDR0 = \
 	statistics.hpp stop.hpp options.hpp cutoff.hpp \
-	support.hh worker.hh exception.hpp engine.hpp base.hpp \
+	support.hh worker.hh worker-control.hh exception.hpp engine.hpp base.hpp \
 	nogoods.hh nogoods.hpp build.hpp traits.hpp sebs.hpp \
 	seq/path.hh seq/path.hpp seq/dfs.hh seq/dfs.hpp \
 	seq/bab.hh seq/bab.hpp seq/lds.hh seq/lds.hpp \
@@ -903,7 +903,7 @@ INTEXAMPLESRC0 =						\
 	word-square crossword open-shop car-sequencing sat      \
 	bin-packing knights tsp perfect-square schurs-lemma     \
 	dominating-queens colored-matrix multi-bin-packing	\
-	qcp job-shop
+	qcp job-shop origin-variant
 
 
 INTEXAMPLEHDR  = $(INTEXAMPLEHDR0:%=examples/%.hpp)
@@ -1267,7 +1267,8 @@ BRANCHTESTSRC0 = \
 	test/assign/set.cpp test/assign/float.cpp
 
 SEARCHTESTSRC0 = \
-	test/search.cpp test/nogoods.cpp
+	test/search.cpp test/nogoods.cpp \
+	test/search/origin-variant-api-pass.cpp
 
 ARRAYTESTSRC0 = \
 	test/array.cpp
@@ -1297,6 +1298,8 @@ TESTOBJ	= $(INTTESTOBJ) $(SETTESTOBJ) $(FLOATTESTOBJ) \
 	$(TESTSRC0:%.cpp=%$(OBJSUFFIX))
 TESTSBJ	= $(TESTOBJ:%$(OBJSUFFIX)=%$(SBJSUFFIX))
 TESTEXE	= test/test$(EXESUFFIX)
+ORIGINVARIANTTERMSRC = test/search/verify-origin-variant-terminology.cpp
+ORIGINVARIANTTERMEXE = test/search/verify-origin-variant-terminology$(EXESUFFIX)
 BLACKBOXEXECOBJ = $(BLACKBOXEXECSRC:%.cpp=%$(OBJSUFFIX))
 BLACKBOXDLLOBJ = $(BLACKBOXDLLSRC:%.cpp=%$(OBJSUFFIX))
 BLACKBOXEXEC = test/flatzinc/blackbox-exec$(EXESUFFIX)
@@ -1310,7 +1313,7 @@ BLACKBOXFIXTURES =
 endif
 
 TESTBUILDDIRS = \
-	test test/int test/set test/float \
+	test test/int test/set test/float test/search \
 	test/branch test/assign \
 	test/flatzinc
 
@@ -1387,7 +1390,21 @@ REQUIREDFLOATCHECKTESTS = Float::Arithmetic::PositiveNRootBounds \
 endif
 
 # A basic integrity test
-check: test
+check: test verify-origin-variant-terminology \
+		$(top_srcdir)/test/search/origin-variant-api-fail.cpp
+	@for hook in MASTER SLAVE; do \
+	  if $(CXX) $(CXXFLAGS) $(EXAMPLES_EXTRA_CXXFLAGS) \
+	      -DGECODE_TEST_REMOVED_$$hook \
+	      -I$(top_builddir) -I$(top_srcdir) -c \
+	      $(top_srcdir)/test/search/origin-variant-api-fail.cpp \
+	      -o test/search/origin-variant-api-fail$(OBJSUFFIX) \
+	      >/dev/null 2>&1; then \
+	    $(RMF) test/search/origin-variant-api-fail$(OBJSUFFIX); \
+	    echo "A removed meta-search Space hook unexpectedly compiles" >&2; \
+	    exit 1; \
+	  fi; \
+	  $(RMF) test/search/origin-variant-api-fail$(OBJSUFFIX); \
+	done
 	@for t in $(REQUIREDFLOATCHECKTESTS); do \
 		case " $(CHECKTESTS) " in *" $$t "*) ;; \
 		*) echo "Required Float check test is missing: $$t" >&2; exit 1 ;; \
@@ -1401,6 +1418,17 @@ check: test
 		$(TESTEXE) -iter 2 -threads 0 -fixprob 1 \
 		$(CHECKTESTS:%=-test %)
 
+.PHONY: verify-origin-variant-terminology
+verify-origin-variant-terminology: mkcompiledirs \
+		$(top_srcdir)/$(ORIGINVARIANTTERMSRC) \
+		$(top_srcdir)/test/search/origin-variant-terminology.expected
+	$(CXX) $(CXXFLAGS) $(EXAMPLES_EXTRA_CXXFLAGS) -std=c++17 \
+	  $(top_srcdir)/$(ORIGINVARIANTTERMSRC) \
+	  -o $(ORIGINVARIANTTERMEXE)
+	$(ORIGINVARIANTTERMEXE) \
+	  $(top_srcdir) \
+	  $(top_srcdir)/test/search/origin-variant-terminology.expected
+
 .PHONY: regenerate
 regenerate:
 	bash "$(top_srcdir)/.github/ci/generated-source-freshness.sh" --update
@@ -1978,6 +2006,7 @@ license.hh: $(ALLGECODEHDR:%=$(top_srcdir)/%) $(ALLSRC:%=$(top_srcdir)/%) \
 
 stat.hh: $(ALLGECODEHDR:%=$(top_srcdir)/%) $(ALLSRC:%=$(top_srcdir)/%) \
 	$(TESTHDR:%=$(top_srcdir)/%) $(TESTSRC:%=$(top_srcdir)/%) \
+	$(ORIGINVARIANTTERMSRC:%=$(top_srcdir)/%) \
 	$(VARIMPHDR)
 	$(UVRUN) $(top_srcdir)/misc/genstatistics.py $^ > stat.hh
 
@@ -2177,6 +2206,8 @@ clean:
 		$(EXAMPLEEXE:%=%.rc) $(EXAMPLEEXE:%=%.res)
 	$(RMF) $(TESTEXE:%.exe=%.pdb) $(TESTEXE:%=%.manifest) \
 		$(TESTEXE:%=%.rc) $(TESTEXE:%=%.res)
+	$(RMF) $(ORIGINVARIANTTERMEXE) \
+		$(ORIGINVARIANTTERMEXE:%.exe=%.pdb)
 	$(RMF) $(BLACKBOXEXEC:%.exe=%.pdb) $(BLACKBOXEXEC:%=%.manifest) \
 		$(BLACKBOXDLL:%$(DLLSUFFIX)=%$(LIBSUFFIX)) \
 		$(BLACKBOXDLL:%$(DLLSUFFIX)=%$(PDBSUFFIX)) \
@@ -2213,6 +2244,6 @@ depend: mkcompiledirs
 	$(top_srcdir) \
 	$(ALLSRC) \
 	$(FLATZINC_GENSRC) \
-	$(TESTSRC) > Makefile.dep
+	$(TESTSRC) $(ORIGINVARIANTTERMSRC) > Makefile.dep
 
 -include Makefile.dep

README.md

@@ -19,6 +19,11 @@ In particular,
 Gecode comes with
 [extensive tutorial and reference documentation](https://gecode.github.io/documentation.html).
 
+For source-level breaking changes, see the
+[Gecode 7 migration notes](docs/gecode-7-migration.md).
+The [adjustable-worker guide](docs/worker-control.md) describes external,
+asynchronous control of parallel-search worker allocation.
+
 ## CMake Build Options
 
 CMake exposes options aligned with the Autoconf build switches.

cmake/GecodeSources.cmake

@@ -48,6 +48,7 @@ set(GECODE_SEARCH_SOURCES
   gecode/search/seq/rbs.cpp
   gecode/search/stop.cpp
   gecode/search/tracer.cpp
+  gecode/search/worker-control.cpp
 )
 
 set(GECODE_INT_SOURCES
@@ -412,6 +413,7 @@ set(GECODE_TEST_SOURCES
   test/nogoods.cpp
   test/region.cpp
   test/search.cpp
+  test/search/origin-variant-api-pass.cpp
   test/set.cpp
   test/set/channel.cpp
   test/set/construct.cpp

docs/gecode-7-migration.md

@@ -0,0 +1,66 @@
+# Gecode 7 migration notes
+
+## Meta-search Space roles
+
+Gecode 7 names the two `Space` roles used by restart-based search (RBS) and
+portfolio-based search (PBS) **Origin** and **Variant**.
+The [Origin and Variant terminology contract](origin-variant-terminology.md)
+records the lifecycle and naming rationale behind these roles.
+
+An Origin is the persistent or common Space from which an exploration Space
+is derived. A Variant is the derived Space configured for one RBS restart
+episode or one PBS portfolio asset. These are logical roles. In RBS, the
+prepared object becomes the explored Variant while its clone becomes the next
+Origin.
+
+The same terms apply to both engines because both use the same derivation:
+prepare common state, derive an exploration Space, and specialize that Space.
+The callback contracts remain engine-specific. RBS uses the return values to
+control restart and completeness behavior, while PBS ignores them during
+one-time Origin and per-asset Variant configuration.
+
+Gecode 7 makes the following breaking override rename:
+
+```cpp
+// Gecode 6
+bool master(const Gecode::MetaInfo& mi) override;
+bool slave(const Gecode::MetaInfo& mi) override;
+
+// Gecode 7
+bool origin(const Gecode::MetaInfo& mi) override;
+bool variant(const Gecode::MetaInfo& mi) override;
+```
+
+There are no compatibility aliases. Keeping `override` on model hooks makes
+the compiler identify every model that still uses a Gecode 6 signature.
+The build-checked
+[Origin and Variant migration example](../examples/origin-variant.cpp)
+contains both current override declarations.
+
+The rename does not change callback timing or behavior:
+
+- RBS calls `origin` when persistent restart state is updated and calls
+  `variant` for each derived restart exploration.
+- PBS calls `origin` once before constructing assets and calls `variant` once
+  per asset, including the single-asset path.
+- The default RBS Origin behavior still constrains against the last solution,
+  posts no-goods, and requests a restart.
+- The default PBS Origin behavior still removes common branchers before
+  asset-specific branching is installed.
+- The default Variant behavior still performs no additional configuration and
+  returns `true`.
+
+Origin and Variant describe Spaces. They do not replace runtime terms such as
+portfolio coordinator, wrapped engine, or worker thread where those terms
+describe different objects.
+
+The [retained terminology inventory](origin-variant-terminology-inventory.md)
+classifies every remaining occurrence of the Gecode 6 role terms.
+
+## Adjustable parallel-search workers
+
+Gecode 7 can adjust the active worker request of a running DFS or BAB engine
+within a fixed initial capacity. The
+[worker-control contract](worker-control.md) documents construction,
+asynchronous resize semantics, parked-thread cost, handle lifetime, and the
+explicit per-asset controls used by PBS.

docs/origin-variant-terminology-inventory.md

@@ -0,0 +1,52 @@
+# Origin and Variant terminology inventory
+
+This inventory retains the result of a case-insensitive, whole-word scan for
+the two Gecode 6 meta-search role terms, including their plurals. The verifier
+walks the entire repository. It excludes only `.git/`, `.zd/`,
+`autom4te.cache/`, directories whose names begin with `build`, binary files,
+and the manifest itself. Root build files are therefore in scope.
+
+`test/search/verify-origin-variant-terminology.cpp` builds a standalone
+verifier for the Autoconf and CMake `check` targets. The occurrence-level
+manifest is
+[`test/search/origin-variant-terminology.expected`](../test/search/origin-variant-terminology.expected).
+Each tab-separated row records `path:line:column`, the exact spelling, a
+classification, and the escaped complete source line as its excerpt. Thus
+two terms on one line are two independently classified records. A new,
+removed, moved, respelled, or contextually changed occurrence fails the
+check.
+
+Run the exact checked scan through either build surface:
+
+```sh
+make verify-origin-variant-terminology
+cmake --build BUILD_DIRECTORY --target verify-origin-variant-terminology
+```
+
+To print the whole-repository occurrence list in manifest format, with each
+classification marked `UNCLASSIFIED`, run:
+
+```sh
+BUILD_DIRECTORY/bin/gecode-verify-origin-variant-terminology REPOSITORY_ROOT -
+```
+
+## Classification guide
+
+The manifest contains one row per occurrence. These groups explain why its
+classifications are retained:
+
+| Files | Classification |
+| --- | --- | --- |
+| `CMakeLists.txt`, `Makefile.in`, `test/search/origin-variant-api-fail.cpp` | Intentional negative API validation. The declarations must fail to compile. |
+| `examples/origin-variant.cpp`, `docs/gecode-7-migration.md` | Historical migration mapping. |
+| `docs/origin-variant-terminology.md` | Rejected terminology retained as design rationale. |
+| `changelog.in` | Historical release record, not current API documentation. |
+| `examples/scowl.hpp` | Third-party word-list data and licence. |
+| `examples/perfect-square.cpp` | Unrelated geometric domain language. |
+| `gecode/support/run-jobs.hpp` | Unrelated internal scheduler topology. |
+| `gecode/int/cumulative/tree.hpp` | Bibliographic title. |
+
+The checked scan contains no current RBS/PBS identifier or descriptive prose
+using either removed role term. A source change that adds one must either fix
+the stale terminology or update this inventory and the checked manifest with a
+specific unrelated or historical classification.