From 9c95e37359b56d8950690c36ebb17a84e5639319 Mon Sep 17 00:00:00 2001 From: Jerome Thayananthajothy Date: Wed, 18 Dec 2024 19:52:45 +0530 Subject: [PATCH] Update README.md --- README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 51 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 9512c3c..202b067 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Matrix’s `async()` helper returns a promise-like object (thanks to `AsyncPromise`) which provides familiar `then()` and `catch()` methods, making asynchronous tasks feel as natural as JavaScript promises. --- - + ## **Why Matrix?** Matrix aims to simplify parallel execution of potentially long-running or CPU-intensive operations in PHP. Instead of waiting for each task to complete sequentially, you can spawn child processes, run tasks concurrently, and handle their results asynchronously. @@ -30,7 +30,7 @@ Matrix aims to simplify parallel execution of potentially long-running or CPU-in - **Easy integration with existing code**: Just wrap your function calls with `async()` and chain handlers as needed. --- - + ## **Installation** Install Matrix via Composer: @@ -47,7 +47,48 @@ Ensure the following PHP extensions are enabled: Matrix also relies on ReactPHP promises and event loop, installed automatically via Composer. --- + +## ⚠️ **Important Notice: Avoid Using `pcntl_fork()` in Web Server Environments** + +**Matrix PHP** leverages `pcntl_fork()` to achieve asynchronous, parallel task execution. However, it's crucial to understand the limitations and best practices when deploying Matrix PHP, especially concerning the use of `pcntl_fork()` within different server environments. + +### 🚫 **Why Avoid `pcntl_fork()` in Web Servers?** + +- **PHP Thread Safety:** + PHP is **not inherently thread-safe**. Utilizing `pcntl_fork()` within a multi-threaded web server environment, such as Apache configured with the **Worker MPM**, can lead to unpredictable behavior, resource leaks, and potential server instability. + +- **Apache Worker MPM Issues:** + Running PHP as a module in an Apache installation configured with the **Worker MPM** is **not recommended**. The **Worker MPM** uses multiple threads to handle requests, which conflicts with PHP's thread safety limitations. + +### ✅ **Recommended Setup** + +- **Use Prefork MPM with Apache:** + For a stable and compatible environment, it's advised to configure Apache with the **Prefork MPM** module when integrating with PHP. The **Prefork MPM** handles each request in a separate process rather than threads, aligning with PHP's operational model and avoiding thread safety issues. + + **References:** + - [PHP Manual: Installing PHP on Unix systems with Apache](http://php.net/install.unix.apache2.php) + - [Steve Kallestad's Guide on Apache Worker MPM with PHP](http://www.stevekallestad.com/blog/apache_worker_mpm_with_php.html) + +### 🔧 **Best Practices** + +- **Command-Line and Background Processes:** + Matrix PHP is best suited for **command-line interfaces (CLI)**, background workers, or daemonized applications where process forking is safe and manageable. + +- **Web Applications:** + For web-based deployments, prefer using **event-driven asynchronous models** provided by libraries like **ReactPHP**, which do not rely on process forking and are more compatible with typical web server configurations. + +### 🛡️ **Conclusion** +To ensure the stability, performance, and reliability of your PHP applications using **Matrix PHP**, adhere to the following guidelines: + +1. **Avoid using `pcntl_fork()` in web server contexts**, especially with multi-threaded server modules like Apache's Worker MPM. +2. **Configure Apache with Prefork MPM** when integrating with PHP to prevent thread safety issues. +3. **Leverage event-driven asynchronous approaches** (e.g., ReactPHP) for web applications to achieve concurrency without the complexities of process forking. + +By following these best practices, you can harness the full potential of **Matrix PHP** while maintaining a robust and stable server environment. + +--- + ## **Asynchronous API Inspired by JavaScript** Matrix provides a helper called `async()` that returns an `AsyncPromise`, mimicking JavaScript’s promise usage. @@ -81,7 +122,7 @@ async(fn () => throw new RuntimeException('Something went wrong')) ``` --- - + ## **Under the Hood** - **Forked Processes**: Calling `async()` triggers `AsyncProcessManager::fork()`, which spawns a new child process. This child executes your given callable in isolation. @@ -90,7 +131,7 @@ async(fn () => throw new RuntimeException('Something went wrong')) - **Promises**: The `AsyncPromise` class wraps React’s `PromiseInterface` to provide a `.then()` and `.catch()` interface, making asynchronous code more intuitive. --- - + ## **Examples** **Running Multiple Tasks in Parallel:** @@ -120,7 +161,7 @@ async(fn() => 21) ``` --- - + ## **Testing and Integration** You can write integration tests to confirm asynchronous behavior. For example, test that two half-second tasks complete in ~0.5s total, ensuring concurrency works as intended: @@ -148,7 +189,7 @@ it('runs tasks concurrently', function () { *(`awaitPromise()` is a helper test function that runs the event loop until the given promise resolves.)* --- - + ## **Common Issues and Troubleshooting** - **Sequential Execution Instead of Parallel**: @@ -161,7 +202,7 @@ it('runs tasks concurrently', function () { If the child throws an unknown exception type not autoloaded in the parent, it defaults to `RuntimeException`. Basic details (message, file, line, trace) are preserved. --- - + ## **API Reference** ### Global `async()` function @@ -185,7 +226,7 @@ function async(callable $callable): AsyncPromise Attaches an error handler (alias to React’s `otherwise()`). --- - + ## **Contributing** We welcome contributions. To contribute: @@ -197,13 +238,13 @@ We welcome contributions. To contribute: 5. Open a pull request against `main`. --- - + ## **License** Matrix is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for more information. --- - + ## **Authors** - **[Jerome Thayananthajothy]** - *Initial Work* - [Thavarshan](https://github.com/Thavarshan)