Skip to content

Add MiniZinc black-box propagator support#219

Merged
zayenz merged 14 commits into
Gecode:mainfrom
Dekker1:feat/blackbox
Jul 13, 2026
Merged

Add MiniZinc black-box propagator support#219
zayenz merged 14 commits into
Gecode:mainfrom
Dekker1:feat/blackbox

Conversation

@Dekker1

@Dekker1 Dekker1 commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

This PR adds support in Gecode’s FlatZinc interpreter for MiniZinc’s experimental black-box propagator interface. Models can delegate value propagation or bounds filtering to a shared library through blackbox_dll, or to a persistent subprocess through blackbox_exec.

The implementation contains:

  • value and bounds propagators for integer and floating-point variables;
  • reason-based rescheduling for bounds filtering;
  • a shared-library ABI with optional initialization, cloning, and cleanup;
  • a line-based protocol for executable backends;
  • independent callback instances and process sessions for parallel search;
  • POSIX and Windows implementations with explicit resource cleanup; and
  • CMake and Autoconf integration tests covering concurrency, malformed data, protocol errors, and backend failures.

The interface is described in Defining Propagators in MiniZinc, by Jip J. Dekker, Peter J. Stuckey, Guido Tack, Huu Quang Tran, and Markus Wagner, presented at ModRef 2026.

@greptile-apps greptile-apps Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your trial has ended. Reactivate Greptile to resume code reviews.

@kalvdans

kalvdans commented Jul 8, 2026

Copy link
Copy Markdown

Please document both the DLL interface functions and the external process protocol, so reviewers can review that the PR adheres to the specification, and so that people can write their own conforming black boxes.

@Dekker1

Dekker1 commented Jul 8, 2026

Copy link
Copy Markdown
Contributor Author

Please document both the DLL interface functions and the external process protocol, so reviewers can review that the PR adheres to the specification, and so that people can write their own conforming black boxes.

The documentation for the ABI and executable streaming format will be part of the MiniZinc documentation.

@kalvdans

kalvdans commented Jul 8, 2026

Copy link
Copy Markdown

The documentation for the ABI and executable streaming format will be part of the MiniZinc documentation.

Great! Do you have a link to it?

@Dekker1

Dekker1 commented Jul 8, 2026

Copy link
Copy Markdown
Contributor Author

You can have a look at the current draft in my fork: https://github.com/Dekker1/libminizinc/blob/feat/blackbox/docs/en/blackbox.rst

@kalvdans

kalvdans commented Jul 8, 2026

Copy link
Copy Markdown

You can have a look at the current draft in my fork: https://github.com/Dekker1/libminizinc/blob/feat/blackbox/docs/en/blackbox.rst

Thanks! Looks well documented. Perhaps mention whether fzn_blackbox function must be threadsafe, and there's a descrepancy who decides the number of output values; in the API it is the caller, in the streaming interface it is the black box.

@Dekker1

Dekker1 commented Jul 8, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the feedback, I've updated the documentation with notes on these points. Regarding the seeming discrepancy, it should be noted that the fzn_blackbox constraint call always declares the amount of expected outputs, so if the stream contains a different amount of return values, this should generally be a runtime error.

@Dekker1

Dekker1 commented Jul 8, 2026

Copy link
Copy Markdown
Contributor Author

I just pushed a small update to avoid an additional allocation for each propagate call (using int64_t directly) that I discovered working on the Chuffed implementation. This was a left-over from a previous version of the ABI where we used int. I'd updated the ABI connection, but not the internal run methods.

@Dekker1

Dekker1 commented Jul 9, 2026

Copy link
Copy Markdown
Contributor Author

I found and fixed a typo. The new autoconf build failure appears to be unrelated to the change. Diagnosis from an agent is that the autoconf is missing a dependency that might be solved by adding:

$(FLATZINCSRC:%.cpp=%$(OBJSUFFIX)): $(VARIMPHDR)
$(FLATZINCSRC:%.cpp=%$(SBJSUFFIX)): $(VARIMPHDR)

Dekker1 and others added 8 commits July 12, 2026 13:10
Strengthen blackbox propagation, ownership, disposal, and error handling around external backends.
Add the MiniZinc annotations, use platform-neutral backend naming, and separate process startup paths and library fallback handling.
Validate protocol data and posting rules, document the callback contract, and integrate generated-header dependencies with Autoconf.
Reuse model-local backends while giving concurrent workers independent callback instances or persistent process sessions.
Use controlled posix_spawn setup, explicit descriptor inheritance, process groups, and bounded teardown.
Harden Windows handle and job-object management and adopt the fixed-width, instance-based shared-library ABI.
Exercise native process and library backends across CMake and Autoconf, including concurrency, malformed responses, portability, and diagnostics.
@zayenz zayenz changed the title Add support for the experimental MiniZinc black-box propagator interface Add MiniZinc black-box propagator support Jul 13, 2026
@zayenz
zayenz merged commit 545fa33 into Gecode:main Jul 13, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants