Stop ignoring .png files

Author: jaynel

.gitignore

@@ -16,7 +16,6 @@ relx
 *.html
 *.o
 *.plt
-*.png
 *.log
 *.swp
 erl_crash.dump

RELEASES.md

@@ -21,6 +21,7 @@ Releases
     * Eliminate elysium_session_enqueuer module
     * Remove unused elysium_queue:node_change/1
     * Add Cassandra node reporting on connection errors
+    * Move pending requests earlier than connection queue in supervisor
 
 ### <a name="0.2.2"></a>0.2.2 Add app.config configuration option
 

doc/README.md

@@ -1,11 +1,96 @@
 elysium
 =======
 
-Elysium provides dynamic access to a Cassandra cluster
+### Elysium provides dynamic access to a Cassandra cluster
 
   - Uses round-robin connection semantics
   - Manages live connections via checkin/checkout
   - Addresses overload using a pending request queue
   - Periodically checks for new Cassandra nodes
 
+-------
+### Resilience is provided via rest_for_one supervision
+
+  - ETS data management: elysium_buffer_sup
+  - Application status/control: elysium_queue
+  - Load balancing: elysium_lb_queue
+  - Cassandra node discovery: elysium_peer_handler
+  - Connection queues: serial queue of connections and requests
+  - Connection management: elysium_connection_sup
+
+-------
+### Supervision Tree
+
+![Elysium Top-Level Supervision Tree](supervision_tree.png)
+
+-------
+### Queues are more persistent than connections
+
+  - Loss of all connections does not affect queues
+     - unless elysium_sup itself is taken out
+     - ets tables, status/control are last to die
+     - ensures monitoring works when things are down
+  - activate/deactivate adds/destroys connections
+     - currently too abrupt
+     - in future will nicely drain in flight queries
+  - load balancing survives when requests/connection queues down
+     - cluster node discovery runs even if connections gone
+     - activate creates new connections using round-robin
+
+-------
+### Basic operation is a checkin/checkout
+
+  - Load balancing via a ring buffer
+     - checkin/checkout Cassandra {Host, Port}
+     - connections are round-robin
+     - slow to respond nodes are skipped
+     - ring buffer updated by elysium_peer_handler
+  - Connections are in a checkin/checkout queue
+     - implemented as a behaviour
+     - currently relies on elysium_serial_queue
+     - elysium_parallel_queue trips on concurrency issues
+  - Requests checkout a connection and then check it back in
+     - if none available, request is put in pending queue
+     - connection is long-lived seestar Cassandra socket gen_server
+  - Also supports a one-shot request
+     - spawns a new seestar connection
+     - discards the connection after the request completes
+
+-------
+### Stochastic Connection Migration
+
+  - Connections decay periodically
+     - randomly in N chances per 1 Billion requests
+     - decayed connections are immediately replaced
+     - the new connection is placed at the end of the queue
+     - unless it is used immediately on a pending request
+  - Reconnect avoids congestion
+     - round-robin skips slow to respond nodes
+     - redistributes all connections over time
+     - restarts seestar sessions to avoid memory/staleness issues
+
+-------
+### Data Flow Logic
+
+![Elysium Data Flow](data_flow.png)
+
+-------
+### Three Methods of Configuration
+
+  - {config_mod, Module}
+     - defines a functional interface for all config values
+     - allows adaptive functionally changing parameters
+  - {vbisect, Binary}
+     - uses a binary dictionary for all config values
+     - shared, lock-free, read-only configuration
+     - any changes have to be distributed to running processes
+  - {config_app_config, elysium}
+     - refers to a top-level config block in the app.config file
+     - has to be the name of a loaded application
+     - simplest is to use elysium as an included_application
+  - Performance is not equal
+     - config_mod is 50% slower
+     - vbisect and app.config seem to have similar performance
+     - not measured with 16-core or more servers
+
 

doc/supervision_tree.dot

@@ -12,8 +12,8 @@ graph ""
    n3 [ label="<l2> elysium_queue\n(gen_fsm elysium status)" ];
    n4 [ label="<l2> elysium_lb_queue\n(gen_server round-robin C*)" ];
    n5 [ label="<l2> elysium_peer_handler\n(node discovery)" ];
-   n6 [ label="<l2> elysium_serial_queue\n(idle C* sessions)" ];
-   n7 [ label="<l2> elysium_serial_queue\n(pending C* requests)" ];
+   n6 [ label="<l2> elysium_serial_queue\n(pending C* requests)" ];
+   n7 [ label="<l2> elysium_serial_queue\n(idle C* sessions)" ];
    n8 [ label="<l2> elysium_connection_sup\n(simple_one_for_one)" ];
   }
 

doc/supervision_tree.pdf

@@ -82,5 +82,5 @@ init({Config}) ->
           [Buffer_Sup, Queue_Proc,                       % Ets owner and status reporter
            Serial_LB_Queue,                              % Queue for peer nodes
            Discovery_Proc,                               % Detects peer nodes and refreshes the buffers
-           Serial_Session_Queue, Serial_Pending_Queue,   % Queue gen_servers for serial option
+           Serial_Pending_Queue, Serial_Session_Queue,   % Queue gen_servers for serial option
            Conn_Sup]}}.                                  % Connection worker supervisor