Wrote README.md
This commit is contained in:
netkas
parent
18a9dfbb64
commit
27be29af5b
1 changed files with 407 additions and 0 deletions
407
README.md
407
README.md
|
|
@ -0,0 +1,407 @@
|
|||
# PsyncLib
|
||||
|
||||
PsyncLib (`net.nosial.psynclib`) is a PHP library that introduces parallel operations into PHP without the need for
|
||||
additional software such as a Message Queue or a Job Queue. Using Shared Memory & Forking, PsyncLib allows you to
|
||||
create parallel operations by calling several simple functions.
|
||||
|
||||
## Table of contents
|
||||
|
||||
<!-- TOC -->
|
||||
* [PsyncLib](#psynclib)
|
||||
* [Table of contents](#table-of-contents)
|
||||
* [Versioning](#versioning)
|
||||
* [Installation](#installation)
|
||||
* [Usage](#usage)
|
||||
* [Classes](#classes)
|
||||
* [P](#p)
|
||||
* [Psync](#psync)
|
||||
* [public static function do(callable $callable, array $args = []): P](#public-static-function-docallable-callable-array-args---p)
|
||||
* [public static function isDone(P $p): bool](#public-static-function-isdonep-p-bool)
|
||||
* [public static function waitFor(P $p): mixed](#public-static-function-waitforp-p-mixed)
|
||||
* [private static function close(P $p): void](#private-static-function-closep-p-void)
|
||||
* [public static function wait(): array](#public-static-function-wait-array)
|
||||
* [public static function total(): int](#public-static-function-total-int)
|
||||
* [public static function running(): int](#public-static-function-running-int)
|
||||
* [public static function clean(): int](#public-static-function-clean-int)
|
||||
* [public static function getSharedMemorySize(): int](#public-static-function-getsharedmemorysize-int)
|
||||
* [public static function setSharedMemorySize(int $sharedMemorySize): void](#public-static-function-setsharedmemorysizeint-sharedmemorysize-void)
|
||||
* [public static function getSharedMemoryPermissions(): int](#public-static-function-getsharedmemorypermissions-int)
|
||||
* [public static function setSharedMemoryPermissions(int $sharedMemoryPermissions): void](#public-static-function-setsharedmemorypermissionsint-sharedmemorypermissions-void)
|
||||
* [License](#license)
|
||||
* [Contributing](#contributing)
|
||||
<!-- TOC -->
|
||||
|
||||
|
||||
## Versioning
|
||||
|
||||
This library uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
To install PsyncLib, you can use [ncc](https://git.n64.cc/nosial/ncc). (can also be found at [github](https://github.com/nosial/ncc))
|
||||
Run the following command:
|
||||
|
||||
```bash
|
||||
ncc package install -p="nosial/libs.psync=latest@n64"
|
||||
```
|
||||
|
||||
To add the package as a dependency to your project, add this entry under `build{} -> dependencies[]` in your
|
||||
`project.json` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "net.nosial.psynclib",
|
||||
"version": "latest",
|
||||
"source_type": "remote",
|
||||
"source": "nosial/libs.psync=latest@n64"
|
||||
}
|
||||
```
|
||||
|
||||
The GitHub alternative name is `nosial/psynclib=latest@github` if you prefer to use GitHub as the source.
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
Psync is called under the namespace `\PsyncLib\Psync`. The following is an example of how to use Psync to calculate
|
||||
the value of Pi using the Monte Carlo method in parallel using 4 processes, this will display the value of Pi and the
|
||||
time taken to calculate it per process and finally the total time in total the script took to run.
|
||||
|
||||
```php
|
||||
<?php
|
||||
// Require ncc, this is required to load the PsyncLib package
|
||||
require 'ncc';
|
||||
|
||||
// Import the Psync package (Not needed if the project references the package as a dependency)
|
||||
import('net.nosial.psynclib');
|
||||
|
||||
// Begin the fun
|
||||
$parentStart = microtime(true);
|
||||
|
||||
$promises = [];
|
||||
for($i = 0; $i < 10; $i++) {
|
||||
$promises[] = \PsyncLib\Psync::do(function() {
|
||||
$start = microtime(true);
|
||||
$pi = 0;
|
||||
$n = 1000000;
|
||||
for($i = 1; $i < $n; $i++) {
|
||||
$pi += 4 * (pow(-1, $i + 1) / (2 * $i - 1));
|
||||
}
|
||||
$end = microtime(true);
|
||||
return ['result' => $pi, 'time' => $end - $start];
|
||||
});
|
||||
}
|
||||
|
||||
// Wait for all promises to resolve
|
||||
/** @var \PsyncLib\P $p */
|
||||
foreach($promises as $p) {
|
||||
$result = \PsyncLib\Psync::waitFor($p);
|
||||
printf("Result: %f, Time: %f\n", $result['result'], $result['time']);
|
||||
}
|
||||
|
||||
$parentEnd = microtime(true);
|
||||
printf("Parent Time: %f\n", $parentEnd - $parentStart);
|
||||
```
|
||||
|
||||
Running this on a test machine, the output will be similar to the following:
|
||||
|
||||
```
|
||||
Result: 3.141594, Time: 2.113697
|
||||
Result: 3.141594, Time: 2.370120
|
||||
Result: 3.141594, Time: 2.043246
|
||||
Result: 3.141594, Time: 2.124459
|
||||
Result: 3.141594, Time: 2.245291
|
||||
Result: 3.141594, Time: 2.309868
|
||||
Result: 3.141594, Time: 2.163053
|
||||
Result: 3.141594, Time: 2.375659
|
||||
Result: 3.141594, Time: 2.360129
|
||||
Result: 3.141594, Time: 2.006329
|
||||
Parent Time: 2.390980
|
||||
```
|
||||
|
||||
|
||||
## Classes
|
||||
|
||||
Psync is a very lightweight library, it only has 2 classes:
|
||||
|
||||
### P
|
||||
|
||||
The `P` class is a simple class that represents a promise, it is used to store the state of the promise, the object
|
||||
itself should be treated as a reference, it has contains no actual functionality.
|
||||
|
||||
- `public function getUuid(): string` - Returns the UUID of the promise
|
||||
- `public function getPid(): int` - Returns the PID of the process
|
||||
- `public function getShm(): Shmop` - Returns the Shared Memory object
|
||||
- `public function __toString(): string` - Returns the UUID of the promise
|
||||
|
||||
|
||||
### Psync
|
||||
|
||||
The `Psync` class is the main class used to interact with the Psync Library
|
||||
|
||||
|
||||
#### public static function do(callable $callable, array $args = []): P
|
||||
|
||||
This method creates a new promise by forking a process to execute the given callable function.
|
||||
The result of the callable is stored in shared memory and can be retrieved later.
|
||||
|
||||
- **Parameters:**
|
||||
- `callable $callable`: The function to be executed in the forked process.
|
||||
- `array $args`: An optional array of arguments to pass to the callable.
|
||||
|
||||
- **Returns:**
|
||||
- `P`: An instance of the `P` class representing the promise.
|
||||
|
||||
- **Throws:**
|
||||
- `RuntimeException`: If the shared memory segment or the process fork fails.
|
||||
|
||||
Usage Example:
|
||||
|
||||
```php
|
||||
<?php
|
||||
$p = \PsyncLib\Psync::do(function() {
|
||||
return 'Hello, World!';
|
||||
});
|
||||
|
||||
// Wait for the promise to resolve
|
||||
$result = \PsyncLib\Psync::waitFor($p);
|
||||
echo $result; // Output: Hello, World!
|
||||
```
|
||||
|
||||
|
||||
#### public static function isDone(P $p): bool
|
||||
|
||||
This method checks if the given promise has completed its execution.
|
||||
|
||||
- **Parameters:**
|
||||
- `P $p`: The promise instance to check.
|
||||
|
||||
- **Returns:**
|
||||
- `bool`: `true` if the promise has completed, `false` otherwise.
|
||||
|
||||
- **Throws:**
|
||||
- `RuntimeException`: If there is an error while checking the process status.
|
||||
|
||||
Usage Example:
|
||||
|
||||
```php
|
||||
<?php
|
||||
$p = \PsyncLib\Psync::do(function() {
|
||||
return 'Hello, World!';
|
||||
});
|
||||
|
||||
// Check if the promise has completed
|
||||
if (\PsyncLib\Psync::isDone($p)) {
|
||||
echo 'Promise is done!';
|
||||
} else {
|
||||
echo 'Promise is still running...';
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
#### public static function waitFor(P $p): mixed
|
||||
|
||||
This method waits for the given promise to complete and retrieves the result stored in shared memory.
|
||||
|
||||
- **Parameters:**
|
||||
- `P $p`: The promise instance containing details about the process to wait for.
|
||||
|
||||
- **Returns:**
|
||||
- `mixed`: The result retrieved from the shared memory, which may throw an exception if an error occurred within the process.
|
||||
|
||||
- **Throws:**
|
||||
- `Throwable`: If the result is an exception, it will be thrown.
|
||||
|
||||
Usage Example:
|
||||
|
||||
```php
|
||||
<?php
|
||||
$p = \PsyncLib\Psync::do(function() {
|
||||
return 'Hello, World!';
|
||||
});
|
||||
|
||||
// Wait for the promise to resolve
|
||||
$result = \PsyncLib\Psync::waitFor($p);
|
||||
echo $result; // Output: Hello, World!
|
||||
```
|
||||
|
||||
|
||||
#### private static function close(P $p): void
|
||||
|
||||
This method closes and cleans up resources associated with the given process.
|
||||
|
||||
- **Parameters:**
|
||||
- `P $p`: The process instance to be closed.
|
||||
|
||||
- **Returns:**
|
||||
- `void`
|
||||
|
||||
Usage Example:
|
||||
|
||||
```php
|
||||
<?php
|
||||
$p = \PsyncLib\Psync::do(function() {
|
||||
return 'Hello, World!';
|
||||
});
|
||||
|
||||
// Close the process and clean up resources
|
||||
\PsyncLib\Psync::close($p);
|
||||
```
|
||||
|
||||
|
||||
#### public static function wait(): array
|
||||
|
||||
This method waits for the completion of all promises and returns their results.
|
||||
|
||||
- **Returns:**
|
||||
- `array`: An associative array containing the results of each promise, indexed by their unique identifiers (UUIDs).
|
||||
|
||||
- **Throws:**
|
||||
- `Throwable`: If any of the promises throw an exception, it will be thrown.
|
||||
|
||||
Usage Example:
|
||||
|
||||
```php
|
||||
<?php
|
||||
$promises = [];
|
||||
for($i = 0; $i < 10; $i++) {
|
||||
$promises[] = \PsyncLib\Psync::do(function() {
|
||||
return 'Hello, World!';
|
||||
});
|
||||
}
|
||||
|
||||
// Wait for all promises to resolve
|
||||
$results = \PsyncLib\Psync::wait();
|
||||
foreach($results as $uuid => $result) {
|
||||
echo "UUID: $uuid, Result: $result\n";
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
#### public static function total(): int
|
||||
|
||||
This method calculates the total number of promises.
|
||||
|
||||
- **Returns:**
|
||||
- `int`: The total number of promises.
|
||||
|
||||
Usage Example:
|
||||
|
||||
```php
|
||||
<?php
|
||||
$totalPromises = \PsyncLib\Psync::total();
|
||||
echo "Total Promises: $totalPromises\n";
|
||||
```
|
||||
|
||||
|
||||
#### public static function running(): int
|
||||
|
||||
This method counts and returns the number of promises that are currently running.
|
||||
|
||||
- **Returns:**
|
||||
- `int`: The number of running promises.
|
||||
|
||||
Usage Example:
|
||||
|
||||
```php
|
||||
<?php
|
||||
$runningPromises = \PsyncLib\Psync::running();
|
||||
echo "Running Promises: $runningPromises\n";
|
||||
```
|
||||
|
||||
|
||||
#### public static function clean(): int
|
||||
|
||||
This method cleans up resources associated with promises that are not completed.
|
||||
|
||||
Iterates through a collection of promises, and for each promise that is not yet marked as done, calls a method to close and clean up the resource.
|
||||
|
||||
- **Returns:**
|
||||
- `int`: The number of promises that were closed and cleaned up.
|
||||
|
||||
Usage Example:
|
||||
|
||||
```php
|
||||
<?php
|
||||
$cleanedPromises = \PsyncLib\Psync::clean();
|
||||
echo "Cleaned Promises: $cleanedPromises\n";
|
||||
```
|
||||
|
||||
|
||||
#### public static function getSharedMemorySize(): int
|
||||
|
||||
This method returns the size of the shared memory.
|
||||
|
||||
- **Returns:**
|
||||
- `int`: The size of the shared memory.
|
||||
|
||||
Usage Example:
|
||||
|
||||
```php
|
||||
<?php
|
||||
$sharedMemorySize = \PsyncLib\Psync::getSharedMemorySize();
|
||||
echo "Shared Memory Size: $sharedMemorySize\n";
|
||||
```
|
||||
|
||||
|
||||
#### public static function setSharedMemorySize(int $sharedMemorySize): void
|
||||
|
||||
This method sets the size of the shared memory.
|
||||
|
||||
- **Parameters:**
|
||||
- `int $sharedMemorySize`: The new size for the shared memory.
|
||||
|
||||
- **Returns:**
|
||||
- `void`
|
||||
|
||||
Usage Example:
|
||||
|
||||
```php
|
||||
<?php
|
||||
\PsyncLib\Psync::setSharedMemorySize(1024);
|
||||
echo "Shared Memory Size set to 1024\n";
|
||||
```
|
||||
|
||||
|
||||
#### public static function getSharedMemoryPermissions(): int
|
||||
|
||||
This method returns the permissions of the shared memory.
|
||||
|
||||
- **Returns:**
|
||||
- `int`: The permissions of the shared memory.
|
||||
|
||||
Usage Example:
|
||||
|
||||
```php
|
||||
<?php
|
||||
$sharedMemoryPermissions = \PsyncLib\Psync::getSharedMemoryPermissions();
|
||||
echo "Shared Memory Permissions: $sharedMemoryPermissions\n";
|
||||
```
|
||||
|
||||
|
||||
#### public static function setSharedMemoryPermissions(int $sharedMemoryPermissions): void
|
||||
|
||||
This method sets the permissions for the shared memory.
|
||||
|
||||
- **Parameters:**
|
||||
- `int $sharedMemoryPermissions`: The permissions to be set for the shared memory.
|
||||
|
||||
- **Returns:**
|
||||
- `void`
|
||||
|
||||
Usage Example:
|
||||
|
||||
```php
|
||||
<?php
|
||||
\PsyncLib\Psync::setSharedMemoryPermissions(0666);
|
||||
echo "Shared Memory Permissions set to 0666\n";
|
||||
```
|
||||
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
|
||||
|
||||
## Contributing
|
||||
|
||||
Feel free to contribute to this project by submitting a pull request or opening an issue.
|
||||
Loading…
Add table
Reference in a new issue