bp-realted docs and methods updated

README.md

@@ -24,7 +24,7 @@ a link to this page somewhere in the documentation/system about section.
     <dependency>
         <groupId>com.github.bthink-bgu</groupId>
         <artifactId>BPjs</artifactId>
-        <version>0.8.3</version>
+        <version>0.8.4</version>
     </dependency>
     ...
 </dependencies>
@@ -35,6 +35,11 @@ a link to this page somewhere in the documentation/system about section.
 
 ## Change log for the BPjs library.
 
+### 2017-03-21
+
+* :sparkles: `bp.getTime()` added.
+* :sparkles: Updated tutorial now includes the `bp` object.
+
 ### 2017-03-15
 
 * :put_litter_in_its_place: Simplified the `examples` test package.

docs/source/BPjsTutorial/bp-object.rst

@@ -2,4 +2,68 @@
 The ``bp`` Object
 =====================
 
-.. todo :: write this.
+In the code snippets we've seen so far, one object kept coming up: ``bp``. This object gives access to the behavioral programming infrastructure that runs the program. It allows registering b-threads, creating events and event sets, and interacting with the external world (e.g. logging).
+
+Another role ``bp`` holds is abstraction layer for values that change, such as random numbers generation and time. This abstraction is needed to allow program verification -- when BP code that uses such values is verified, the verifier needs to iterate over the possible return values. To enable this, the verifier will be able to decide on the values methods such as ``bp.random.nextInt(7)`` will return. For regular program execution, however, calling these methods is just like calling the regular Javascript objects, such as ``Math.random()``.
+
+``bp`` is implemented on the Java side by an object called ``il.ac.bgu.cs.bp.bpjs.bprogram.runtimeengine.jsproxy.BProgramJsProxy`` - look at its `JavaDoc`_ for full reference. Below are the noteworthy methods.
+
+.. _JavaDoc: http://static.javadoc.io/com.github.bthink-bgu/BPjs/0.8.3/il/ac/bgu/cs/bp/bpjs/bprogram/runtimeengine/jsproxy/BProgramJsProxy.html
+
+
+Methods of Note
+---------------
+
+``bp.Event(name, [data])``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creates an event with name and possible data object.
+
+* ``name``: Name of event. String.
+* ``data``: Optional object. Additional data for the object.
+
+
+``bp.EventSet(name, predicate)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Creates and event set: basically a named predicate that accepts events and returns ``true`` for set members.
+
+* ``name``: Name of the event set. String.
+* ``predicate``: The set membership predicate. Function that takes one parameter (event) and returns boolean.
+
+
+``bp.enqueueExternalEvent(event)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Enqueues an event to the program's external event queue. See :ref:`external_events`.
+
+* ``event``: The event to be enqueued. Event.
+
+
+``bp.registerBThread([name], bthreadFunction)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Registers a new b-thread into the running b-program. The caller may specify a name (useful for making sense of the logs, for example). If no name is specified, an automatic name is generated.
+
+* ``name``: Optional. Name of the b-thread. String.
+* ``bthreadFunction``: A no-parameter function that is the body of the b-thread.
+
+
+``bp.log``
+~~~~~~~~~~
+
+Provides access to the logger. See :doc:`logging`.
+
+``bp.random``
+~~~~~~~~~~~~~
+
+provides an access to a random number generator, sporting the following methods:
+
+* ``bp.random.nextFloat()``: Generate a random number between 0 and 1.
+* ``bp.random.nextInt(bound)``: Generate a random number between 0 (inclusive) and ``bound`` (non-inclusive).
+* ``bp.random.nextBoolean()``: Toss a coin, report the caller.
+
+``bp.getTime()``
+~~~~~~~~~~~~~~~~
+
+Returns the current time in milliseconds since January 1st, 1970. To get the current date, call ``new Date(bp.getTime())``;

docs/source/BPjsTutorial/dynamic-bthread-addition.rst

@@ -31,13 +31,13 @@ The reason for this is that Javascript is a late-binding language, so ``i``'s  v
 
 Alas, the b-thread is started after the javascript file is evaluated. At this point, ``i`` is equal to 4. So in effect, we had four b-threads, named ``requestor-0`` to ``requestor-3``, all asking for event ``e4``.
 
-To get four different events, we need to create a scope for each iteration. This is easy, since Javascript supports functions as first-class-citizens (:download:`source <code/dynamic-bthread-ok.js>`)..
+To get four different events, we need to create a scope for each iteration. This is easy, since Javascript supports functions as first-class-citizens (:download:`source <code/dynamic-bthread-ok.js>`).
 
 .. literalinclude:: code/dynamic-bthread-ok.js
   :linenos:
   :language: javascript
 
-Lines 4-6 are the same as before, but now they are wrapped in an anonymous function (line 3) that's immediately called, with ``i`` as the parameter (line 7). This results in the b-thread function having its own scope (or, to be technically exact, activation object). That scope keeps the value of ``i`` at the iteration the scope was created - that value is put in the parameter ``j``.
+Lines 4-6 are the same as before, but now they are wrapped in an anonymous function (line 3) that's immediately called, with ``i`` as the parameter (line 7). This results in the b-thread function having its own scope (or, to be technically exact, activation object). That scope keeps the value of ``i`` at the iteration the scope was created in - that value is put in the parameter ``j``.
 
 Thus, each b-thread gets its own scope and correct value of ``i`` (except that it's calling it ``j`` at this point).
 

docs/source/BPjsTutorial/interrupts.rst

@@ -66,6 +66,8 @@ Here's the output of an unsuccessful baking attempt:
   ---:BPjs Ended
 
 
+.. _external_events:
+
 Final Acts of an Interrupted B-Thread
 --------------------------------------
 

docs/source/BPjsTutorial/logging.rst

@@ -38,7 +38,8 @@ The "event generator" creates four events, one for each logging level. The "even
 
 
 
-.. caution :: Later versions might integrate BPjs with a full-blown logging system, such as `logback`_ or `log4j2`_. Programs relying on the exact logging format may need to change once the logging is updated.
+.. caution :: Later versions might integrate BPjs with a full-blown logging system, such as `logback`_ or `log4j2`_. Programs relying on the exact logging format may need to change once the logging is updated. If you need to write a program that relies on accurate interpretation a b-program life cycle and selected events, consider implementing a `BProgramListener`_.
 
 .. _logback: https://logback.qos.ch
 .. _log4j2: http://logging.apache.org/log4j/2.x/index.html
+.. _BProgramListener: http://static.javadoc.io/com.github.bthink-bgu/BPjs/0.8.3/il/ac/bgu/cs/bp/bpjs/bprogram/runtimeengine/listeners/BProgramListener.html

docs/source/_static/css/custom.css

@@ -13,6 +13,10 @@ h3 {
   font-weight: bold;
 }
 
+.sphinxsidebarwrapper ul li {
+  overflow-wrap: break-word;
+}
+
 .admonition {
   box-shadow: 0 2px 2px rgba(255,255,255,.5) inset, 0 2px 4px rgba(0,0,0,.5);
 }
@@ -88,6 +92,12 @@ pre {
   border: 1px solid white;
 }
 
+code.literal {
+  font-size: 11pt;
+  font-family: Menlo, Monaco, "Courier New", monospace;
+  padding: inherit 4px;
+}
+
 .bash .highlight pre,
 .code.bash.literal-block {
   background-color: #232;

src/main/java/il/ac/bgu/cs/bp/bpjs/ContinuationGames.java

@@ -4,20 +4,13 @@
 package il.ac.bgu.cs.bp.bpjs;
 
 import il.ac.bgu.cs.bp.bpjs.bprogram.runtimeengine.BProgram;
-import il.ac.bgu.cs.bp.bpjs.bprogram.runtimeengine.BSyncStatement;
 import il.ac.bgu.cs.bp.bpjs.bprogram.runtimeengine.BThreadSyncSnapshot;
-import il.ac.bgu.cs.bp.bpjs.bprogram.runtimeengine.jsproxy.BProgramJsProxy;
-import il.ac.bgu.cs.bp.bpjs.events.BEvent;
-import il.ac.bgu.cs.bp.bpjs.eventsets.JsEventSet;
 import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
-import java.util.Arrays;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 import org.mozilla.javascript.Context;
 import org.mozilla.javascript.ContextFactory;
-import org.mozilla.javascript.Function;
-import org.mozilla.javascript.ImporterTopLevel;
 import org.mozilla.javascript.Scriptable;
 import org.mozilla.javascript.serialize.ScriptableInputStream;
 import org.mozilla.javascript.serialize.ScriptableOutputStream;
@@ -92,6 +85,7 @@ public void mainEventLoop() throws InterruptedException {
 
                         // go!!
                         cx.resumeContinuation(cnt2, scope2, new Object[0]);
+                        cx.resumeContinuation(cnt2, scope2, new Object[0]);
                     }
                 }
                 Context.exit();

src/main/java/il/ac/bgu/cs/bp/bpjs/bprogram/runtimeengine/jsproxy/BProgramJsProxy.java

@@ -10,8 +10,6 @@
 import il.ac.bgu.cs.bp.bpjs.eventsets.EventSets;
 import il.ac.bgu.cs.bp.bpjs.eventsets.JsEventSet;
 import il.ac.bgu.cs.bp.bpjs.exceptions.BPjsRuntimeException;
-import java.util.Arrays;
-import java.util.Random;
 import java.util.concurrent.atomic.AtomicInteger;
 import org.mozilla.javascript.Function;
 
@@ -168,5 +166,12 @@ public void loadJavascriptResource(String path) {
         program.evaluateResource(path);
     }
 
+    /**
+     * @return Returns the current time in milliseconds since 1/1/1970.
+     */
+    public long getTime() {
+        return System.currentTimeMillis();
+    }
+
 
 }

src/main/java/il/ac/bgu/cs/bp/bpjs/bprogram/runtimeengine/jsproxy/BThreadJsProxy.java

@@ -11,7 +11,6 @@
 import il.ac.bgu.cs.bp.bpjs.eventsets.EventSets;
 import java.util.Arrays;
 import java.util.Map;
-import java.util.Set;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 import static java.util.stream.Collectors.toSet;

src/test/java/il/ac/bgu/cs/bp/bpjs/examples/GetTimeTest.java

@@ -0,0 +1,46 @@
+/*
+ * The MIT License
+ *
+ * Copyright 2017 michael.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package il.ac.bgu.cs.bp.bpjs.examples;
+
+import il.ac.bgu.cs.bp.bpjs.bprogram.runtimeengine.BProgram;
+import il.ac.bgu.cs.bp.bpjs.bprogram.runtimeengine.SingleResourceBProgram;
+import static org.junit.Assert.assertTrue;
+import org.junit.Test;
+
+/**
+ *
+ * @author michael
+ */
+public class GetTimeTest {
+
+    @Test
+    public void test() throws InterruptedException {
+        BProgram sut = new SingleResourceBProgram("getTimeTest.js");
+        long timePre = System.currentTimeMillis();
+        sut.start();
+        long timePost = System.currentTimeMillis();
+        Long actual = sut.getFromGlobalScope("theTime", Long.class).get();
+        assertTrue( (actual>=timePre) && (actual<=timePost) );
+    }
+}

src/test/resources/getTimeTest.js

@@ -0,0 +1,5 @@
+/* global bp */
+
+var theTime = bp.getTime();
+bp.log.warn("Time is: " + theTime);
+