Added documentation for event set compositions (closes #85)

Author: michbarsinai

docs/source/BPjsTutorial/bp-object.rst

@@ -62,6 +62,23 @@ Splits the calling b-thread to two identical b-threads. On the "parent" b-thread
 
 Provides access to the logger. See :doc:`logging`.
 
+``bp.eventSets``
+~~~~~~~~~~~~~~~~
+
+Provides access to useful event sets methods and constant:
+
+* ``bp.eventSets.all``: All events (an event set that contains all events).
+* ``bp.eventSets.none``: An event set that does not contain any event.
+* ``bp.eventSets.anyOf(e1, e2, e3)``: An event set that contains ``e1``, ``e2``, and ``e3``. Similar to ``e1.or(e2).or(e3)``.
+* ``bp.eventSets.allOf(s1, s2, s3)``: An event set that is the conjunction of ``s1``, ``s2``, and ``s3`` (so, contains only events that are in ``s1`` and ``s2`` AND ``s3``). Similar to ``e1.and(e2).and(e3)``.
+* ``bp.eventSets.not(es42)``: An event set containing all events that are not in ``es42``.
+
+.. note::
+    Recall that events are event sets themselves (technically, an event is an event set that contains a single event - itself). So whenever a method expects an event _set_, you can pass a regular event to it.
+
+
+
+
 ``bp.random``
 ~~~~~~~~~~~~~
 

docs/source/BPjsTutorial/eventsets.rst

@@ -2,30 +2,61 @@
 Event Sets
 ==========
 
-When a b-thread requests an event, it has to be specific. That is, the b-thread has to provide an event instance as a parameter to ``bp.sync``. This is not the case for waited-for and blocked events: there are specified by an **event set**. An event set can be specified in the following ways:
+When a b-thread requests an event, it has to be specific. That is, the b-thread has to provide an event instance as a parameter to ``bp.sync``. This is not the case for waited-for and blocked events: these are specified by an **event set**. An event set contains other events. It is a set in the mathematical sense - it does not have to store the events it contains in a data structure, just to answer *yes* or *no* when asked whether it contains them. Accordingly, an event set is defined by a function that accepts an event and returns ``true`` or ``false``.
+
+An event is a special type of event set - an event set that contains only itself. So we get that:
+
+.. code:: javascript
+
+  const eventA = bp.Event("A");
+  const eventB = bp.Event("B");
+
+  eventA.contains(eventA); // true
+  eventA.contains(eventB); // false
+
+An event set can be specified in the following ways:
 
 *  If the set contains a single event, the event itself serves as an event set. We used this in the :ref:`hello_world` example.
 
-*  If the set contains some events known in advance, they can be passed as a value like so:
+* By composing events through their composition methods ``or``, ``and``, ``negate``, ``xor``, ``nor``, and ``nand``:
+
+  .. code:: javascript
+
+    const aOrB = bp.Event("A").or( bp.Event("B") ); // contains events "A" and "B"
+    const notA = bp.Event("A").negate(); // all events except "A"
+    const notAOrB = bp.Event("A").or( bp.Event("B") ).negate(); // contains all events 
+                                                                // except for "A" and "B"
+
+* By using the ``bp.eventSets`` utility object:
 
   .. code:: javascript
 
-    bp.sync({waitFor:[evt1, evt2, evt3], block:[evt500]});
+    const aOrB = bp.eventSets.anyOf( bp.Event("A"), bp.Event("B") );
+    const conj = bp.eventSets.allOf( es1, es2 ); // events that are members of event sets ``es1`` and ``es2``.
+    const notA = bp.eventSets.not( bp.Event("A") ); // all events except "A".
 
-*  By an ``EventSet`` object. These have name and a predicate that takes an event and returns a boolean result: ``true`` if the event is a member of the set, and ``false`` otherwise:
+*  By an ``EventSet`` object. These have name and a predicate that takes an event and returns a boolean result: ``true`` if the event is a member of the set, and ``false`` otherwise. This way of defining event sets is verbose, but allows for fine-grained control over the set containment logic:
 
   .. code:: Javascript
 
-    bp.EventSet( "name", function(evt){
-      return /* computation about evt goes here */;
+    bp.EventSet( "eventsWhoseNameStartsWithA", function(evt){
+      return (evt.name.indexOf("A")==0);
     });
 
-* By using one of the built-in event sets, ``bp.all``, which contains all events, or ``bp.none``, which is an empty set.
+
+*  An array of event sets is a translated to a disjunction (or) of those events (however, this is an old form which is not encouraged anymore, since it's not intuitive whether the semantics are of AND or of an OR).:
+
+  .. code:: javascript
+
+    bp.sync({waitFor:[evt1, evt2, evt3], block:evt500}); // same as evt1.or(evt2).or(evt3)
+
+.. tip::
+  The utility object ``bp.eventSets`` has two useful event set constants: ``bp.eventSets.all``, which contains all events, and ``bp.eventSets.none``, which is an empty set.
 
 Example: Keep Serving Coffee
 ----------------------------
 
-Consider a coffee shop that serves some teas, sparkling water, and -- surprise -- coffees. Customers come and request their drink. To make sure the coffee is always freshly ground, the ground coffee container is just large enough to contain amount needed for ten cups. Thus, after the tenth coffee, the baristas has to stop taking coffee orders and go grind some coffee. They can serve other orders, though. The code below (:download:`full source <code/eventsets.js>`) models this.
+Consider a coffee shop that serves some teas, sparkling water, and -- surprise -- coffees. Customers come and request their drink. To make sure the coffee is always freshly ground, the ground coffee container is just large enough to contain the amount needed for ten cups. Thus, after the tenth coffee, the baristas has to stop taking coffee orders and go grind some coffee. They can serve other orders, though. The code below (:download:`full source <code/eventsets.js>`) models this.
 
 First off, we need to generate the orders. Nothing fancy here, just your usual event requesting for-loop.
 
@@ -46,7 +77,7 @@ After defining the event set for coffee orders, the "coffee supply" b-thread loo
 
 .. note:: Rather than counting how many coffees were made using some variable, the "coffee supply" b-thread loops for 10 times, waiting for coffee to be ordered. This is an example for the classic scenario style: X has to happen Y times, and then we do Z.
 
-Here's a sample output of this b-program:
+Here's a sample output of this b-program (annotated):
 
 .. code:: bash
 
@@ -58,30 +89,30 @@ Here's a sample output of this b-program:
   ---:BPjs Started
    --:BPjs Event [BEvent name:green tea]
    --:BPjs Event [BEvent name:green tea]
-   --:BPjs Event [BEvent name:espresso coffee]
-   --:BPjs Event [BEvent name:latte coffee]
+   --:BPjs Event [BEvent name:espresso coffee]  «1»
+   --:BPjs Event [BEvent name:latte coffee]     «2»
    --:BPjs Event [BEvent name:sparkling water]
-   --:BPjs Event [BEvent name:espresso coffee]
+   --:BPjs Event [BEvent name:espresso coffee]  «3»
    --:BPjs Event [BEvent name:black tea]
-   --:BPjs Event [BEvent name:espresso coffee]
-   --:BPjs Event [BEvent name:latte coffee]
+   --:BPjs Event [BEvent name:espresso coffee]  «4»
+   --:BPjs Event [BEvent name:latte coffee]     «5»
    --:BPjs Event [BEvent name:black tea]
    --:BPjs Event [BEvent name:black tea]
    --:BPjs Event [BEvent name:sparkling water]
    --:BPjs Event [BEvent name:sparkling water]
-   --:BPjs Event [BEvent name:espresso coffee]
-   --:BPjs Event [BEvent name:flatwhite coffee]
-   --:BPjs Event [BEvent name:espresso coffee]
-   --:BPjs Event [BEvent name:latte coffee]
+   --:BPjs Event [BEvent name:espresso coffee]  «6»
+   --:BPjs Event [BEvent name:flatwhite coffee] «7»
+   --:BPjs Event [BEvent name:espresso coffee]  «8»
+   --:BPjs Event [BEvent name:latte coffee]     «9»
    --:BPjs Event [BEvent name:black tea]
-   --:BPjs Event [BEvent name:espresso coffee]
-   --:BPjs Event [BEvent name:Grind more coffee!]
-   --:BPjs Event [BEvent name:flatwhite coffee]
+   --:BPjs Event [BEvent name:espresso coffee]  «10»
+   --:BPjs Event [BEvent name:Grind more coffee!] «**Grind**»
+   --:BPjs Event [BEvent name:flatwhite coffee] «11»
    --:BPjs Event [BEvent name:sparkling water]
    --:BPjs Event [BEvent name:black tea]
    ... continues ...
 
 Creating Complex Behaviors Using Simpler Ones
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The coffee shop program also serves as an example for the BP way of composing complex behavior from simpler ones. Baristas serves drinks when they are ordered. They also grind coffee when the ground coffee supply is low. Using BP, these behaviors can be described separately by the programmer, so they are easy to maintain and reason about. At runtime, the BP execution engine -- BPjs, in our case -- combines them to the required complex behavior.
+The coffee shop program also serves as an example for the BP way of composing complex behavior from simpler ones. Baristas serves drinks when they are ordered. They also grind coffee when the ground coffee supply is low. Using BP, these behaviors can be described separately by the programmer, so they are easy to maintain and reason about. At runtime, the BP execution engine -- BPjs, in our case -- combines them into the required complex behavior.