134 lines
3.0 KiB
Markdown
134 lines
3.0 KiB
Markdown
noccylabs/ipc
|
|
=============
|
|
|
|
This is a one-size-fits-all IPC library to facilitate communication between
|
|
threads and processes.
|
|
|
|
For complete examples, see the `examples` directory in the source tree.
|
|
## Signals
|
|
|
|
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:
|
|
|
|
if (!ASYNC_SIGNALS) {
|
|
pcntl_signal_dispatch();
|
|
}
|
|
|
|
### Signal handlers
|
|
|
|
Signal handlers allow for multiple listeners, with any one of them being able to
|
|
prevent the signal from bubbling up.
|
|
|
|
$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.
|
|
|
|
// Once every second...
|
|
$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
|
|
|
|
All these wrappers depend on a `KeyInterface` being passed to the constructor.
|
|
This is usually an instance of a `FileKey`, created as such:
|
|
|
|
$key = new FileKey(__FILE__);
|
|
|
|
The key has a project identifier that starts at `chr(0)`, or `"\0"`. To increase
|
|
this identifier, and thus point to another segment, just clone it.
|
|
|
|
$key2 = clone $key1;
|
|
|
|
### Semaphores
|
|
|
|
### Mutexes
|
|
|
|
### Message Queues
|
|
|
|
$key = new FileKey(__FILE__);
|
|
$msgq = new Queue($key);
|
|
|
|
$msgq->send(1, [ "Some data", [ "format"=>"foo" ]]);
|
|
|
|
$data = $msgq->receive(1, $type);
|
|
|
|
$msgq->destroy();
|
|
|
|
### Shared Memory
|
|
|
|
Shared memory using `SharedData` supports integrity checking when setting, using
|
|
the third parameter to `set()`.
|
|
|
|
$key = new FileKey(__FILE__);
|
|
$shm = new SharedData($key);
|
|
|
|
do {
|
|
$counter = $shm->get("counter") + 1;
|
|
} while (!$shm->set("counter", $counter, true));
|
|
|
|
$shm->destroy();
|
|
|
|
The `SharedMemory` class is a simple integer-indexed array
|
|
|
|
$key = new FileKey(__FILE__);
|
|
$shm = new SharedMemory($key);
|
|
|
|
$shm[0] = 42;
|
|
|
|
$shm->destroy();
|
|
|
|
## 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();
|