C SDK: Make library thread-safe with mutex-protected allocator

[Copilot]

The C SDK had race conditions in global allocator access and was missing cleanup of the regex cache. Multiple threads calling validation functions concurrently could corrupt allocator state.

Changes

Thread-safe allocator access:

• Protected g_allocator reads/writes with pthread_mutex_t (Unix) / CRITICAL_SECTION (Windows)
• Used pthread_once / InitOnceExecuteOnce for race-free mutex initialization
• Guarded js_malloc(), js_realloc(), js_free(), js_set_allocator(), js_get_allocator()

Cleanup lifecycle:

• js_cleanup() now calls js_regex_cache_clear() to free compiled patterns
• js_init() explicitly initializes allocator mutex (optional but recommended)

Documentation:

• Added thread-safety semantics to types.h and json_structure.h
• New "Thread Safety" section in README with usage guidelines
• Documented that js_set_allocator() and js_cleanup() must not be called during validation

Testing:

• Added 5 concurrent validation tests (4-8 threads, 50-1000 iterations)
• Tests schema validation, instance validation, mixed operations, and init/cleanup lifecycle

Usage

// Initialize once before threading
js_init();

// Safe: concurrent validation from multiple threads
#pragma omp parallel for
for (int i = 0; i < 1000; i++) {
    js_result_t result;
    js_validate_instance(instance_json, schema_json, &result);
    js_result_cleanup(&result);
}

// Cleanup after all threads complete
js_cleanup();

Notes

• Regex cache (already thread-safe with std::mutex) now properly cleaned up
• One-time initialization via pthread_once persists for process lifetime
• Library can be reinitialized after js_cleanup() but pthread_once state remains

Original prompt

---

This section details on the original issue you should resolve

<issue_title>C SDK: Make library fully thread-safe</issue_title>
<issue_description>## Problem

The C SDK has thread-safety issues with global state:

Global allocator (types.c:31-36):

• g_allocator is mutable global state with no synchronization
• js_set_allocator() modifies it without locking
• js_malloc/js_realloc/js_free read it without locking

Initialization/cleanup:

• js_init_with_allocator() and js_cleanup() modify global state
• Calling these while validations are in progress causes undefined behavior
• js_cleanup() doesn't clear the regex cache

The regex cache in regex_utils.cpp IS thread-safe (uses std::mutex).

Proposed Solution

1. Protect allocator access:

   • Add mutex around g_allocator reads/writes
   • Or make allocator immutable after js_init()
   • Or use thread-local allocators

2. Fix js_cleanup():

   • Call regex_cache_clear() to clean up regex cache
   • Document that cleanup must only be called when no validations are active

3. Document thread-safety requirements:

   • js_init() must be called once before any threads start validation
   • js_set_allocator() must not be called during validation
   • js_cleanup() must be called after all validations complete

Tests to Add

• Test concurrent validation from multiple pthreads
• Test with ThreadSanitizer (TSan)
• Verify no data races with concurrent js_validate_schema/js_validate_instance calls
• Test init/cleanup lifecycle with proper ordering

Acceptance Criteria

• Concurrent validation calls are safe (with proper init/cleanup)
• ThreadSanitizer reports no races
• js_cleanup() properly cleans up all resources
• Thread safety documented in README and header comments</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes C SDK: Make library fully thread-safe #42

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.