dds_c_api.h

/*
   DDS, a bridge double dummy solver.

   C-ABI shim over the modern SolverContext API (dds_api.hpp).

   Every function here is C-callable and takes only pointers and plain-old-data
   by value: the opaque handle is a void*, and non-POD C++ types (SolverConfig,
   TTKind, C++ references) never appear. This gives Java (FFM/jextract), .NET,
   and ctypes a single clean, stable ABI to bind against.

   NOTE: the *exported symbols* are a pure C ABI, but this header is not itself
   compilable by a C front-end: it includes <api/dll.h>, whose flat API is
   declared with C++ trailing-return syntax (auto ... -> int). Consume the ABI
   by binding to the compiled library's symbols (FFM/ctypes/.NET) or by parsing
   the headers with a C++ mode (jextract); do not #include this from a C
   translation unit.

   See LICENSE and README.
*/

#pragma once

#include <api/dll.h>   /* struct Deal, FutureTricks, DdTableDeal, DdTableResults, ParResults */

#ifdef __cplusplus
extern "C" {
#endif

/* Opaque solver-context handle. Owns per-context solver state and the
   transposition table. Create with dds_c_create_solvercontext_default and
   release with dds_c_destroy_solvercontext. Not thread-safe: use one handle
   per thread. */
typedef void* DDS_C_SOLVER_CTX;

/* Creation / destruction. */
DLLEXPORT DDS_C_SOLVER_CTX dds_c_create_solvercontext_default(void);
DLLEXPORT void             dds_c_destroy_solvercontext(DDS_C_SOLVER_CTX ctx);

/* Solve a single board. Returns a RETURN_* status code. */
DLLEXPORT int dds_c_solve_board(DDS_C_SOLVER_CTX ctx,
                                const struct Deal* dl,
                                int target, int solutions, int mode,
                                struct FutureTricks* futp);

/* Compute the double dummy table for a deal. */
DLLEXPORT int dds_c_calc_dd_table(DDS_C_SOLVER_CTX ctx,
                                  const struct DdTableDeal* deal,
                                  struct DdTableResults* results);

/* Compute the par result for a deal (computes the DD table internally). */
DLLEXPORT int dds_c_calc_par(DDS_C_SOLVER_CTX ctx,
                             const struct DdTableDeal* deal,
                             int vulnerable,
                             struct DdTableResults* results,
                             struct ParResults* par);

/* Creation with explicit transposition-table configuration. The C++ SolverConfig
   is decomposed into scalars rather than mirrored as a struct: passing a struct
   by value is exactly the ABI question this shim exists to avoid, and a mirror
   type would be a second definition to keep in sync. tt_kind: 0 = Small,
   1 = Large (matching enum class TTKind). Returns NULL on failure. */
DLLEXPORT DDS_C_SOLVER_CTX dds_c_create_solvercontext(int tt_kind,
                                                      int def_mb, int max_mb);

/* Compute the double dummy table from a PBN-format deal. */
DLLEXPORT int dds_c_calc_dd_table_pbn(DDS_C_SOLVER_CTX ctx,
                                      const struct DdTableDealPBN* deal,
                                      struct DdTableResults* results);

/* Transposition-table configuration. */
DLLEXPORT void dds_c_configure_tt(DDS_C_SOLVER_CTX ctx, int tt_kind,
                                  int def_mb, int max_mb);
DLLEXPORT void dds_c_resize_tt(DDS_C_SOLVER_CTX ctx, int def_mb, int max_mb);
DLLEXPORT void dds_c_clear_tt(DDS_C_SOLVER_CTX ctx);

/* Per-solve state resets. */
DLLEXPORT void dds_c_reset_for_solve(DDS_C_SOLVER_CTX ctx);
DLLEXPORT void dds_c_reset_best_moves_lite(DDS_C_SOLVER_CTX ctx);

/* Logging passthrough. msg is a NUL-terminated UTF-8 string. */
DLLEXPORT void dds_c_log_append(DDS_C_SOLVER_CTX ctx, const char* msg);
DLLEXPORT void dds_c_log_clear(DDS_C_SOLVER_CTX ctx);

#ifdef __cplusplus
}
#endif