Skip to content

c++_interface.md

Latest commit

 

History

History
163 lines (105 loc) · 4.08 KB

c++_interface.md

File metadata and controls

163 lines (105 loc) · 4.08 KB

C++ Interface Documentation

Overview

DDS provides a modernized C++ interface built around instance-scoped solver state.

  • Preferred umbrella include: #include <dds/dds.hpp>
  • Core modernization concept: SolverContext

The modern API is designed to preserve existing solver behavior while improving ownership, lifecycle control, and composability in C++ applications.

Design Goals

The modern C++ interface emphasizes:

  • Instance-scoped state: each SolverContext owns or references its own thread state.
  • RAII resource management: context lifetime drives solver resource lifetime.
  • Explicit transposition-table lifecycle control.
  • Snake_case C++ entry points.

Public C++ Headers

Primary entry points:

  • library/src/dds.hpp (exported as <dds/dds.hpp>)
  • library/src/api/solve_board.hpp
  • library/src/api/calc_dd_table.hpp
  • library/src/api/calc_par.hpp
  • library/src/solver_context/solver_context.hpp

Core Types

SolverConfig

SolverConfig controls context-level transposition table configuration.

Fields:

  • tt_kind_: TTKind::Small or TTKind::Large
  • tt_mem_default_mb_: default TT memory in MB
  • tt_mem_maximum_mb_: maximum TT memory in MB

SolverContext

SolverContext is the primary C++ state holder for solving operations.

Capabilities include:

  • Access to thread data via thread()
  • Solver utility facade via utilities()
  • Search state facade via search()
  • TT lifecycle methods:
    • trans_table() / maybe_trans_table()
    • reset_for_solve()
    • reset_best_moves_lite()
    • clear_tt()
    • dispose_trans_table()
    • configure_tt(...)

Threading note:

  • SolverContext is not inherently thread-safe.
  • Use one context per worker thread.

Modern C++ API Functions

Solve APIs

Preferred context-aware solve function:

  • solve_board(SolverContext& ctx, const Deal& dl, int target, int solutions, int mode, FutureTricks* futp)

Compatibility wrapper also available in C++:

  • SolveBoard(SolverContext& ctx, const Deal& dl, int target, int solutions, int mode, FutureTricks* futp)

DD Table APIs

Temporary-context overloads:

  • calc_dd_table(const DdTableDeal& table_deal, DdTableResults* table_results)
  • calc_dd_table_pbn(const DdTableDealPBN& table_deal_pbn, DdTableResults* table_results)

Context-aware overloads:

  • calc_dd_table(SolverContext& ctx, const DdTableDeal& table_deal, DdTableResults* table_results)
  • calc_dd_table_pbn(SolverContext& ctx, const DdTableDealPBN& table_deal_pbn, DdTableResults* table_results)

Par APIs

Par with table calculation:

  • calc_par(const DdTableDeal& table_deal, int vulnerable, DdTableResults* table_results, ParResults* par_results)
  • calc_par(SolverContext& ctx, const DdTableDeal& table_deal, int vulnerable, DdTableResults* table_results, ParResults* par_results)

Par from precomputed table:

  • calc_par_from_table(const DdTableResults* table_results, int vulnerable, ParResults* par_results)

Data Structures and Status Codes

All core deal/result structs and return codes are defined in api/dll.h and exposed via dds.hpp.

Examples include:

  • Deal, DealPBN, Boards, BoardsPBN
  • FutureTricks, DdTableDeal, DdTableResults, ParResults
  • RETURN_NO_FAULT and other error/status constants

Usage Example

#include <dds/dds.hpp>
#include <iostream>

int main()
{
    SolverConfig cfg;
    cfg.tt_kind_ = TTKind::Large;
    cfg.tt_mem_default_mb_ = 256;
    cfg.tt_mem_maximum_mb_ = 512;

    SolverContext ctx(cfg);

    Deal dl{};
    // Fill dl.trump, dl.first, dl.currentTrickSuit/Rank, dl.remainCards

    FutureTricks fut{};
    const int rc = solve_board(ctx, dl, -1, 3, 0, &fut);

    if (rc != RETURN_NO_FAULT) {
        std::cerr << "solve_board failed: " << rc << "\n";
        return rc;
    }

    std::cout << "cards=" << fut.cards << " nodes=" << fut.nodes << "\n";

    // Optional lifecycle control between independent batches:
    // ctx.reset_for_solve();

    return 0;
}

Build and Verification

Build all targets:

bazel build //...

Run tests:

bazel test //...

Build docs package:

bazel build //:doxygen_docs