package gudusoft.gsqlparser.pp2.region;

import gudusoft.gsqlparser.EDbVendor;
import gudusoft.gsqlparser.TGSqlParser;

/**
 * Size-1 pool that owns a single {@link TGSqlParser} per {@link EDbVendor}.
 *
 * <p>Allocating a new {@code TGSqlParser} is non-trivial (vendor parser
 * factory wiring, lexer state, license initialisation). For a script with N
 * statement regions, the engine wants to perform up to N parse attempts
 * without paying allocation cost per region. {@code ParserPool} hands out
 * the same instance every time after a lazy first allocation, and provides
 * an explicit {@link #reset()} for the engine to call between regions.
 *
 * <p>"Size-1" is the plan's mandate (§5.3, §7.3/S12). The pool is therefore
 * <b>single-threaded by construction</b> — a single {@code ParseRecoveryEngine}
 * must never call {@link #borrow()} or {@link #reset()} from more than one
 * thread concurrently. No locking is provided; concurrent use is undefined.
 *
 * <h2>Reset semantics</h2>
 *
 * <p>{@link TGSqlParser#prepareForReuse()} (available since GSP 3.2.0.0)
 * clears cached vendor parser, the SQL environment, the source filename, the
 * statement list, and the syntax-error list, and resets parsing options to
 * their defaults. The pool's {@link #reset()} method invokes
 * {@code prepareForReuse()} and additionally calls
 * {@link TGSqlParser#setSqltext(String) setSqltext("")} which atomically
 * clears {@code sqltext}, {@code sqlfilename}, and the cached
 * {@code sqlInputStream}. {@code prepareForReuse} as of 3.2.x does not
 * touch {@code sqlInputStream}, so this extra step is required to avoid a
 * prior file-based parse's stream leaking into the next call.
 *
 * <p>Note: {@code setSqlInputStream(null)} would <i>throw</i> because of an
 * unconditional {@code new BufferedInputStream(input)} on its else branch.
 * The {@code setSqltext("")} path is the only safe way to null out the
 * stream field from public API.
 *
 * <p>Reset is idempotent and safe to call before the first {@link #borrow()}.
 *
 * <p>Plan reference: §5.3, §7.3/S12, §7.4/S12, §13/R1.
 */
public final class ParserPool {

    private final EDbVendor vendor;
    private TGSqlParser parser;     // lazily allocated by borrow()
    private long borrowCount;       // for tests / observability
    private long resetCount;

    public ParserPool(EDbVendor vendor) {
        if (vendor == null) throw new NullPointerException("vendor");
        this.vendor = vendor;
    }

    public EDbVendor getVendor() { return vendor; }

    /**
     * Return the pooled parser, allocating it on the first call. Increments
     * {@link #getBorrowCount()}.
     */
    public TGSqlParser borrow() {
        if (parser == null) {
            parser = new TGSqlParser(vendor);
        }
        borrowCount++;
        return parser;
    }

    /**
     * Clear stale parser state so the next {@link #borrow()} sees a clean
     * baseline. Safe to call before the first borrow (no-op). Increments
     * {@link #getResetCount()} regardless.
     *
     * <h3>Why this does NOT call {@code prepareForReuse()} (performance)</h3>
     *
     * <p>{@link TGSqlParser#prepareForReuse()} nulls the cached
     * <i>vendor parser</i>. The vendor parser owns the YACC/LEX parse tables —
     * large {@code int[]}/{@code long[]} arrays (~100KB+ per dialect). Nulling
     * it forces {@code parse()} to re-create the vendor parser and reload those
     * tables on <i>every</i> region. On a script with hundreds of statement
     * regions that is hundreds of full table reloads — measured at ~351MB of
     * {@code int[]} churn for an 18KB / 534-region invalid script, which pushes
     * the formatter into GC thrash (and OOM-to-FAILED) under a constrained heap
     * (-Xmx512m). {@code getVendorParser()} is explicitly designed to cache and
     * reuse the vendor parser across {@code parse()} calls, so reusing it
     * between regions is the supported path, not a hack. (Root-caused in S36;
     * gates S37. plan §13/R14, R16.)
     *
     * <p>A lighter reset is sufficient because {@code doparse()} already
     * rebuilds {@code sourcetokenlist} and {@code sqlstatements} and clears
     * {@code syntaxErrors} at the start of every parse. We only need to clear
     * the input fields here: {@code setSqltext("")} atomically clears
     * {@code sqltext}, {@code sqlfilename}, AND the cached {@code sqlInputStream}
     * (calling {@code setSqlInputStream(null)} would throw, so {@code setSqltext}
     * is the only safe way to null the stream field from public API).
     */
    public void reset() {
        resetCount++;
        if (parser == null) return;
        try {
            // Clears sqltext + sqlfilename + cached input stream. Keeps the
            // cached vendor parser (and its parse tables) so the next parse
            // does not reload them. parse() rebuilds the statement list and
            // clears syntax errors itself, so no stale parse output bleeds.
            parser.setSqltext("");
        } catch (Throwable t) {
            // setSqltext is not expected to throw; if it ever does, drop the
            // parser so the next borrow() rebuilds a clean one. Reset stays
            // non-throwing.
            parser = null;
        }
    }

    /** Number of times {@link #borrow()} has been called. */
    public long getBorrowCount() { return borrowCount; }

    /** Number of times {@link #reset()} has been called. */
    public long getResetCount() { return resetCount; }

    /**
     * True when the pool has allocated its parser. Visible for tests that
     * want to assert lazy allocation behaviour.
     */
    public boolean isAllocated() { return parser != null; }
}