{
    "slug": "coroutines",
    "term": "Coroutines — Cooperative Multitasking",
    "category": "concurrency",
    "difficulty": "advanced",
    "short": "Functions that explicitly yield control — enabling concurrent I/O without threads, where code decides when to pause rather than being preemptively interrupted.",
    "long": "Coroutines pause at explicit yield points and resume from the same point later. Unlike threads (preemptive — OS interrupts at any time), coroutines yield explicitly (cooperative — code decides when to pause). PHP 8.1 Fibers implement stackful coroutines. Coroutines enable concurrent I/O without threads: Fiber A waits for a DB query → suspends → Fiber B makes an HTTP request → suspends → Fiber A resumes when the DB responds. The event loop schedules which coroutine runs next.",
    "aliases": [
        "coroutine",
        "cooperative multitasking",
        "Fiber PHP",
        "green thread"
    ],
    "tags": [
        "concurrency",
        "php",
        "async"
    ],
    "misconception": "Coroutines provide parallelism — coroutines provide concurrency (interleaved execution on one CPU) not parallelism (simultaneous execution on multiple CPUs); two coroutines still run on one core.",
    "why_it_matters": "10,000 coroutines use the same memory as 100 threads — enabling high-concurrency PHP services without the overhead of process or thread-per-request models.",
    "common_mistakes": [
        "Blocking I/O inside coroutines — blocks the entire event loop",
        "Expecting CPU parallelism from coroutines — use processes for that",
        "Not propagating cancellation when parent coroutine is cancelled",
        "Stack overflows in deeply recursive stackful coroutines"
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "fibers",
        "php_fiber_scheduler",
        "php_async_frameworks",
        "php_concurrency_options"
    ],
    "prerequisites": [
        "fibers",
        "php_concurrency_options",
        "async_vs_parallel"
    ],
    "refs": [
        "https://www.php.net/manual/en/class.fiber.php"
    ],
    "bad_code": "// Blocking I/O — all other Fibers wait:\n$fiber = new Fiber(function(): void {\n    $data = file_get_contents('https://api.example.com'); // BLOCKS!\n    // During this HTTP wait, no other Fiber can run\n    echo $data;\n});",
    "good_code": "// Non-blocking with explicit yield:\n$fiber = new Fiber(function() use ($httpClient): void {\n    $promise = $httpClient->getAsync('https://api.example.com');\n    $result  = Fiber::suspend($promise); // Yield control — event loop runs others\n    echo $result; // Resume here when the response arrives\n});",
    "quick_fix": "In PHP 8.1+, Fibers are coroutines — use them via an async framework (Amp v3, ReactPHP) rather than directly; in Python/JavaScript, use async/await which compiles to coroutines",
    "severity": "medium",
    "effort": "high",
    "created": "2026-03-16",
    "updated": "2026-04-05",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/coroutines",
        "html_url": "https://codeclaritylab.com/glossary/coroutines",
        "json_url": "https://codeclaritylab.com/glossary/coroutines.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": "[Coroutines — Cooperative Multitasking](https://codeclaritylab.com/glossary/coroutines) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/coroutines"
            }
        }
    }
}