libsnobol4 1.0.2
High-performance SNOBOL4-style pattern matching library
Loading...
Searching...
No Matches
dynamic_pattern.h File Reference

Dynamic pattern objects and canonical cache keys. More...

#include <stdbool.h>
#include "snobol/c23_compat.h"
#include <stddef.h>
#include <stdint.h>
Include dependency graph for dynamic_pattern.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  dynamic_pattern
struct  dynamic_pattern_cache_key_t
struct  dynamic_pattern_cache_entry
struct  dynamic_pattern_cache_t

Typedefs

typedef struct snobol_table snobol_table_t
 Associative table (opaque handle).
typedef struct dynamic_pattern dynamic_pattern_t
typedef struct dynamic_pattern_cache_entry dynamic_pattern_cache_entry_t

Functions

dynamic_pattern_t * dynamic_pattern_create (const char *source, uint8_t *bc, size_t bc_len)
 Create a new dynamic pattern object.
dynamic_pattern_t * dynamic_pattern_retain (dynamic_pattern_t *pattern)
 Increment dynamic pattern reference count.
void dynamic_pattern_release (dynamic_pattern_t *pattern)
 Decrement reference count and free if zero.
const dynamic_pattern_cache_key_t * dynamic_pattern_compute_key (const char *source, size_t source_len, dynamic_pattern_cache_key_t *out_key)
 Compute canonical cache key from source string.
bool dynamic_pattern_cache_init (dynamic_pattern_cache_t *cache, size_t max_size)
 Initialize dynamic pattern cache.
void dynamic_pattern_cache_destroy (dynamic_pattern_cache_t *cache)
 Destroy cache and free all entries.
dynamic_pattern_t * dynamic_pattern_cache_get (dynamic_pattern_cache_t *cache, const char *source, int source_len)
 Look up a pattern in the cache.
bool dynamic_pattern_cache_put (dynamic_pattern_cache_t *cache, const char *source, dynamic_pattern_t *pattern)
 Insert a pattern into the cache.
bool dynamic_pattern_cache_remove (dynamic_pattern_cache_t *cache, const char *source, int source_len)
 Remove a pattern from the cache.
void dynamic_pattern_cache_clear (dynamic_pattern_cache_t *cache)
 Clear all entries from the cache.
void dynamic_pattern_cache_stats (const dynamic_pattern_cache_t *cache, size_t *out_size, size_t *out_max)
 Get cache statistics.
uint32_t dynamic_pattern_hash_source (const char *source, size_t len)
 Hash function for pattern sources.

Detailed Description

Dynamic pattern objects and canonical cache keys.

Ownership/Lifetime Rules:

  • Dynamic patterns are created with dynamic_pattern_create() and freed with dynamic_pattern_release()
  • Dynamic patterns use reference counting for safe sharing
  • The compiled bytecode is owned by the dynamic pattern object
  • Cache entries hold references to dynamic patterns (via retain/release)
  • Canonical keys are computed from pattern content for cache lookup

Retain/Release Semantics:

Cache Ownership Rules:

Execution Lifecycle (VM):

  1. OP_DYNAMIC_DEF: Stores source text and bytecode (both owned by VM)
  2. OP_DYNAMIC cache miss: Creates pattern, caches it (cache retains reference)
  3. OP_DYNAMIC cache hit: Retrieves pattern (caller retains reference)
  4. Pattern execution: Uses pattern bytecode (pattern not modified)
  5. After execution: Caller releases their reference (cache retains its reference)

Success Path:

  • Cache miss: create() → put() [cache retains] → execute → release() [caller's ref]
  • Cache hit: get() [retains for caller] → execute → release() [caller's ref]

Failure Path:

  • Cache miss with create failure: No pattern created, no cache entry
  • Cache hit with execution failure: release() caller's reference, restore VM state

Definition in file dynamic_pattern.h.

Typedef Documentation

◆ dynamic_pattern_cache_entry_t

Dynamic pattern cache entry

◆ dynamic_pattern_t

Dynamic pattern object

Represents a pattern that was compiled at runtime from a string or AST. The bytecode is owned by this object and freed when refcount reaches 0.

◆ snobol_table_t

typedef struct snobol_table snobol_table_t

Associative table (opaque handle).

Runtime-owned string-keyed hash table for table-backed substitutions.

Definition at line 65 of file dynamic_pattern.h.

Function Documentation

◆ dynamic_pattern_cache_clear()

void dynamic_pattern_cache_clear ( dynamic_pattern_cache_t * cache)

Clear all entries from the cache.

Parameters
cacheCache to clear

◆ dynamic_pattern_cache_destroy()

void dynamic_pattern_cache_destroy ( dynamic_pattern_cache_t * cache)

Destroy cache and free all entries.

Parameters
cacheCache to destroy

◆ dynamic_pattern_cache_get()

dynamic_pattern_t * dynamic_pattern_cache_get ( dynamic_pattern_cache_t * cache,
const char * source,
int source_len )

Look up a pattern in the cache.

Parameters
cacheCache to query
sourceSource string
source_lenLength of source (or -1 for strlen)
Returns
Cached pattern (reference retained), or NULL if not found

Ownership: Caller must call dynamic_pattern_release() when done

◆ dynamic_pattern_cache_init()

bool dynamic_pattern_cache_init ( dynamic_pattern_cache_t * cache,
size_t max_size )

Initialize dynamic pattern cache.

Parameters
cacheCache to initialize
max_sizeMaximum entries before eviction (0 = default)
Returns
true on success

◆ dynamic_pattern_cache_put()

bool dynamic_pattern_cache_put ( dynamic_pattern_cache_t * cache,
const char * source,
dynamic_pattern_t * pattern )

Insert a pattern into the cache.

Parameters
cacheCache to modify
sourceSource string (copied)
patternPattern to cache (reference retained)
Returns
true on success, false on allocation failure or cache full

Ownership: Cache retains its own reference to the pattern

◆ dynamic_pattern_cache_remove()

bool dynamic_pattern_cache_remove ( dynamic_pattern_cache_t * cache,
const char * source,
int source_len )

Remove a pattern from the cache.

Parameters
cacheCache to modify
sourceSource string to remove
source_lenLength of source (or -1 for strlen)
Returns
true if pattern was found and removed

◆ dynamic_pattern_cache_stats()

void dynamic_pattern_cache_stats ( const dynamic_pattern_cache_t * cache,
size_t * out_size,
size_t * out_max )

Get cache statistics.

Parameters
cacheCache to query
out_sizeOutput: current number of entries
out_maxOutput: maximum entries

◆ dynamic_pattern_compute_key()

const dynamic_pattern_cache_key_t * dynamic_pattern_compute_key ( const char * source,
size_t source_len,
dynamic_pattern_cache_key_t * out_key )

Compute canonical cache key from source string.

Parameters
sourceSource string
source_lenLength of source (or -1 for strlen)
out_keyOutput: cache key structure
Returns
Pointer to cache key (valid while source is valid)

◆ dynamic_pattern_create()

dynamic_pattern_t * dynamic_pattern_create ( const char * source,
uint8_t * bc,
size_t bc_len )

Create a new dynamic pattern object.

Parameters
sourceSource string (copied)
bcCompiled bytecode (ownership transferred)
bc_lenLength of bytecode
Returns
Pointer to new dynamic pattern, or NULL on failure

Ownership: Caller owns the returned pattern and must call dynamic_pattern_release() The bytecode pointer is adopted by the pattern (do not free separately)

◆ dynamic_pattern_hash_source()

uint32_t dynamic_pattern_hash_source ( const char * source,
size_t len )

Hash function for pattern sources.

Parameters
sourceSource string
lenLength of source
Returns
32-bit hash value

◆ dynamic_pattern_release()

void dynamic_pattern_release ( dynamic_pattern_t * pattern)

Decrement reference count and free if zero.

Parameters
patternPattern to release

◆ dynamic_pattern_retain()

dynamic_pattern_t * dynamic_pattern_retain ( dynamic_pattern_t * pattern)

Increment dynamic pattern reference count.

Parameters
patternPattern to retain
Returns
Same pattern pointer for convenience