module Bakelite::Docs::F_CONCURRENCY::THREAD_SAFETY

Overview

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.

Defined in:

bakelite/docs/f_concurrency/thread_safety.cr

Class Method Summary

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

Class Method Detail

def self.topic_01_synchronized_io : Nil #

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).

def self.topic_02_concurrent_fiber_reads : Nil #

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.