mirror_php/parallel
1
0
Fork 0
mirror of https://github.com/amphp/parallel.git synced 2025-01-17 20:58:36 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs cold turkey

Browse Source
This commit is contained in:
Stephen Coakley 2016-01-17 22:02:52 -06:00
parent d0654e5909
commit ab566d08a1
1 changed files with 2 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
README.md
View File

@ -47,91 +47,10 @@ You can also manually edit `composer.json` to add this library as a project requ
## Documentation ## Documentation
Concurrent can use either process forking, processes created using `proc_open()`, or true threading to parallelize execution. Threading provides better performance and is compatible with Unix and Windows but requires ZTS (Zend thread-safe) PHP, while forking has no external dependencies but is only compatible with Unix systems. Documentation is available online at <http://icicle.io/docs>.
### Threads
Threading is a cross-platform concurrency method that is fast and memory efficient. Thread contexts take advantage of an operating system's multi-threading capabilities to run code in parallel. A spawned thread will run completely parallel to the parent thread, each with its own environment. Each thread is assigned a closure to execute when it is created, and the returned value is passed back to the parent thread. Concurrent goes for a "shared-nothing" architecture, so any variables inside the closure are local to that thread and can store any non-safe data. ## Development and Contributing
You can spawn a new thread with the `Thread::spawn()` method:
```php
use Icicle\Concurrent\Threading\Thread;
use Icicle\Coroutine;
use Icicle\Loop;
Coroutine\create(function () {
$thread = Thread::spawn(function () {
print "Hello, World!\n";
});
yield $thread->join();
});
Loop\run();
```
You can wait for a thread to finish by calling `join()`. Joining does not block the parent thread and will asynchronously wait for the child thread to finish before resolving.
### Forks
For Unix-like systems, you can create parallel execution using fork contexts. Though not as efficient as multi-threading, in some cases forking can take better advantage of some multi-core processors than threads. Fork contexts use the `pcntl_fork()` function to create a copy of the current process and run alternate code inside the new process.
Spawning and controlling forks are quite similar to creating threads. To spawn a new fork, use the `Fork::spawn()` method:
```php
use Icicle\Concurrent\Forking\Fork;
use Icicle\Coroutine;
use Icicle\Loop;
Coroutine\create(function () {
$fork = Fork::spawn(function () {
print "Hello, World!\n";
});
yield $fork->join();
});
Loop\run();
```
Calling `join()` on a fork will asynchronously wait for the forked process to terminate, similar to the `pcntl_wait()` function.
#### Synchronization with Channels
Threads and forks wouldn't be very useful if they couldn't be given any data to work on. The recommended way to share data between contexts is with a `Channel`. A channel is a low-level abstraction over local, non-blocking sockets, which can be used to pass messages and objects between two contexts. Channels are non-blocking and do not require locking. For example:
```php
use Icicle\Concurrent\Sync\Channel;
use Icicle\Concurrent\Threading\Thread;
use Icicle\Coroutine;
use Icicle\Loop;
Coroutine\create(function () {
$thread = Thread::spawn(function () {
$time = (yield $this->receive()); // Receive from the parent.
sleep($time);
yield $this->send("Hello!"); // Send to the parent.
});
yield $thread->send(3); // Send 3 to the context.
$message = (yield $thread->receive()); // Receive from the context.
yield $thread->join();
print $message . "\n";
});
Loop\run();
```
Thread and fork execution contexts include a channel to communicate with the parent and context. The channel methods `send()` and `receive()` may be invoked using `$this` within the function executed in the context and on the context object in the parent. See the example above.
#### Synchronization with Parcels
Parcels are shared containers that allow you to store context-safe data inside a shared location so that it can be accessed by multiple contexts. To prevent race conditions, you still need to access a parcel's data exclusively, but Concurrent allows you to acquire a lock on a parcel asynchronously without blocking the context execution, unlike traditional mutexes.
### Development and Contributing
Interested in contributing to Icicle? Please see our [contributing guidelines](https://github.com/icicleio/icicle/blob/master/CONTRIBUTING.md) in the [Icicle repository](https://github.com/icicleio/icicle). Interested in contributing to Icicle? Please see our [contributing guidelines](https://github.com/icicleio/icicle/blob/master/CONTRIBUTING.md) in the [Icicle repository](https://github.com/icicleio/icicle).