ABI entry points

The thirteen entry points every solver exports, with the contract on each.

NAME is a placeholder: a real solver substitutes its own name, so these are fznso_gecode_solver_run and friends in a library named gecode. See Entry points for what each is for, and c/fznso_solver_template.c for the C template to copy.

Functions

fznso_NAME_abi_version

extern "C" fn fznso_NAME_abi_version() -> u32source

Report the FZnSO ABI version this solver was built against. A loader rejects the solver if this does not match its own.

fznso_NAME_constraint_list

extern "C" fn fznso_NAME_constraint_list() -> fznso_types::FznsoConstraintList<'static>source

Returns the constraints that can be posted to the solver.

The array is static: valid for as long as the library is loaded, and never freed by the caller.

fznso_NAME_decision_list

extern "C" fn fznso_NAME_decision_list() -> fznso_types::FznsoTypeList<'static>source

Returns the types for which the solver can create decision variables.

The array is static: valid for as long as the library is loaded, and never freed by the caller.

fznso_NAME_objective_list

extern "C" fn fznso_NAME_objective_list() -> fznso_types::FznsoObjectiveList<'static>source

Returns the objective strategies the solver can pursue.

The array is static: valid for as long as the library is loaded, and never freed by the caller.

fznso_NAME_option_list

extern "C" fn fznso_NAME_option_list() -> fznso_types::FznsoOptionList<'static>source

Returns the options that can be set on the solver.

The array is static: valid for as long as the library is loaded, and never freed by the caller.

fznso_NAME_solver_create

extern "C" fn fznso_NAME_solver_create() -> *mut fznso_types::FznsoSolversource

Create a new solver instance

fznso_NAME_solver_free

unsafe extern "C" fn fznso_NAME_solver_free(solver: *mut fznso_types::FznsoSolver)source

Free a solver instance, releasing all resources associated with it.

The pointer to the solver instance will be invalid after this function has been called.

Safety

solver must be a pointer returned by fznso_NAME_solver_create that has not yet been passed to this function.

fznso_NAME_solver_option_get

unsafe extern "C" fn fznso_NAME_solver_option_get<'a>(solver: fznso_types::FznsoPtr<'a, fznso_types::FznsoSolver>, ident: fznso_types::FznsoStr<'_>) -> fznso_types::FznsoValueRef<'a>

source

Get the current value of an option for the solver.

Only valid for options named by fznso_NAME_option_list.

The returned value must stay valid until the next call that can change the solver (_solver_option_set, _solver_run or _solver_free). Borrowing the solver’s own state is the intent; the caller never frees it.

Safety

solver must be a pointer returned by fznso_NAME_solver_create that has not yet been passed to fznso_NAME_solver_free.

fznso_NAME_solver_option_set

unsafe extern "C" fn fznso_NAME_solver_option_set(solver: *mut fznso_types::FznsoSolver, ident: fznso_types::FznsoStr<'_>, value: fznso_types::FznsoValueRef<'_>) -> bool

source

Set the current value of an option for the solver.

Only valid for options named by fznso_NAME_option_list, and the value must have the declared type. Returns true if the option was set, false otherwise; the reason is then available through fznso_NAME_solver_read_error.

Safety

solver must be a pointer returned by fznso_NAME_solver_create that has not yet been passed to fznso_NAME_solver_free.

fznso_NAME_solver_read_error

unsafe extern "C" fn fznso_NAME_solver_read_error(solver: *mut fznso_types::FznsoSolver, context: *mut ffi::c_void, read_error: extern "C" fn(context: *mut ffi::c_void, error: fznso_types::FznsoStr<'_>))

source

Read an error message from the solver.

Called after an interaction signals an error: fznso_NAME_solver_run returning FznsoStatus::FznsoError, or fznso_NAME_solver_option_set returning false.

The message is handed to read_error rather than returned, so it need only stay valid for the duration of that callback.

Safety

solver must be a pointer returned by fznso_NAME_solver_create that has not yet been passed to fznso_NAME_solver_free.

fznso_NAME_solver_run

unsafe extern "C" fn fznso_NAME_solver_run(solver: *mut fznso_types::FznsoSolver, model: fznso_types::FznsoModelRef<'_>, context: *mut ffi::c_void, on_solution: extern "C" fn(context: *mut ffi::c_void, solution: fznso_types::FznsoSolutionRef<'_>), on_message: Option<extern "C" fn(context: *mut ffi::c_void, scope: fznso_types::FznsoStr<'_>, value: fznso_types::FznsoValueRef<'_>)>, should_stop: Option<extern "C" fn(context: *mut ffi::c_void) -> bool>) -> fznso_types::FznsoStatus

source

Run the solver with the given model.

model is borrowed for the duration of this call and is read-only throughout. The solution passed to on_solution, and the scope and value passed to on_message, are likewise valid only for the duration of that one callback.

Both on_message and should_stop may be None, and the difference is worth honouring: None means nobody is listening and the caller will never cancel respectively, so a solver should skip building diagnostics and drop the poll from its search loop, rather than doing the work and discarding it.

Failures are not reported through on_message. Return FznsoStatus::FznsoError and make the reason available through fznso_NAME_solver_read_error.

The full contracts — when should_stop must be polled, and what a multi-threaded solver may do with the callbacks and the model — are specified once at https://fznso.minizinc.org/spec/running/ and https://fznso.minizinc.org/spec/threading/.

Safety

solver must be a pointer returned by fznso_NAME_solver_create that has not yet been passed to fznso_NAME_solver_free.

fznso_NAME_solver_statistic

unsafe extern "C" fn fznso_NAME_solver_statistic<'a>(solver: fznso_types::FznsoPtr<'a, fznso_types::FznsoSolver>, ident: fznso_types::FznsoStr<'_>) -> fznso_types::FznsoValueRef<'a>

source

Get the current value of a statistic from the solver instance.

Only valid for statistics named by fznso_NAME_statistic_list whose solver flag is set; those carrying only the solution flag are read from a solution, using FznsoSolutionMethods::statistic. An unknown identifier yields a value of kind FznsoValueAbsent.

As with _solver_option_get, the returned value must stay valid until the next call that can change the solver.

Safety

solver must be a pointer returned by fznso_NAME_solver_create that has not yet been passed to fznso_NAME_solver_free.

fznso_NAME_statistic_list

extern "C" fn fznso_NAME_statistic_list() -> fznso_types::FznsoStatisticList<'static>source

Returns the statistics that can be read from the solver and its solutions.

The array is static: valid for as long as the library is loaded, and never freed by the caller.