From afa4c85ccada6ac7ae66f8291379d4ea5883efa4 Mon Sep 17 00:00:00 2001
From: xdrm-brackets <doowap31@gmail.com>
Date: Sun, 4 Feb 2018 13:42:29 +0100
Subject: [PATCH] upd: 'README.md' -> new description, added 'bind-input' and
 'bind-output'; TODO: read, write, pool, master, trigger-send, trigger-wait

---
 README.md | 105 ++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 83 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 0a2320c..852870d 100644
--- a/README.md
+++ b/README.md
@@ -1,45 +1,106 @@
-# Exemple
+# bash socket utility
 
-2 machines (A and B) want to share an INPUT/OUTPUT communication in bash.
-- Machine B: 10.10.10.10 port 1111
-- Machine A: 20.20.20.20 port 2222
+## native calls
 
-### On machine B
+### 1. bind-input
 
-First of all because each machine will launch a **client** and a **server**, because of cyclic-redondency, we have to synchronise them so that the _clients_ are connected after the 2 _servers_.
-
-We can use the 'trigger' to do such synchronisation. It waits until it receives (through a choosen port) a message from machine A.
+Binding an input creates a listening socket on a local port and binds the socket data to a local accessible buffer (accessible with the native `read` call).
 
 ```bash
-./trigger 9999; ./launch machineB 20.20.20.20 2222 1111
+bind-input $id $port;
 ```
-So we are listening on port _9999_ waiting for machine A to tell us when to start.
 
-The arguments can be read through this sentence "I will connect to `20.20.20.20` at port `2222` and my port `1111` is available."
+*Arguments:*
+- `$id` is a unique arbitrary name you must give to the listening binding
+- `$port` is the number of the local port to listen to (between 1024 and 49151)
+
+*Execution:*
+- The `bind-input` execution will last until the socket is created, then it will move it to a background process and print its *PID*.
+- In order to close properly the `bind-input`, you must kill its *PID* with one of the 3 following signals: SIGINT, SIGHUP, SIGTERM. Note that you must not use *SIGKILL* because it won't trigger the "*proper closing*" routine.
 
 
-### On machine A
+*Exemple:*
 
-You can notice that it is the reverse command from machine B, but we have to launch the trigger instead of waiting for it. The last optional parameter of 'launch' is made for that purpose.
+Let's say that you want to listen to port 9999, then read every second. You want to ignore empty messages (if nothing received), and end the program when you receive the message "**END**".
 
 ```bash
-./launch machineA 10.10.10.10 1111 2222 9999;
-```
-Now the server will start as expected and stop the 'trigger' command on machine B so it will also launch the server on it. After a delay of 2 seconds, the 2 servers might be connected to each other.
+#/bin/bash
 
+# 1. Create the listening socket + store PID in /tmp
+bind-input input1 9999 > /tmp/get_bg_pid;
 
+# 2. Store PID in a variable
+bound_pid="`cat /tmp/get_bg_pid`";
 
-### Send a message
+# 3. Now the socket is listening, you can read every 1 sec
+while true; do
 
-```bash
-./write {sender_machine} "some_message\n";
+	# 3.1. Read received data from port 9999
+	message="`read input1`";
+
+	# 3.2. Ignore empty messages
+	[[ -z "$message" ]] && sleep 1 && continue;
+
+	# 3.3. Exit while() loop if received "END"
+	[[ "$message" = "END" ]] && break;
+
+	# 3.4. Wait 1 sec
+	sleep 1;
+
+done;
+
+# 4. Kill 'bind-input' with signal SIGINT, SIGHUP or SIGTERM
+kill -INT $bound_pid;
 ```
 
 
 
-### Read messages
+
+
+
+
+
+
+
+### 2. bind-output
+
+Binding an output creates a local accessible buffer (accessible with the native `write` call) bound to a socket connecting to a certain host and port.
 
 ```bash
-./read {sender_machine};
+bind-output $id $host $port;
+```
+
+*Arguments:*
+- `$id` is a unique arbitrary name you must give to the output binding
+- `$host` is the hostname (IP addr. or resolvable) of the machine to connect to.
+- `$port` is the number of the remote port to connect to (between 1024 and 49151)
+
+*Execution:*
+- The `bind-output` execution will last until the socket is created, then it will move it to a background process and print its *PID*.
+- In order to close properly the `bind-output`, you must kill its *PID* with one of the 3 following signals: SIGINT, SIGHUP, SIGTERM. Note that you must not use *SIGKILL* because it won't trigger the "*proper closing*" routine.
+
+
+*Exemple:*
+
+Let's say that you want to connect to port 192.168.0.2 at port 9999, wait 2 seconds, send a message, wait 1 second and send the "**END**" message.
+
+```bash
+#/bin/bash
+
+# 1. Create the connecting socket + store PID in /tmp
+bind-output output1 192.168.0.2 9999 > /tmp/get_bg_pid;
+
+# 2. Store PID in a variable
+bound_pid="`cat /tmp/get_bg_pid`";
+
+# 3. Wait for sending first message
+sleep 2;
+write output1 "some message\nwith\tescapable\e[1mcharaters\e[0m";
+
+# 4. Wait for sending "END" message
+sleep 1;
+write output1 "END";
+
+# 5. Kill 'bind-output' with signal SIGINT, SIGHUP or SIGTERM
+kill -INT $bound_pid;
 ```
-Note: After a 'read' call, the buffer will be flushed (reading = consuming).
\ No newline at end of file