Crate ddss 

ddss

Rusty API for ddss, a performance-oriented fork of the DDS double dummy solver for bridge. ddss is based on DDS 2.9.0 and keeps the 2.9 design — a single persistent internal thread pool with non-reentrant entry points. This crate wraps the raw ddss-sys FFI bindings behind a Solver guard that serializes access to that pool.

Example

use contract_bridge::{FullDeal, Seat, Strain};
use ddss::Solver;

let deal: FullDeal = "N:AKQJT98765432... .AKQJT98765432.. \
                      ..AKQJT98765432. ...AKQJT98765432".parse()?;
let solver = Solver::lock();
let tricks = solver.solve_deal(deal);
assert_eq!(u8::from(tricks[Strain::Spades].get(Seat::North)), 13);

Threading

Solver is a guard, not an owned context. ddss exposes a global thread pool that is initialized once (via SetMaxThreads(0)) on first lock acquisition. Hold a Solver once for a batch of related calls to avoid repeated locking. Batch entry points (solve_deals, solve_boards) parallelize internally across that pool — there is no need for caller-side rayon.

Because Solver wraps a parking_lot::MutexGuard<'static, ()>, it is !Send: the lock must be released on the same OS thread that acquired it. Spawn one thread per solving job and acquire the lock inside that thread.

Relationship to dds-bridge

dds-bridge wraps a different sys crate (dds-bridge-sys, DDS 3.x) with a per-context Solver design that fits DDS 3’s reentrant API. This crate is the analogous wrapper for ddss; the two cannot link in the same binary because their underlying C libraries export overlapping symbols.

Panic policy

The solver entry points in this crate — calculate_par, calculate_pars, Solver::solve_deal, Solver::solve_board, Solver::solve_deals, Solver::solve_boards, Solver::analyse_play, and Solver::analyse_plays — are not expected to panic. They map ddss status codes through an internal helper that panics on error, but reaching that panic means either invalid input slipped past a safe constructor or ddss itself misbehaved. Either case is a bug — please report it.

This policy does not cover validator panics from safe constructors (e.g. TrickCountRow::new), which panic by design on out-of-range inputs and have try_* counterparts for fallible construction.

Structs

Board

A snapshot of a board

CurrentTrick

Trick-in-progress — 0 to 3 cards played, in playing order

FoundPlays

Solved plays for a board

InvalidTrickCount

Error returned when a trick count is outside 0..=13

NonEmptyStrainFlags

A guaranteed non-empty StrainFlags

Objective

A board and its solving target

Par

Par score and contracts

ParContract

Par contract

ParseVulnerabilityError

Error returned when parsing a Vulnerability fails

Play

A play and its consequences

PlayAnalysis

Double-dummy trick counts before and after each played card in a trace

PlayTrace

A starting board and a sequence of cards played from it

PlayTraceBin

Thin wrapper over sys::playTraceBin so we can impl conversions for it

Solver

Exclusive handle to the ddss solver

StrainFlags

Flags for the solver to solve for a strain

SystemInfo

Information about the ddss library and how it was built

TrickCount

A number of tricks in 0..=13

TrickCountRow

Tricks that each seat can take as declarer for a strain

TrickCountRowHex

Hexadecimal view of a TrickCountRow from a seat’s perspective

TrickCountTable

Tricks that each seat can take as declarer for all strains

TrickCountTableHex

Hexadecimal view of a TrickCountTable from a seat’s perspective

Vulnerability

Vulnerability of pairs

Enums

BoardError

Error returned when constructing a Board with invalid invariants

Compiler

C++ compiler used to build the ddss library

CurrentTrickError

Error returned when pushing cards to a CurrentTrick

Platform

OS platform reported by the ddss library

RevokePosition

Position of the revoking card within the current trick

Target

Target tricks and number of solutions to find

Threading

Threading model used by the ddss library

Functions

calculate_par

Calculate par score and contracts for a deal

calculate_pars

Calculate par scores for both pairs

dd_table_deal_from

Convert a validated deal (either FullDeal or PartialDeal) into a ddss ddTableDeal.

dd_table_deal_from_builder

Low-level conversion from a Builder into a ddss ddTableDeal.

strain_to_sys

Convert a Strain to its index in ddss_sys

system_info

Get information about the underlying ddss library