Rewrite Conf doc

Author: jmettraux

README.md

@@ -25,41 +25,6 @@ Flor is a "Ruby workflow engine", if that makes any sense.
 
 see [doc/](doc/).
 
-## Running the specs
-
-(Most of the time, as developer of flor, I'm writing specs, running them with `FLOR_DEBUG=dbg` and hammering the code until the specs are green. The following lines are about setting `FLOR_DEBUG` for flor development).
-
-##### setting FLOR_DEBUG
-
-This is a targetted run of a spec file:
-```
-FLOR_DEBUG=msg,err bundle exec rspec spec/punit/cancel_spec.rb
-```
-
-* `msg` displays the flor messages in a summary, colored format
-* `err` displays errors with details, when and if they happen
-* `src` displays the source before it gets parsed and launched
-* `tree` displays the syntax tree as parsed from the source, right before launch
-* `run` shows info about each [run](doc/glossary.md#run) that just ended
-* `sto` displays debug information about the [storage](doc/glossary.md#storage), it's mostly SQL statements
-
-#### `FLOR_DEBUG=dbg` and `FLOR_DEBUG=all`
-
-There are two shortcuts for the flags above:
-```
-FLOR_DEBUG=dbg bundle exec rspec spec/punit/cancel_spec.rb
-  # is equivalent to
-FLOR_DEBUG=msg,err,src,tree,run bundle exec rspec spec/punit/cancel_spec.rb
-```
-and
-```
-FLOR_DEBUG=all bundle exec rspec spec/punit/cancel_spec.rb
-  # is equivalent to
-FLOR_DEBUG=msg,err,src,tree,run,log,sto bundle exec rspec spec/punit/cancel_spec.rb
-```
-
-I tend to use `FLOR_DEBUG=dbg` when developping flor.
-
 
 ## LICENSE
 

doc/fragments.md

@@ -0,0 +1,43 @@
+
+# fragments.md
+
+Fragments of documentation that will be reused later on.
+
+---
+
+
+## Running the specs
+
+(Most of the time, as developer of flor, I'm writing specs, running them with `FLOR_DEBUG=dbg` and hammering the code until the specs are green. The following lines are about setting `FLOR_DEBUG` for flor development).
+
+##### setting FLOR_DEBUG
+
+This is a targetted run of a spec file:
+```
+FLOR_DEBUG=msg,err bundle exec rspec spec/punit/cancel_spec.rb
+```
+
+* `msg` displays the flor messages in a summary, colored format
+* `err` displays errors with details, when and if they happen
+* `src` displays the source before it gets parsed and launched
+* `tree` displays the syntax tree as parsed from the source, right before launch
+* `run` shows info about each [run](doc/glossary.md#run) that just ended
+* `sto` displays debug information about the [storage](doc/glossary.md#storage), it's mostly SQL statements
+
+#### `FLOR_DEBUG=dbg` and `FLOR_DEBUG=all`
+
+There are two shortcuts for the flags above:
+```
+FLOR_DEBUG=dbg bundle exec rspec spec/punit/cancel_spec.rb
+  # is equivalent to
+FLOR_DEBUG=msg,err,src,tree,run bundle exec rspec spec/punit/cancel_spec.rb
+```
+and
+```
+FLOR_DEBUG=all bundle exec rspec spec/punit/cancel_spec.rb
+  # is equivalent to
+FLOR_DEBUG=msg,err,src,tree,run,log,sto bundle exec rspec spec/punit/cancel_spec.rb
+```
+
+I tend to use `FLOR_DEBUG=dbg` when developping flor.
+

lib/flor/conf.rb

@@ -27,35 +27,63 @@ module Flor
 
   module Conf
 
-    #
     # * uni_ unit prefix (or no prefix like for :env)
     # * sch_ scheduler prefix
     # * sto_ storage prefix
     # * exe_ executor prefix
     # * log_ logger prefix
     #
     #
+    # * :uni_name
+    #   The name for the unit (Scheduler+Storage) pair.
+    #   The name must match the following regex: `/\A[a-zA-Z0-9_]+\z/`
+    #   Can also be set via the FLOR_UNIT environment variable.
+    #
     # * :sch_heart_rate
-    #   defaults to 0.3s, checks for exids to run and timers to triggers
-    #   at least every 0.3s
+    #   Defaults to 0.3s, every 0.3s the scheduler checks its @wake_up and
+    #   @next_time fields to determine if it has to run (no db query)
+    #   @wake_up is set to true when there are incoming messages give to
+    #   this unit, @next_time simply holds the timestamp for the next timer
+    #   that has to trigger
     #
-    # * :sch_reload_frequency
-    #   resync (reload) with db after how much time? (defaults to 60 (seconds))
+    # * :sch_reload_after
+    #   reload/resync with db after how much time? (defaults to 60 (seconds))
+    #   minimizes communication with db in idle periods
     #
     # * :sch_max_executors
-    #   how many executor thread at most? (defaults to 7, 1 is OK in certain
+    #   How many executor thread at most? (defaults to 7, 1 is OK in certain
     #   environments)
     #
     # * :exe_max_messages
-    #   how many messages will an executor run in a single session
-    #   (before quitting and passing the hand)
+    #   How many messages will an executor run in a single session
+    #   (before quitting and passing the hand) Defaults to 77
+    #   An executor will not run indefinitely as long as they are messages.
+    #   The goal is to prevent an execution from monopolizing an executor.
+    #
+    # And finally:
+    #
+    # * :flor_debug or :debug
+    #
+    #   Usually set via the FLOR_DEBUG environment variable.
+    #   * `msg` displays the flor messages in a summary, colored format
+    #   * `err` displays errors with details, when and if they happen
+    #   * `src` displays the source before it gets parsed and launched
+    #   * `tree` displays the syntax tree as parsed from the source, right
+    #     before launch
+    #   * `run` shows info about each [run](doc/glossary.md#run) that just ended
+    #   * `sto` displays debug information about the
+    #           [storage](doc/glossary.md#storage), it's mostly SQL statements
+    #
+    #   * `stdout` states that the debug messages must go to STDOUT
+    #   * `stderr` states that the debug messages must go to STDERR
     #
+    #   For example `debug: 'msg,stdout'`
 
     def self.read(s)
 
       h = {}
       h.merge!(Flor::ConfExecutor.interpret(s))
-      h.merge!(interpret_flor_debug(h['flor_debug']))
+      h.merge!(interpret_flor_debug(h['flor_debug'] || h['debug']))
 
       h
     end