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.
13 entry points
Functions
Section titled “Functions”fznso_NAME_abi_version
Section titled “fznso_NAME_abi_version”extern "C" fn fznso_NAME_abi_version() -> u32sourceReport 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
Section titled “fznso_NAME_constraint_list”extern "C" fn fznso_NAME_constraint_list() -> fznso_types::FznsoConstraintList<'static>sourceReturns the list of available constraint that can be added to the solver.
The returned array must stay valid for as long as the library is loaded, so
it is static. The caller never frees it.
fznso_NAME_decision_list
Section titled “fznso_NAME_decision_list”extern "C" fn fznso_NAME_decision_list() -> fznso_types::FznsoTypeList<'static>sourceReturns the list of types for which decision variable can be created by the solver.
The returned array must stay valid for as long as the library is loaded, so
it is static. The caller never frees it.
fznso_NAME_objective_list
Section titled “fznso_NAME_objective_list”extern "C" fn fznso_NAME_objective_list() -> fznso_types::FznsoObjectiveList<'static>sourceReturns the list of available objective that can be achieved by the solver.
The returned array must stay valid for as long as the library is loaded, so
it is static. The caller never frees it.
fznso_NAME_option_list
Section titled “fznso_NAME_option_list”extern "C" fn fznso_NAME_option_list() -> fznso_types::FznsoOptionList<'static>sourceReturns the list of available options that can be set of the solver.
The returned array must stay valid for as long as the library is loaded, so
it is static. The caller never frees it.
fznso_NAME_solver_create
Section titled “fznso_NAME_solver_create”extern "C" fn fznso_NAME_solver_create() -> *mut fznso_types::FznsoSolversourceCreate a new solver instance
fznso_NAME_solver_free
Section titled “fznso_NAME_solver_free”unsafe extern "C" fn fznso_NAME_solver_free(solver: *mut fznso_types::FznsoSolver)sourceFree 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
Section titled “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
Section titled “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>sourceGet the current value of an option for the solver.
Note that this is only valid to be called with options named by
fznso_NAME_option_list.
The returned value must stay valid until the next call that can change the
solver (e.g. _solver_option_set, _solver_run, or _solver_free).
Returning a borrow of the solver’s own state is the intent; the caller never
frees it.
Safety
Section titled “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
Section titled “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<'_>) -> boolsourceSet the current value of an option for the solver.
Note that this is only valid to be called with options named by
fznso_NAME_option_list, and the value must be of the correct type. This
function returns true if the option was successfully set, and false
otherwise.
Safety
Section titled “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
Section titled “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<'_>))sourceRead an error message from the solver.
This function is expected to be called after solver interactions signal an
error has occurred. For example, if fznso_NAME_solver_run returns
FznsoStatus::FznsoError or fznso_NAME_solver_option_set returns
false.
The message is handed to read_error rather than returned, so it need only
stay valid for the duration of that callback.
Safety
Section titled “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
Section titled “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::FznsoStatussourceRun 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.dev/spec/running/ and
https://fznso.minizinc.dev/spec/threading/.
Safety
Section titled “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
Section titled “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>sourceGet the current value of a statistic from the solver instance.
Note that this is only valid to be called with statistics named by
fznso_NAME_statistic_list whose solver flag is set; statistics carrying
only the solution flag are read from a solution instead, 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
Section titled “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
Section titled “fznso_NAME_statistic_list”extern "C" fn fznso_NAME_statistic_list() -> fznso_types::FznsoStatisticList<'static>sourceReturns the list of available statistical information that can be requested from the solver and its solutions.
The returned array must stay valid for as long as the library is loaded, so
it is static. The caller never frees it.