Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
6 / 6
100.00%
3 / 3
 CRAP
100.00%
1 / 1
LogicException
100.00%
6 / 6
100.00%
3 / 3
 3
100.00%
1 / 1
 __construct
100.00%
1 / 1
100.00%
1 / 1
 1
 forForkFromWorkerProcess
100.00%
4 / 4
100.00%
1 / 1
 1
 forWorkerWaitingOnItself
100.00%
1 / 1
100.00%
1 / 1
 1
1<?php
2
3declare(strict_types=1);
4
5/**
6 * This file is part of fast-forward/fork.
7 *
8 * This source file is subject to the license bundled
9 * with this source code in the file LICENSE.
10 *
11 * @copyright Copyright (c) 2026 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
12 * @license   https://opensource.org/licenses/MIT MIT License
13 *
14 * @see       https://github.com/php-fast-forward/fork
15 * @see       https://github.com/php-fast-forward
16 * @see       https://datatracker.ietf.org/doc/html/rfc2119
17 */
18
19namespace FastForward\Fork\Exception;
20
21/**
22 * Represents logical contract violations detected during worker orchestration.
23 *
24 * This exception type is intended for scenarios in which the caller invokes the
25 * process management API in a way that is incompatible with the expected runtime
26 * lifecycle. Such failures indicate an invalid usage pattern rather than an
27 * invalid scalar argument value.
28 *
29 * Callers MUST treat this exception as a signal of incorrect control flow or
30 * invalid process-context usage. Library code SHOULD throw this exception only
31 * when the operation is structurally invalid for the current execution state.
32 */
33 class LogicException extends \LogicException implements ForkExceptionInterface
34{
35    /**
36     * Initializes the exception with a descriptive message.
37     *
38     * This constructor is private to enforce the use of named constructors for specific
39     * logic violation scenarios, ensuring that each exception instance is created with
40     * a clear and relevant message.
41     *
42     * @param string $message
43     */
44    private function __construct(string $message)
45    {
46        parent::__construct($message);
47    }
48
49    /**
50     * Creates an exception for attempts to fork from within a worker process.
51     *
52     * A worker process MUST NOT reuse a manager instance that belongs to a parent
53     * process context for creating nested workers. If nested process management is
54     * required, the worker SHOULD instantiate a new manager within its own process.
55     *
56     * @return self a new instance describing the invalid fork attempt
57     */
58    public static function forForkFromWorkerProcess(): self
59    {
60        return new self(
61            'Forking from a worker process is not supported by this manager instance. '
62            . 'Create a new manager inside the worker to manage a nested process tree.',
63        );
64    }
65
66    /**
67     * Creates an exception for attempts by a worker to wait on itself.
68     *
69     * A worker MUST NOT attempt to block while waiting for its own termination,
70     * because such behavior would be logically invalid and would prevent correct
71     * lifecycle coordination.
72     *
73     * @param int $workerPid the process identifier of the worker attempting to wait on itself
74     *
75     * @return self a new instance describing the self-wait violation
76     */
77    public static function forWorkerWaitingOnItself(int $workerPid): self
78    {
79        return new self(\sprintf('Worker %d cannot wait on itself.', $workerPid));
80    }
81}