feat: add first draft of the protocol

.gitignore

···
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+target/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+
+# RustRover
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

Cargo.toml

···
+[workspace]
+
+members = ["crates/ipdos_protocol"]
+
+resolver = "2"
+
+[workspace.package]
+repository = "https://tangled.sh/@dekker.one/ipdos"
+version = "0.1.0"
+authors = ["Jip J. Dekker <[e-mail]>"]
+edition = "2024"
+license = ""
+
+[workspace.lints.rust]
+missing_debug_implementations = "warn"
+missing_docs = "warn"
+non_ascii_idents = "deny"
+trivial_casts = "warn"
+trivial_numeric_casts = "warn"
+unit_bindings = "warn"
+# unnameable_types = "warn"
+unreachable_pub = "warn"
+unused_crate_dependencies = "deny"
+unused_import_braces = "warn"
+unused_lifetimes = "warn"
+unused_macro_rules = "warn"
+unused_qualifications = "warn"
+unused_results = "warn"
+variant_size_differences = "warn"
+
+[workspace.lints.clippy]
+allow_attributes_without_reason = "deny"
+# cargo_common_metadata = "warn"
+clone_on_ref_ptr = "warn"
+default_union_representation = "deny"
+missing_docs_in_private_items = "warn"
+mixed_read_write_in_expression = "deny"
+# multiple_crate_versions = "warn"
+negative_feature_names = "deny"
+rc_buffer = "warn"
+rc_mutex = "warn"
+redundant_feature_names = "warn"
+redundant_type_annotations = "warn"
+rest_pat_in_fully_bound_structs = "warn"
+# same_name_method = "warn"
+semicolon_if_nothing_returned = "warn"
+str_to_string = "warn"
+string_add = "warn"
+string_add_assign = "warn"
+string_lit_chars_any = "warn"
+string_to_string = "warn"
+tests_outside_test_module = "warn"
+try_err = "warn"
+undocumented_unsafe_blocks = "warn"
+unnecessary_safety_comment = "warn"
+unseparated_literal_suffix = "warn"
+unnecessary_safety_doc = "warn"
+wildcard_dependencies = "warn"
+wrong_self_convention = "warn"

README.md

···
+# IPDOS: An Incremental Protocol for Decision and Optimization Solvers
+
+## Introduction
+
+## Common Functionality
+
+Although solvers are able to define their own functionality using the IPDOS protocol, we advocate for the following common functionality to be implemented by different solvers.
+This will allow for a more consistent user experience when interacting with different solvers.
+Even if a solver does not implement all of these functions, we recommend that the solvers do not use the same name for different functionality.
+
+### Common Options
+
+A solver will expose its available options through `ipdos_option_list`.
+We recommend that solvers eagerly implement the following options:
+
+- `all_optimal` (`bool`, default: `false`): If set to `true`, the solver will after finding an optimal solution, continue to search for other solutions with the same objective value.
+- `fixed_search` (`bool`, default: `false`): If set to `true`, the solver will strictly follow the search order defined by the user.
+- `intermediate` (`bool`, default: `false`): If set to `true` for a problem with an objective strategy set, the solver will trigger its `on_solution` callback when it finds an intermediate solution.
+  Afterward, the solver will continue the search until it finds the next solution, or it proves that no better solutions exist (returning the `IpdosComplete` status).
+- `threads` (`int`, default: `1`): For multithreaded solvers, this option will set the number of threads to use.
+- `time_limit` (`int`, default: `-1`): If set to a positive integer, the solver will abandon the search after the specified number of milliseconds.
+- `random_seed` (`opt int`, default: `<>`): If set to a positive integer, the solver will use the given value as the seed for its random number generator.
+  Solvers are encouraged to use a variable seed for the default value.
+- `verbose` (`bool`, default: `false`): If set to `true`, the solver will print additional information about its process to `stderr`.
+
+### Common Constraints
+
+A solver will expose the constraints that can be used in a `IpdosModel` through `ipdos_constraint_list`.
+We encourage solvers to support the constraints using the names and definitions from the [FlatZinc Builtins](https://docs.minizinc.dev/en/stable/lib-flatzinc.html).
+Other MiniZinc (global) constraints are also encouraged to be implemented, using the `fzn_` prefix.
+
+### Common Objective Strategies
+
+A solver will expose the objective strategies that can be used in a `IpdosModel` through `ipdos_objective_list`.
+We encourage solvers to support the following objective strategies if possible:
+
+- `lex_maximize_int` (`list of var int`) | `lex_maximize_float` (`list of var float`): The solver will maximize the list of decision variables in lexicographical order, i.e., the first variable is maximized first, then the second variable, etc.
+- `lex_minimize_int` (`list of var int`) | `lex_minimize_float` (`list of var float`): The solver will minimize the list of decision variables in lexicographical order, i.e., the first variable is minimized first, then the second variable, etc.
+- `maximize_int` (`var int`) | `maximize_float` (`var float`): The solver will maximize the given decision variable.
+- `minimize_int` (`var int`) | `minimize_float` (`var float`): The solver will minimize the given decision variable.
+- `pareto_maximize_int` (`list of var int`) | `pareto_maximize_float` (`list of
+var float`): The solver will output solutions where at least one decision variable is assigned a higher value than it was assigned in all previous solutions.
+
+Note that if no objective is set, then the solver is expected to find any valid assignment of the decision variables that satisfies the constraints added to the solver.

codebook.toml

···
+words = ["ipdos"]

crates/ipdos_protocol/.gitignore

···
+/target

crates/ipdos_protocol/Cargo.toml

···
+[package]
+name = "ipdos_protocol"
+repository.workspace = true
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+
+[lints]
+workspace = true

crates/ipdos_protocol/cbindgen.toml

···
+language = "C"
+
+# Wrapping header contents
+include_guard = "ipdos_protocol_h"
+documentation_style = "c99"

crates/ipdos_protocol/ipdos_protocol.h

···
+#ifndef ipdos_protocol_h
+#define ipdos_protocol_h
+
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+
+// The status returned by `ipdos_solver_run`, indicating whether the solver
+// completed its search.
+typedef enum IpdosStatus {
+  // The solver explored the full search space and yielded all relevant
+  // solutions.
+  IpdosComplete,
+  // The solver did not explore the full search space due to a timeout or
+  // other termination condition. Additional (better) solutions might be
+  // possible.
+  IpdosIncomplete,
+  // An error occurred during the solver's execution.
+  //
+  // `ipdos_solver_read_error` can be used to retrieve the error message.
+  IpdosError,
+} IpdosStatus;
+
+// Representation of the base type of a value.
+typedef enum IpdosTypeBase {
+  // Boolean type
+  IpdosTypeBaseBool,
+  // Integer numeric type
+  IpdosTypeBaseInt,
+  // Floating point numeric type
+  IpdosTypeBaseFloat,
+  // Character string type
+  IpdosTypeBaseString,
+} IpdosTypeBase;
+
+// Enumerated type used to mark the kind of [`IpdosValue`]. This is used to
+// determine which field in the [`IpdosValueContent`] union to access.
+typedef enum IpdosValueKind {
+  // No value is stored.
+  IpdosValueAbsent,
+  // The value is stored in `decision_index`.
+  IpdosValueDecision,
+  // The value is stored in `boolean_value`.
+  IpdosValueBoolean,
+  // The value is stored in `integer_value`.
+  IpdosValueInteger,
+  // The value is stored in `float_value`.
+  IpdosValueFloat,
+  // The value is stored in `string_value`.
+  IpdosValueString,
+  // The value is stored in `list_value`.
+  IpdosValueList,
+} IpdosValueKind;
+
+// Representation of a type to signal and check whether an argument takes the
+// correct type.
+typedef struct IpdosType {
+  // Whether the type is a list of values.
+  bool list_of;
+  // Whether the argument can be or contain decision variables (represented as
+  // decision indexes).
+  bool decision;
+  // Whether expected type is an set of values of the base type.
+  bool set_of;
+  // The expected base type of the argument.
+  enum IpdosTypeBase base;
+} IpdosType;
+
+// Representation of a type of constraint, discerned by its identifier and the
+// types of its arguments.
+typedef struct IpdosConstraintType {
+  // The identifier of the constraint type.
+  const char *ident;
+  // The number of expected arguments for the constraint type.
+  uintptr_t arg_len;
+  // The types of the expected arguments for the constraint type.
+  const struct IpdosType *arg_types;
+} IpdosConstraintType;
+
+// A list of [`IpdosConstraintType`]s.
+//
+// This type is for example used to return from [`ipdos_constraint_list`].
+typedef struct IpdosConstraintList {
+  // The number of elements in the `constraints` array.
+  uintptr_t len;
+  // An array of constraint types.
+  const struct IpdosConstraintType *constraints;
+} IpdosConstraintList;
+
+// A list of [`IpdosType`]s.
+//
+// This type is for example used to return from [`ipdos_decision_list`].
+typedef struct IpdosTypeList {
+  // The number of elements in the `constraints` array.
+  uintptr_t len;
+  // An array of constraint types.
+  const struct IpdosType *types;
+} IpdosTypeList;
+
+// Representation of a type of objective strategies, discerned by its
+// identifier and the type of its argument.
+typedef struct IpdosObjective {
+  // The identifier of the objective type.
+  const char *ident;
+  // The type of the expected argument for the constraint type.
+  struct IpdosType arg_type;
+} IpdosObjective;
+
+// A list of [`IpdosObjective`]s.
+//
+// This type is, for example, used to return from [`ipdos_objective_list`].
+typedef struct IpdosObjectiveList {
+  // The number of elements in the `options` array.
+  uintptr_t len;
+  // An array of option definitions.
+  const struct IpdosObjective *options;
+} IpdosObjectiveList;
+
+// The storage of the value content of a [`IpdosValue`].
+typedef union IpdosValueContent {
+  // Decision index storage
+  uintptr_t decision_index;
+  // Boolean value storage
+  bool bool_value;
+  // Integer value storage
+  int64_t integer_value;
+  // Float value storage
+  double float_value;
+  // Set of integers value storage
+  //
+  // The set of integers is represented using a range list. The array of
+  // `i64` values should be interpreted as a list of inclusive ranges,
+  // where each range is represented by two values.
+  //
+  // Note that the number of `i64` values is stored in the `len` field. Since
+  // each range is represented by two values, it can be assumed that `len mod
+  // 2 == 0`.
+  const int64_t *set_of_int_value;
+  // Set of floating point value storage
+  //
+  // The set of floating point values is represented using a range list. The
+  // array of `f64` values should be interpreted as a list of inclusive
+  // ranges, where each range is represented by two values.
+  //
+  // Note that the number of `f64` values is stored in the `len` field. Since
+  // each range is represented by two values, it can be assumed that `len mod
+  // 2 == 0`.
+  const int64_t *set_of_float_value;
+  // String value storage
+  //
+  // Note that the `string_value` field is intended to be interpreted as a
+  // C-string. It should be \0 terminated, use UTF-8 encoding, and be valid
+  // for the lifetime of the value.
+  const char *string_value;
+  // List value storage
+  //
+  // Note that the the number of elements in the list is stored in the `len`
+  // field.
+  const struct IpdosValue *list_value;
+} IpdosValueContent;
+
+// The value representation used for values assigned to decision variables in
+// solution, as constraint/annotation arguments, and option parameters.
+typedef struct IpdosValue {
+  // The kind of the value
+  //
+  // This field is used to determine what field in the `value` union is
+  // allowed to be accessed.
+  enum IpdosValueKind kind;
+  // A field containing the size of the value.
+  //
+  // This field is used when the value is a list, set of float/int, and
+  // string, to determine the number of elements in the C array type.
+  uint32_t len;
+  // The storage of the actual data of the value.
+  union IpdosValueContent content;
+} IpdosValue;
+
+// The definition of an option that is available to be set for the solver.
+typedef struct IpdosOption {
+  // The identifier used to set the option or get the current value of the option.
+  const char *ident;
+  // The type of value that is expected for this option.
+  struct IpdosValue arg_ty;
+  // The default value for this option.
+  struct IpdosType arg_def;
+} IpdosOption;
+
+// A list of [`IpdosOption`]s.
+//
+// This type is, for example, used to return from [`ipdos_option_list`].
+typedef struct IpdosOptionList {
+  // The number of elements in the `options` array.
+  uintptr_t len;
+  // An array of option definitions.
+  const struct IpdosOption *options;
+} IpdosOptionList;
+
+// The handle to a solver instance.
+//
+// This type is opaque to the user. Only pointers of this type are ever used.
+//
+// In implementation of the IPDOS interface, a pointer is generally cast to
+// this type, i.e. `(IpdosSolver*) my_solver`. A similar cast can be used to
+// cast the pointer back to the original type, e.g. `(MySolverType*)
+// ipdos_solver`.
+typedef void IpdosSolver;
+
+// The handle to a the data of a model instance.
+//
+// This type is opaque to the user. Only pointers of this type are ever used.
+//
+// In implementation of the IPDOS interface, a pointer is generally cast to
+// this type, i.e. `(IpdosModelData*) my_model`. A similar cast can be used to
+// cast the pointer back to the original type, e.g. `(MyModel*) ipdos_model`.
+typedef void IpdosModelData;
+
+// An interface to a model instance used to communicate with the solver.
+//
+// The solver can use the included function callbacks to interact with the
+// model.
+typedef struct IpdosModel {
+  // The handle to the data of the model instance.
+  //
+  // This handle is passed to all the different function callbacks to
+  // interact with the model.
+  const IpdosModelData *data;
+  // Returns the current number of model layers currently contained in the
+  // model.
+  //
+  // Note that it is required that the solver calls [`ipdos_solver_push`] and
+  // [`ipdos_solver_pop`] whenever a layer is added or removed.
+  uintptr_t (*layers)(const IpdosModelData *model);
+  // Retrieve the number of constraints currently contained in the model.
+  uintptr_t (*constraint_len)(const IpdosModelData *model);
+  // Retrieve the constraint index of the first new constraint in the layer.
+  //
+  // This can be equivalent to `constraint_len` if the layer does not add any
+  // new constraints.
+  uintptr_t (*constraint_layer_start)(const IpdosModelData *model);
+  // Retrieve the identifier of a constraint.
+  //
+  // The returned pointer can be assumed to have the the same lifetime as the
+  // constraint reference and must be valid UTF8.
+  const char *(*constraint_ident)(const IpdosModelData *model, uintptr_t constraint);
+  // Retrieve the number of arguments of a constraint.
+  uintptr_t (*constraint_argument_len)(const IpdosModelData *model, uintptr_t constraint);
+  // Retrieve the value of the constraint's argument at the given index.
+  //
+  // The `index` argument must be less than the value returned by
+  // `constraint_argument_len` for the given constraint.
+  struct IpdosValue (*constraint_argument)(const IpdosModelData *model,
+                                           uintptr_t constraint,
+                                           uintptr_t index);
+  // Retrieve the number of decisions currently contained in the model.
+  uintptr_t (*decision_len)(const IpdosModelData *model);
+  // Retrieve the decision index of the first new decision in the layer.
+  //
+  // This can be equivalent to `decision_len` if the layer does not add any
+  // new decisions.
+  uintptr_t (*decision_layer_start)(const IpdosModelData *model);
+  // Retrieve the domain of the given decision.
+  //
+  // Note that the the value might have [`IpdosValueKind::IpdosValueAbsent`] if
+  // the decision variable does not have an explicit domain.
+  struct IpdosValue (*decision_domain)(const IpdosModelData *model, uintptr_t decision);
+  // Retrieve the name of a decision variable, if it exists.
+  //
+  // Note that names are only available for debugging purposes. Decisions are
+  // identified using their index in the model. If the decision variable does
+  // not have a name, this function returns a null pointer.
+  const char *(*decision_name)(const IpdosModelData *model, uintptr_t decision);
+  // Check whether the decision variable is functionally defined by a
+  // constraint.
+  bool (*decision_defined)(const IpdosModelData *model, uintptr_t decision);
+  // Request the identifier of the type of objective strategy to be used when
+  // solving the model.
+  //
+  // Note that the function can return a null pointer if the model does not
+  // have an objective strategy.
+  const char *(*objective_ident)(const IpdosModelData *model);
+  // Retrieve the argument of the objective strategy.
+  struct IpdosValue (*objective_arg)(const IpdosModelData *model);
+} IpdosModel;
+
+// The handle to a the data of a solution instance.
+//
+// This type is opaque to the user. Only pointers of this type are ever used.
+//
+// In implementation of the IPDOS interface, a pointer is generally cast to
+// this type, i.e. `(IpdosSolutionData*) my_solution`. A similar cast can be
+// used to cast the pointer back to the original type, e.g. `(MySolution*)
+// ipdos_solution`.
+typedef void IpdosSolutionData;
+
+// Structure used to represent a solution emitted by the solver.
+//
+// The caller can use the `get_value` function to retrieve the value of the
+// used decision variables.
+typedef struct IpdosSolution {
+  // The data pointer to be the first argument of `get_value`.
+  const IpdosSolutionData *data;
+  // Function callback to retrieve the value assigned to a decision variable
+  // in the solution.
+  struct IpdosValue (*get_value)(const IpdosSolutionData *data, uintptr_t decision_index);
+} IpdosSolution;
+
+// Returns the list of available constraint that can be added to the solver.
+struct IpdosConstraintList ipdos_constraint_list(void);
+
+// Returns the list of types for which decision variable can be created by the
+// solver.
+struct IpdosTypeList ipdos_decision_list(void);
+
+// Returns the list of available objective that can be achieved by the solver.
+struct IpdosObjectiveList ipdos_objective_list(void);
+
+// Returns the list of available options that can be set of the solver.
+struct IpdosOptionList ipdos_option_list(void);
+
+// Create a new solver instance
+IpdosSolver *ipdos_solver_create(void);
+
+// 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.
+void ipdos_solver_free(IpdosSolver *solver);
+
+// Get the current value of an option for the solver.
+//
+// Note that this is only valid to be called with options named by
+// `ipdos_option_list`.
+struct IpdosValue ipdos_solver_option_get(const IpdosSolver *solver, const char *ident);
+
+// Set the current value of an option for the solver.
+//
+// Note that this is only valid to be called with options named by
+// `ipdos_option_list`, and the value must be of the correct type.
+bool ipdos_solver_option_set(IpdosSolver *solver, const char *ident, struct IpdosValue value);
+
+// Remove a model layer from the solver.
+//
+// It is required that `model.layers` is less than the number of layers in the
+// last call to `ipdos_solver_push` or `ipdos_solver_pop`. It is allowed to
+// remove multiple model layers at the same time.
+void ipdos_solver_pop(IpdosSolver *solver, struct IpdosModel model);
+
+// Add a new model layer to the solver.
+//
+// It is required that `model.layers` is exactly one larger than the previous
+// call to `ipdos_solver_push` or `ipdos_solver_pop`. It is NOT allowed to add
+// multiple model layers at the same time.
+bool ipdos_solver_push(IpdosSolver *solver, struct IpdosModel model);
+
+// Read an error message from the solver.
+//
+// This function is expected to be called after solver interactions signal an
+// error has occurred. For example, if [`ipdos_solver_run`] returns
+// [`IpdosError`] or [`ipdos_solver_push`] returns `false`.
+void ipdos_solver_read_error(IpdosSolver *solver,
+                             void *context,
+                             void (*read_error)(void *context, const char *error));
+
+// Run the solver with the given model
+enum IpdosStatus ipdos_solver_run(IpdosSolver *solver,
+                                  void *context,
+                                  void (*on_solution)(void *context,
+                                                      const struct IpdosSolution *solution));
+
+#endif  /* ipdos_protocol_h */

crates/ipdos_protocol/src/lib.rs

···
+//! IPDOS Protocol
+//!
+//! This crate defines the IPDOS protocol, which allows the incremental usage of
+//! solvers that can solve decision and optimization problems. The goal of the
+//! interface is to easily use different solvers in a unified way.
+#![allow(missing_debug_implementations)]
+
+use std::{ffi, marker::PhantomData};
+
+#[repr(C)]
+/// Representation of a type of constraint, discerned by its identifier and the
+/// types of its arguments.
+pub struct IpdosConstraintType<'a> {
+	/// The identifier of the constraint type.
+	pub ident: *const ffi::c_char,
+	/// The number of expected arguments for the constraint type.
+	pub arg_len: usize,
+	/// The types of the expected arguments for the constraint type.
+	pub arg_types: *const IpdosType,
+	/// The lifetime for which the `ident` and `arg_types` attributes are
+	/// allocated.
+	pub lifetime: PhantomData<&'a ()>,
+}
+
+#[repr(C)]
+/// A list of [`IpdosConstraintType`]s.
+///
+/// This type is for example used to return from [`ipdos_constraint_list`].
+pub struct IpdosConstraintList<'a> {
+	/// The number of elements in the `constraints` array.
+	pub len: usize,
+	/// An array of constraint types.
+	pub constraints: *const IpdosConstraintType<'a>,
+	/// The lifetime for which the `constraints` attribute is allocated.
+	pub lifetime: PhantomData<&'a ()>,
+}
+
+#[repr(C)]
+/// An interface to a model instance used to communicate with the solver.
+///
+/// The solver can use the included function callbacks to interact with the
+/// model.
+pub struct IpdosModel<'a> {
+	/// The handle to the data of the model instance.
+	///
+	/// This handle is passed to all the different function callbacks to
+	/// interact with the model.
+	data: &'a IpdosModelData,
+	/// Returns the current number of model layers currently contained in the
+	/// model.
+	///
+	/// Note that it is required that the solver calls [`ipdos_solver_push`] and
+	/// [`ipdos_solver_pop`] whenever a layer is added or removed.
+	layers: extern "C" fn(model: &IpdosModelData) -> usize,
+
+	/// Retrieve the number of constraints currently contained in the model.
+	constraint_len: extern "C" fn(model: &IpdosModelData) -> usize,
+	/// Retrieve the constraint index of the first new constraint in the layer.
+	///
+	/// This can be equivalent to `constraint_len` if the layer does not add any
+	/// new constraints.
+	constraint_layer_start: extern "C" fn(model: &IpdosModelData) -> usize,
+	/// Retrieve the identifier of a constraint.
+	///
+	/// The returned pointer can be assumed to have the the same lifetime as the
+	/// constraint reference and must be valid UTF8.
+	constraint_ident:
+		extern "C" fn(model: &IpdosModelData, constraint: usize) -> *const ffi::c_char,
+	/// Retrieve the number of arguments of a constraint.
+	constraint_argument_len: extern "C" fn(model: &IpdosModelData, constraint: usize) -> usize,
+	/// Retrieve the value of the constraint's argument at the given index.
+	///
+	/// The `index` argument must be less than the value returned by
+	/// `constraint_argument_len` for the given constraint.
+	constraint_argument:
+		extern "C" fn(model: &IpdosModelData, constraint: usize, index: usize) -> IpdosValue<'_>,
+
+	/// Retrieve the number of decisions currently contained in the model.
+	decision_len: extern "C" fn(model: &IpdosModelData) -> usize,
+	/// Retrieve the decision index of the first new decision in the layer.
+	///
+	/// This can be equivalent to `decision_len` if the layer does not add any
+	/// new decisions.
+	decision_layer_start: extern "C" fn(model: &IpdosModelData) -> usize,
+	/// Retrieve the domain of the given decision.
+	///
+	/// Note that the the value might have [`IpdosValueKind::IpdosValueAbsent`] if
+	/// the decision variable does not have an explicit domain.
+	decision_domain: extern "C" fn(model: &IpdosModelData, decision: usize) -> IpdosValue<'_>,
+	/// Retrieve the name of a decision variable, if it exists.
+	///
+	/// Note that names are only available for debugging purposes. Decisions are
+	/// identified using their index in the model. If the decision variable does
+	/// not have a name, this function returns a null pointer.
+	decision_name: extern "C" fn(model: &IpdosModelData, decision: usize) -> *const ffi::c_char,
+	/// Check whether the decision variable is functionally defined by a
+	/// constraint.
+	decision_defined: extern "C" fn(model: &IpdosModelData, decision: usize) -> bool,
+
+	/// Request the identifier of the type of objective strategy to be used when
+	/// solving the model.
+	///
+	/// Note that the function can return a null pointer if the model does not
+	/// have an objective strategy.
+	objective_ident: extern "C" fn(model: &IpdosModelData) -> *const ffi::c_char,
+	/// Retrieve the argument of the objective strategy.
+	objective_arg: extern "C" fn(model: &IpdosModelData) -> IpdosValue<'_>,
+}
+
+#[repr(transparent)]
+/// The handle to a the data of a model instance.
+///
+/// This type is opaque to the user. Only pointers of this type are ever used.
+///
+/// In implementation of the IPDOS interface, a pointer is generally cast to
+/// this type, i.e. `(IpdosModelData*) my_model`. A similar cast can be used to
+/// cast the pointer back to the original type, e.g. `(MyModel*) ipdos_model`.
+pub struct IpdosModelData(ffi::c_void);
+
+#[repr(C)]
+/// Representation of a type of objective strategies, discerned by its
+/// identifier and the type of its argument.
+pub struct IpdosObjective<'a> {
+	/// The identifier of the objective type.
+	pub ident: *const ffi::c_char,
+	/// The type of the expected argument for the constraint type.
+	pub arg_type: IpdosType,
+	/// The lifetime for which the `ident` attribute is allocated.
+	pub lifetime: PhantomData<&'a ()>,
+}
+
+#[repr(C)]
+/// A list of [`IpdosObjective`]s.
+///
+/// This type is, for example, used to return from [`ipdos_objective_list`].
+pub struct IpdosObjectiveList<'a> {
+	/// The number of elements in the `options` array.
+	pub len: usize,
+	/// An array of option definitions.
+	pub options: *const IpdosObjective<'a>,
+	/// The lifetime of the `options` attribute.
+	pub lifetime: PhantomData<&'a ()>,
+}
+
+#[repr(C)]
+/// The definition of an option that is available to be set for the solver.
+pub struct IpdosOption<'a> {
+	/// The identifier used to set the option or get the current value of the option.
+	pub ident: *const ffi::c_char,
+	/// The type of value that is expected for this option.
+	pub arg_ty: IpdosValue<'a>,
+	/// The default value for this option.
+	pub arg_def: IpdosType,
+	/// The lifetime of the `ident` attribute.
+	pub lifetime: PhantomData<&'a ()>,
+}
+
+#[repr(C)]
+/// A list of [`IpdosOption`]s.
+///
+/// This type is, for example, used to return from [`ipdos_option_list`].
+pub struct IpdosOptionList<'a> {
+	/// The number of elements in the `options` array.
+	pub len: usize,
+	/// An array of option definitions.
+	pub options: *const IpdosOption<'a>,
+	/// The lifetime of the `options` attribute.
+	pub lifetime: PhantomData<&'a ()>,
+}
+
+#[repr(C)]
+/// Structure used to represent a solution emitted by the solver.
+///
+/// The caller can use the `get_value` function to retrieve the value of the
+/// used decision variables.
+pub struct IpdosSolution<'a> {
+	/// The data pointer to be the first argument of `get_value`.
+	data: &'a IpdosSolutionData,
+	/// Function callback to retrieve the value assigned to a decision variable
+	/// in the solution.
+	get_value: extern "C" fn(data: &IpdosSolutionData, decision_index: usize) -> IpdosValue<'_>,
+}
+
+#[repr(transparent)]
+/// The handle to a the data of a solution instance.
+///
+/// This type is opaque to the user. Only pointers of this type are ever used.
+///
+/// In implementation of the IPDOS interface, a pointer is generally cast to
+/// this type, i.e. `(IpdosSolutionData*) my_solution`. A similar cast can be
+/// used to cast the pointer back to the original type, e.g. `(MySolution*)
+/// ipdos_solution`.
+pub struct IpdosSolutionData(ffi::c_void);
+
+#[repr(transparent)]
+/// The handle to a solver instance.
+///
+/// This type is opaque to the user. Only pointers of this type are ever used.
+///
+/// In implementation of the IPDOS interface, a pointer is generally cast to
+/// this type, i.e. `(IpdosSolver*) my_solver`. A similar cast can be used to
+/// cast the pointer back to the original type, e.g. `(MySolverType*)
+/// ipdos_solver`.
+pub struct IpdosSolver(ffi::c_void);
+
+#[repr(C)]
+/// The status returned by `ipdos_solver_run`, indicating whether the solver
+/// completed its search.
+pub enum IpdosStatus {
+	/// The solver explored the full search space and yielded all relevant
+	/// solutions.
+	IpdosComplete,
+	/// The solver did not explore the full search space due to a timeout or
+	/// other termination condition. Additional (better) solutions might be
+	/// possible.
+	IpdosIncomplete,
+	/// An error occurred during the solver's execution.
+	///
+	/// `ipdos_solver_read_error` can be used to retrieve the error message.
+	IpdosError,
+}
+
+#[repr(C)]
+/// Representation of a type to signal and check whether an argument takes the
+/// correct type.
+pub struct IpdosType {
+	/// Whether the type is a list of values.
+	pub list_of: bool,
+	/// Whether the argument can be or contain decision variables (represented as
+	/// decision indexes).
+	pub decision: bool,
+	/// Whether expected type is an set of values of the base type.
+	pub set_of: bool,
+	/// The expected base type of the argument.
+	pub base: IpdosTypeBase,
+}
+
+#[repr(C)]
+/// Representation of the base type of a value.
+pub enum IpdosTypeBase {
+	/// Boolean type
+	IpdosTypeBaseBool,
+	/// Integer numeric type
+	IpdosTypeBaseInt,
+	/// Floating point numeric type
+	IpdosTypeBaseFloat,
+	/// Character string type
+	IpdosTypeBaseString,
+}
+
+#[repr(C)]
+/// A list of [`IpdosType`]s.
+///
+/// This type is for example used to return from [`ipdos_decision_list`].
+pub struct IpdosTypeList<'a> {
+	/// The number of elements in the `constraints` array.
+	pub len: usize,
+	/// An array of constraint types.
+	pub types: *const IpdosType,
+	/// The lifetime for which the `types` attribute is allocated.
+	pub lifetime: PhantomData<&'a ()>,
+}
+
+#[repr(C)]
+/// The value representation used for values assigned to decision variables in
+/// solution, as constraint/annotation arguments, and option parameters.
+pub struct IpdosValue<'a> {
+	/// The kind of the value
+	///
+	/// This field is used to determine what field in the `value` union is
+	/// allowed to be accessed.
+	pub kind: IpdosValueKind,
+	/// A field containing the size of the value.
+	///
+	/// This field is used when the value is a list, set of float/int, and
+	/// string, to determine the number of elements in the C array type.
+	pub len: u32,
+	/// The storage of the actual data of the value.
+	pub content: IpdosValueContent<'a>,
+	/// Lifetime of the value (only relevant in Rust).
+	pub lifetime: PhantomData<&'a ()>,
+}
+
+#[repr(C)]
+/// The storage of the value content of a [`IpdosValue`].
+pub union IpdosValueContent<'a> {
+	/// Decision index storage
+	pub decision_index: usize,
+	/// Boolean value storage
+	pub bool_value: bool,
+	/// Integer value storage
+	pub integer_value: i64,
+	/// Float value storage
+	pub float_value: f64,
+	/// Set of integers value storage
+	///
+	/// The set of integers is represented using a range list. The array of
+	/// `i64` values should be interpreted as a list of inclusive ranges,
+	/// where each range is represented by two values.
+	///
+	/// Note that the number of `i64` values is stored in the `len` field. Since
+	/// each range is represented by two values, it can be assumed that `len mod
+	/// 2 == 0`.
+	pub set_of_int_value: *const i64,
+	/// Set of floating point value storage
+	///
+	/// The set of floating point values is represented using a range list. The
+	/// array of `f64` values should be interpreted as a list of inclusive
+	/// ranges, where each range is represented by two values.
+	///
+	/// Note that the number of `f64` values is stored in the `len` field. Since
+	/// each range is represented by two values, it can be assumed that `len mod
+	/// 2 == 0`.
+	pub set_of_float_value: *const i64,
+	/// String value storage
+	///
+	/// Note that the `string_value` field is intended to be interpreted as a
+	/// C-string. It should be \0 terminated, use UTF-8 encoding, and be valid
+	/// for the lifetime of the value.
+	pub string_value: *const ffi::c_char,
+	/// List value storage
+	///
+	/// Note that the the number of elements in the list is stored in the `len`
+	/// field.
+	pub list_value: *const IpdosValue<'a>,
+}
+
+#[repr(C)]
+/// Enumerated type used to mark the kind of [`IpdosValue`]. This is used to
+/// determine which field in the [`IpdosValueContent`] union to access.
+pub enum IpdosValueKind {
+	/// No value is stored.
+	IpdosValueAbsent,
+	/// The value is stored in `decision_index`.
+	IpdosValueDecision,
+	/// The value is stored in `boolean_value`.
+	IpdosValueBoolean,
+	/// The value is stored in `integer_value`.
+	IpdosValueInteger,
+	/// The value is stored in `float_value`.
+	IpdosValueFloat,
+	/// The value is stored in `string_value`.
+	IpdosValueString,
+	/// The value is stored in `list_value`.
+	IpdosValueList,
+}
+
+#[unsafe(no_mangle)]
+/// Returns the list of available constraint that can be added to the solver.
+pub extern "C" fn ipdos_constraint_list() -> IpdosConstraintList<'static> {
+	unimplemented!()
+}
+
+#[unsafe(no_mangle)]
+/// Returns the list of types for which decision variable can be created by the
+/// solver.
+pub extern "C" fn ipdos_decision_list() -> IpdosTypeList<'static> {
+	unimplemented!()
+}
+
+#[unsafe(no_mangle)]
+/// Returns the list of available objective that can be achieved by the solver.
+pub extern "C" fn ipdos_objective_list() -> IpdosObjectiveList<'static> {
+	unimplemented!()
+}
+
+#[unsafe(no_mangle)]
+/// Returns the list of available options that can be set of the solver.
+pub extern "C" fn ipdos_option_list() -> IpdosOptionList<'static> {
+	unimplemented!()
+}
+
+#[unsafe(no_mangle)]
+/// Create a new solver instance
+pub extern "C" fn ipdos_solver_create() -> Box<IpdosSolver> {
+	unimplemented!()
+}
+
+/// 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.
+#[unsafe(no_mangle)]
+pub extern "C" fn ipdos_solver_free(solver: Box<IpdosSolver>) {
+	let _ = solver;
+	unimplemented!()
+}
+
+#[unsafe(no_mangle)]
+/// Get the current value of an option for the solver.
+///
+/// Note that this is only valid to be called with options named by
+/// `ipdos_option_list`.
+pub extern "C" fn ipdos_solver_option_get(
+	solver: &IpdosSolver,
+	ident: *const ffi::c_char,
+) -> IpdosValue<'_> {
+	let _ = solver;
+	let _ = ident;
+	unimplemented!()
+}
+
+#[unsafe(no_mangle)]
+/// Set the current value of an option for the solver.
+///
+/// Note that this is only valid to be called with options named by
+/// `ipdos_option_list`, and the value must be of the correct type.
+pub extern "C" fn ipdos_solver_option_set(
+	solver: &mut IpdosSolver,
+	ident: *const ffi::c_char,
+	value: IpdosValue<'_>,
+) -> bool {
+	let _ = solver;
+	let _ = ident;
+	let _ = value;
+	unimplemented!()
+}
+
+#[unsafe(no_mangle)]
+/// Remove a model layer from the solver.
+///
+/// It is required that `model.layers` is less than the number of layers in the
+/// last call to `ipdos_solver_push` or `ipdos_solver_pop`. It is allowed to
+/// remove multiple model layers at the same time.
+pub extern "C" fn ipdos_solver_pop(solver: &mut IpdosSolver, model: IpdosModel) {
+	let _ = solver;
+	let _ = model;
+	unimplemented!()
+}
+
+#[unsafe(no_mangle)]
+/// Add a new model layer to the solver.
+///
+/// It is required that `model.layers` is exactly one larger than the previous
+/// call to `ipdos_solver_push` or `ipdos_solver_pop`. It is NOT allowed to add
+/// multiple model layers at the same time.
+pub extern "C" fn ipdos_solver_push(solver: &mut IpdosSolver, model: IpdosModel) -> bool {
+	let _ = solver;
+	let _ = model;
+	unimplemented!()
+}
+
+#[unsafe(no_mangle)]
+/// Read an error message from the solver.
+///
+/// This function is expected to be called after solver interactions signal an
+/// error has occurred. For example, if [`ipdos_solver_run`] returns
+/// [`IpdosError`] or [`ipdos_solver_push`] returns `false`.
+pub extern "C" fn ipdos_solver_read_error(
+	solver: &mut IpdosSolver,
+	context: &mut ffi::c_void,
+	read_error: extern "C" fn(context: &mut ffi::c_void, error: *const ffi::c_char),
+) {
+	let _ = solver;
+	let _ = context;
+	let _ = read_error;
+	unimplemented!()
+}
+
+#[unsafe(no_mangle)]
+/// Run the solver with the given model
+pub extern "C" fn ipdos_solver_run(
+	solver: &mut IpdosSolver,
+	context: &mut ffi::c_void,
+	on_solution: extern "C" fn(context: &mut ffi::c_void, solution: &IpdosSolution),
+) -> IpdosStatus {
+	let _ = solver;
+	let _ = context;
+	let _ = on_solution;
+	unimplemented!()
+}
+
+#[cfg(test)]
+mod tests {
+	use crate::{IpdosType, IpdosValue};
+
+	#[test]
+	fn memory() {
+		assert_eq!(size_of::<IpdosValue>(), size_of::<u128>());
+		assert_eq!(size_of::<IpdosType>(), size_of::<u64>());
+	}
+}

rustfmt.toml

···
+group_imports = "StdExternalCrate"
+hard_tabs = true
+imports_granularity = "Crate"
+wrap_comments = true