Updated readme

This commit is contained in:
Chris 2018-04-15 18:27:51 +02:00
parent 176f9aa5ec
commit 2652480c5d

View File

@ -2,26 +2,89 @@ noccylabs/ipc
=============
This is a one-size-fits-all IPC library to facilitate communication between
threads and processes. It contains the following features:
threads and processes.
**Core:**
For complete examples, see the `examples` directory in the source tree.
## Signals
- [ ] Semaphore
- [ ] Mutex
- [x] Queue
- [x] SharedMemory key-value store
- [ ] SharedMemory blocks
- [x] Signals
- [x] Locks
Asynchronous signals are automatically enabled if supported. Otherwise, the
`pcntl_signal_dispatch()` method must be frequently called from your main loop.
You can test for this using the `ASYNC_SIGNALS` constant:
**High-Level:**
if (!ASYNC_SIGNALS) {
pcntl_signal_dispatch();
}
- [ ] EventBridge
- [ ] EventDispatcher
- [ ] InterOp/Marshalling
- [x] Asynchronous timers
### Signal handlers
**Transports:**
Signal handlers allow for multiple listeners, with any one of them being able to
prevent the signal from bubbling up.
- [x] Stream channels
$handler = new SignalHandler(SIGUSR1);
$handler->addHandler(function () {
// Handle SIGUSR1, return true to stop bubbling
return true;
});
You can also handle as well as fire signals using the `Signal` class:
$signal = new Signal(SIGUSR1);
$signal->setHandler(function () {
// Handle SIGUSR1
});
// Dispatch the signal to ourselves
(new Signal(SIGUSR1))->dispatch($pid);
### Signal traps
Traps are used in the main loop to break on signals
$trap = new SignalTrap(SIGINT);
while (!$trap->isTrapped()) {
// ...
}
## Timers
Timers fire asynchronously at fixed 1 second intervals. It requires signals to be
processed; see above.
$timer = new Timer(function () {
echo ".";
});
## File locks
File locks uses a shared file as a resource for locking.
// Creating the lock will not acquire it
$lock = new FileLock(__FILE__);
if (!$lock->acquire()) {
echo "fail!\n";
} else {
$lock->release();
}
## SysV wrappers
### Semaphores
### Mutexes
### Messagae Queues
## Communication
### Channels
Channels are essentially connected pipes. A channel can be created with a stream resource,
or through the `createPair()` factory method.
[ $ch1, $ch2 ] = StreamChannel::createPair();
$ch1->send($data);
$rcvd = $ch2->receive();