Updated readme

README.md

@@ -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
+Asynchronous signals are automatically enabled if supported. Otherwise, the
- - [ ] Mutex
+`pcntl_signal_dispatch()` method must be frequently called from your main loop.
- - [x] Queue
+You can test for this using the `ASYNC_SIGNALS` constant:
- - [x] SharedMemory key-value store
- - [ ] SharedMemory blocks
- - [x] Signals
- - [x] Locks
 
-**High-Level:**
+    if (!ASYNC_SIGNALS) {
+        pcntl_signal_dispatch();
+    }
 
- - [ ] EventBridge
+### Signal handlers
- - [ ] EventDispatcher
- - [ ] InterOp/Marshalling
- - [x] Asynchronous timers
 
-**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();