From 62ec306fa8e585f7e4d16c1533bc645571cdf606 Mon Sep 17 00:00:00 2001
From: xdrm-brackets <doowap31@gmail.com>
Date: Tue, 6 Feb 2018 10:35:10 +0100
Subject: [PATCH] upd: 'README.md' -> added 'master' and 'pool'

---
 README.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 103 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 5226940..c32d0b5 100644
--- a/README.md
+++ b/README.md
@@ -33,17 +33,17 @@ bound_pid="`cat /tmp/get_bg_pid`";
 # 3. Now the socket is listening, you can read every 1 sec
 while true; do
 
-	# 3.1. Read received data from port 9999
-	message="`read input1`";
+    # 3.1. Read received data from port 9999
+    message="`read input1`";
 
-	# 3.2. Ignore empty messages
-	[[ -z "$message" ]] && sleep 1 && continue;
+    # 3.2. Ignore empty messages
+    [[ -z "$message" ]] && sleep 1 && continue;
 
-	# 3.3. Exit while() loop if received "END"
-	[[ "$message" = "END" ]] && break;
+    # 3.3. Exit while() loop if received "END"
+    [[ "$message" = "END" ]] && break;
 
-	# 3.4. Wait 1 sec
-	sleep 1;
+    # 3.4. Wait 1 sec
+    sleep 1;
 
 done;
 
@@ -146,4 +146,99 @@ Let's say you want to execute a long command (sleep 5), then send the trigger to
 
 ```bash
 sleep 5; trigger-send somekey123 192.168.0.2 9999;
+```
+
+
+## 4. Daemon pool
+
+This package includes a purpose-specific implementation:
+- `master` pushes a pool of daemons (infinite scripts echoing things over time) bound to a pool receiver.
+- `pool` waits for daemons to be started to bind input buffers.
+
+### Pool receiver
+
+The `pool` commands allows you to wait for daemons on a port.
+
+```bash
+pool $key $port
+```
+
+*Arguments:*
+- `$key` is the key for the pool receiver, the _master_ must match it in order for the communication to be validated.
+- `$port` is the number of the local port to listen on (between 1024 and 49151).
+
+*Execution:*
+1. Waits for incoming _daemon_request_ from `master` (asks for binding an input for a daemon). If  the *END message* is received, stop listening and wait for background bindings to stop.
+2. For each daemon, open a free port (`bind-input` in background), then return its number to the `master`
+
+*Signals:*
+- If one of these signals: SIGHUP, SIGTERM, SIGINT is received, all processes, sockets and background routines will be properly (recursively) stopped.
+- You **must avoid SIGKILL**, because nothing can be triggered (by definition), so all sockets and binding will remain active.
+
+
+### Pool creator (master)
+
+The `master` commands allows you to bind daemons output to another machine.
+
+```bash
+master $key $host $port $ddir
+```
+
+*Arguments:*
+- `$key` is the key for the pool receiver, if it does not match, it won't work.
+- `$host` is the hostname (IP addr. or resolvable) of the machine powering the `pool` receiver.
+- `$port` is the number of the remote port the pool is listening on (between 1024 and 49151).
+- `$ddir` is the directory containing the daemon files (must be executable).
+
+*Execution:*
+1. Send _daemon_request_ for each daemon, when open port received, start daemon in background bound to output on `$host`
+2. Send the *END message*
+3. Wait for daemons and output to end
+
+*Signals:*
+- If one of these signals: SIGHUP, SIGTERM, SIGINT is received, all processes, sockets and background routines will be properly (recursively) stopped.
+- You **must avoid SIGKILL**, because nothing can be triggered (by definition), so all sockets and binding will remain active.
+
+
+
+
+*Exemple master-pool:*
+
+Let's say the master has 2 daemons: _dem1_ and _dem2_. Both contains a while loop echoing something each second. In this example, the key is "**k12**".
+
+```
+                   ip:      ipM                      ip:      ipP
+                   listen:  pM                       listen:  pP
+
+                   +--------+                        +--------+
+                   | master |                        |  pool  |
+                   +--------+                        +--------+
+                       |                                 |
+               ________|________                   ______|_______
+              /                 \                 /              \
+             | connect to ipP:pP | =============> | listen on pP |
+              \_________________/                 \______________/
+                       |                                 |
+                      ...                               ...
+                       |                                 |
+                       | ------ k12:dem1:ipM:pM -------> | bind input on free port: p1
+                       |                                 |
+                       |                                 |
+ start dem1 to ipP:p1  | <------------- p1 ------------- |
+                       |                                 |
+                      ...                               ...
+                       |                                 |
+                       | ------ k12:dem2:ipM:pM -------> | bind input on free port: p2
+                       |                                 |
+                       |                                 |
+ start dem2 to ipP:p2  | <------------- p2 ------------- |
+                       |                                 |
+                      ...                               ...
+                       |                                 |
+                       | --------- ENDk12END ----------> x stop listening on pP,
+                       |
+disconnect from ipP:pP x
+
+
+                wait dem1+dem2                      wait dem1+dem2
 ```
\ No newline at end of file