{
    "slug": "thread_safety",
    "term": "Thread Safety",
    "category": "concurrency",
    "difficulty": "intermediate",
    "short": "Thread-safe code produces correct results regardless of how multiple threads interleave — achieved through immutability, atomic operations, or synchronisation primitives.",
    "long": "Code is thread-safe if it behaves correctly when multiple threads execute it simultaneously. Strategies: (1) Immutability — objects that cannot be modified are inherently thread-safe. (2) Thread-local storage — each thread has its own copy of mutable state. (3) Atomic operations — hardware-level indivisible read-modify-write. (4) Synchronisation — mutexes/locks. (5) Stateless design — functions with no shared state are thread-safe. In PHP: the language runtime is not thread-safe by default (ZTS — Zend Thread Safety — is a compile option). PHP-FPM uses separate processes (not threads) so most PHP code is safe. Extensions may not be ZTS-compiled. Swoole and ReactPHP introduce real concurrency within one process.",
    "aliases": [],
    "tags": [
        "concurrency",
        "thread-safety",
        "php",
        "immutability"
    ],
    "misconception": "PHP is immune to concurrency issues because it's single-threaded — PHP-FPM runs many processes concurrently, all hitting shared resources (DB, files, cache). Concurrency bugs are real.",
    "why_it_matters": "Stateless, immutable design is the most reliable path to thread safety — and also makes code easier to test and reason about.",
    "common_mistakes": [
        "Mutable static/global state in classes — shared across requests in Swoole/FrankenPHP.",
        "Assuming global state is safe in PHP-FPM — each process has its own, but shared resources (DB, Redis) still need protection.",
        "Not marking PHP extensions as ZTS-safe when using threaded PHP."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "race_condition",
        "mutex",
        "immutability",
        "atomic_operations"
    ],
    "prerequisites": [
        "race_condition",
        "mutex"
    ],
    "refs": [
        "https://www.php.net/manual/en/pthreads.requirements.php"
    ],
    "bad_code": "// Mutable static — breaks in Swoole/FrankenPHP:\nclass RequestContext {\n    private static ?User $currentUser = null;\n    public static function setUser(User $u): void { self::$currentUser = $u; }\n}",
    "good_code": "// Immutable request context — safe in all runtimes:\nclass RequestContext {\n    public function __construct(\n        public readonly User $user,\n        public readonly string $requestId,\n    ) {}\n}\n// Pass as dependency, not global static",
    "quick_fix": "Prefer immutable objects and stateless functions. Avoid static mutable state — breaks under Swoole/FrankenPHP. Protect shared resources (files, DB, cache) with locks.",
    "severity": "high",
    "effort": "medium",
    "created": "2026-03-23",
    "updated": "2026-04-05",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/thread_safety",
        "html_url": "https://codeclaritylab.com/glossary/thread_safety",
        "json_url": "https://codeclaritylab.com/glossary/thread_safety.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Thread Safety](https://codeclaritylab.com/glossary/thread_safety) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/thread_safety"
            }
        }
    }
}