lib/match-cache.x

Caches of prepared Match plans.

Primary API

Functions

x2c_match_thread_release

void x2c_match_thread_release(void)

Disposes this thread’s default Match plan cache. x2c_thread_state_release calls it before Scope releases the Scope that holds that cache; a thread that never matched has no cache and nothing happens. All default-cache leases and Context states must already be closed.

Raises: <bad-state> when a lease remains active.

Source: lib/match-cache.x:527

MatchCache

MatchCache.context_close

void MatchCache.context_close(void *token)

Disposes and removes the top Context’s default Match cache. A null token is ignored. Successful close restores the previous default; the token storage remains owned by its Context Scope.

Raises: <bad-state> when token is not the top state or its cache has an active lease. The failure leaves the state installed.

Source: lib/match-cache.x:510

MatchCache.context_open

void *MatchCache.context_open(void)

Opens one Context-local default Match-cache state. The returned opaque token becomes the top of a thread-local LIFO stack; its cache is created only on first use. The token is allocated in the active Scope and must be passed to MatchCache.context_close before that Scope ends.

Raises: <alloc-fail> when the state cannot be allocated.

Source: lib/match-cache.x:496

Runtime-internal callables

These callables connect runtime translation units. They are documented for source readers but are not supported as user API.

MatchCache

MatchCache.acquire

int MatchCache.acquire( MatchCache m, Var pattern, MatchLease &lease, const char *owner)

Acquires a lease for a cached prepared pattern. cache and lease must be nonnull, and owner names the operation a fence diagnostic should report. The lease is initialized on every returning path. An admitted pattern reuses or creates an LRU entry; an inadmissible pattern gets a transient plan owned by the lease. Returns the plan’s MachinePrepare status, or MATCH_CACHE_PRESSURE when every entry is pinned. Release the lease after any returned status; releasing the inactive pressure lease is a no-op.

Raises: <size-limit> when pattern exceeds a lowering limit. Such a pattern compiles to no program, so it is never cached and never leased. <alloc-fail> may also be raised while preparing or growing storage.

Source: lib/match-cache.x:94

MatchCache.current

MatchCache MatchCache.current(void)

Returns the active default Match cache, creating it on first use.

Raises: <alloc-fail> when the cache cannot be created.

Source: lib/match-cache.x:463

MatchCache.dispose

void MatchCache.dispose(MatchCache cache)

Destroys a Match cache with no active leases. A null cache is ignored. Disposal frees all plans and cache storage and invalidates every alias.

Raises: <bad-state> when a lease remains active. The failure leaves the cache intact.

Source: lib/match-cache.x:571

MatchCache.flush_default

void MatchCache.flush_default(void)

Destroys the active Context-local or thread-local Match cache. A missing cache is ignored; the next Match recreates it lazily. Static compiler capture sites are unaffected.

Raises: <bad-state> when a lease remains active. The failure leaves the cache installed.

Source: lib/match-cache.x:482

MatchCache.new

MatchCache MatchCache.new(int capacity)

Creates a MatchCache retaining up to capacity prepared patterns. The returned cache owns a named Scope and is not synchronized. It borrows admitted pattern identities, so dispose it before their owning canonical pools. MatchCache.dispose is required after every lease is released.

Raises: <bad-arg> when capacity is not positive, <size-limit> when its storage dimensions cannot be represented, and <alloc-fail> when cache storage cannot be allocated.

Source: lib/match-cache.x:544

MatchCache.search

int MatchCache.search( MatchCache cache, List input, Var pattern, List &out_results, const char *owner)

Searches through cache, writing every match. out_results must be nonnull. It receives the reverse-visitation result List, or nil when there are no matches, the pattern is malformed, cache pressure prevents execution, or the machine fails. Returns 1 exactly when that List is nonempty.

Raises: <size-limit> for an ineligible pattern, or <alloc-fail> while preparing or constructing results.

Source: lib/match-cache.x:403

MatchCache.search_replace

int MatchCache.search_replace( MatchCache cache, List input, Var pattern, Var template, List &out, const char *owner)

Replaces every match through cache from the leaves upward. out must be nonnull. A completed prepared traversal returns 1 and writes its result even when nothing matched. A malformed pattern, cache pressure, or machine error returns 0 and writes input unchanged.

Raises: <size-limit> for an ineligible pattern, or <alloc-fail> while preparing, traversing, or replacing.

Source: lib/match-cache.x:434

MatchCache.try_capture

int MatchCache.try_capture( MatchCache cache, List input, Var pattern, MatchCaptureBuffer &?captures, const char *owner)

Matches through cache into caller-owned positional storage. Returns 1 only after atomically committing a valid buffer. A miss, malformed pattern, invalid buffer, cache pressure, or machine error returns 0 and leaves it unchanged.

Raises: <size-limit> for an ineligible pattern, or <alloc-fail> while preparing or matching.

Source: lib/match-cache.x:360

MatchCache.try_match

int MatchCache.try_match( MatchCache cache, List input, Var pattern, List &?out_bindings, const char *owner)

Matches through cache, writing bindings on success. out_bindings must be nonnull. Returns 0 and leaves it unchanged for a miss, malformed pattern, cache pressure, or machine error. Successful binding shape and order follow MatchPlan.execute.

Raises: <size-limit> for an ineligible pattern, or <alloc-fail> while preparing, materializing, or publishing.

Source: lib/match-cache.x:374

MatchCache.try_match_replace

int MatchCache.try_match_replace( MatchCache cache, List input, Var pattern, Var template, Var &?out, const char *owner)

Match-replaces through cache, writing the replacement on success. out must be nonnull. Returns 0 and leaves it unchanged on a miss, malformed pattern, cache pressure, or machine error. The successful result may be any Var.

Raises: <size-limit> for an ineligible pattern, or <alloc-fail> while preparing, materializing, or replacing.

Source: lib/match-cache.x:420

MatchCache.try_search

int MatchCache.try_search( MatchCache cache, List input, Var pattern, Var &?out_match, List &?out_bindings, const char *owner)

Searches through cache, writing the first match and bindings. Both outputs must be nonnull. Returns 0 and leaves them unchanged on a miss, malformed pattern, cache pressure, or machine error. Traversal order follows MatchPlan.try_search.

Raises: <size-limit> for an ineligible pattern, or <alloc-fail> while preparing or constructing bindings.

Source: lib/match-cache.x:388

MatchLease

MatchLease.release

void MatchLease.release(MatchLease *lease)

Releases the prepared program held by lease. Releasing an inactive lease has no effect. A successful release destroys a transient plan or unpins its cached entry and makes the lease inactive.

Raises: <bad-arg> when lease is NULL and <bad-state> when its cache or entry state is inconsistent. The failure leaves the lease active.

Source: lib/match-cache.x:299

Public types

MatchCache

typedef struct MatchCache *MatchCache

Names an explicit cache of immutable prepared Match plans. A cache is not synchronized. Its caller must serialize access, keep every admitted pattern value alive until disposal, and dispose it when no lease remains active.

Source: lib/match-cache.x:26

MatchLease

typedef struct MatchLease { MatchCache cache; MatchPlan transient_plan; unsigned long generation; int slot, active; } MatchLease

Represents one acquired use of a cached or transient Match plan. A cached lease pins its entry; a transient lease owns its plan. Initialize it only through MatchCache.acquire and call MatchLease.release on every exit after acquisition returns, including a pressure result.

Source: lib/match-cache.x:33

Design notes

A MatchCache keeps immutable prepared plans under the canonical identity of their patterns and lends them through leases. The List.match family runs through the active default cache, which is Context-local while a Context is open and otherwise thread-local.

Tests and examples

make verify (unittest/test-match-cache.x).