module

Bakelite::Docs::F_CONCURRENCY::THREAD_SAFETY

Concurrency and Thread Safety

In modern games and web servers, multiple fibers or background OS threads frequently query virtual assets concurrently. Bakelite provides robust concurrency protections ensuring safe, race-free operation.

Executive Summary & Key Topics

Topic Method / Anchor Description
Synchronized Container IO .topic_01_synchronized_io Atomic seek-and-read protection for shared container file handles.
Multi-Fiber Parallel Execution .topic_02_concurrent_fiber_reads Concurrency patterns verified by automated test suites.

Class methods

topic_01_synchronized_io

Synchronized Container IO: Atomic seek-and-read protection for shared container file handles.

When a .bkl container or executable overlay is mounted at runtime via Container::Reader, the underlying container file is wrapped in Bakelite::SynchronizedIO.

SynchronizedIO protects all file pointer seeking and chunk extraction through an internal Thread::Mutex. When multiple concurrent fibers open different (or identical) files within the container, each chunk read executes atomically via read_at(offset, slice).

Source
topic_02_concurrent_fiber_reads

Multi-Fiber Parallel Execution: Concurrency patterns verified by automated test suites.

The Bakelite concurrency test suite (spec/concurrency_spec.cr) stress-tests 30 concurrent fibers simultaneously seeking and streaming from the same container:

  • Fibers can seek to arbitrary positions simultaneously without corrupting neighbor streams.
  • Each FileIO maintains its own independent sliding active chunk and position pointer.
  • Clean resource release upon stream closure.
Source