From 2652480c5d7d15b92046751dbf1d54e34845238f Mon Sep 17 00:00:00 2001
From: Christopher Vagnetoft <cvagnetoft@gmail.com>
Date: Sun, 15 Apr 2018 18:27:51 +0200
Subject: [PATCH] Updated readme

---
 README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 80 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index a2261e8..7491743 100644
--- a/README.md
+++ b/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
- - [ ] 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
- 
\ No newline at end of file
+    $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();