SqlPointerCache class

LRU cache of native UTF-8 pointers keyed by their original Dart String.

Eliminates the per-call toNativeUtf8 + malloc.free round-trip when the same SQL string is executed repeatedly (hot loops, prepared statement rewrite paths, etc.). Cache hits return the previously-allocated pointer directly; misses allocate, register, and return.

Lifecycle

  • The pointer is owned by the cache. Callers MUST NOT free it.
  • When an entry is evicted (because maxSize was reached), its pointer is freed via malloc.free.
  • dispose releases every cached pointer; call once when the owning OdbcNative is disposed.

Concurrency

Each OdbcNative owns its own cache, and the FFI mutex serializes calls through a single connection. Sharing one cache across isolates would require explicit synchronization and is not the intended design.

Sizing

Default 256 entries × average ~512 bytes per SQL ≈ 128 KB. Workloads with larger SQL or wider hot sets should pass a custom maxSize.

Constructors

SqlPointerCache({int maxSize = _defaultMaxSize})

Properties

hashCode → int
The hash code for this object.
no setterinherited
length → int
Number of entries currently held by the cache.
no setter
maxSize → int
Maximum number of cached entries. Once full, the oldest entry is freed to make room for the new one (LRU policy via LinkedHashMap insertion order).
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
stats → ({int evictions, int hits, int misses})
Diagnostic counters since construction. Useful for benchmarks and regression tests; do not export through telemetry without rolling.
no setter

Methods

acquire(String sql) → Pointer<Utf8>
Returns a native UTF-8 pointer for sql, allocating if necessary.
containsSql(String sql) → bool
Whether the cache contains an entry for sql.
dispose() → void
Frees every cached pointer. Safe to call multiple times. The cache is reusable after dispose if a new instance is constructed.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
resetStats() → void
Resets the diagnostic counters without touching the cached entries.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited