README.md

BPjs: A Javascript-based Behavioral Programming Runtime.

This repository contains a javascript-based BP library.

License

• BPjs is open sourced under the MIT license. If you use it in a system, please provide a link to this page somewhere in the documentation/system about section.
• BPjs uses the Mozilla Rhino Javascript engine. Project page and source code can be found here.

---

Getting BPjs

• For Maven projects: Add BPjs as dependency. Note that the version number changes.

<dependencies>
    ...
    <dependency>
        <groupId>com.github.bthink-bgu</groupId>
        <artifactId>BPjs</artifactId>
        <version>0.8.6</version>
    </dependency>
    ...
</dependencies>

• Clone, fork, or download the starting project.
• Download the .jar files directly from Maven Central.
• The project's Google group

Documentation

• Presentations: Introduction Deeper dive
• Tutorial and Reference
• API Javadocs

Change log for the BPjs library.

2018-02-25

• ⬆️ VisitedStateStore Adds a clear() method.
• 🐛 DfsBProgramVerifier instances can now be re-used.

2018-01-24

• ⬆️ Improved hashing algorithm on BThreadStateVisitedNodeStore.
• ✨ Transient caching of thread state in BThreadSyncSnapshots. This improves verification performance, with low memory cost.
• 🐛 Removed visited state stores that took incoming state into consideration.
• 🔄 More mazes in the Mazes example.

2018-01-18

• 🐛 Fixed a crash where program with failed assertions were intermittently crashing.

2018-01-17

• 🐛 Verifier now correctly identifies deadlock as a state where there are requested events, but they are all blocked (formerly it just looked for the existence of b-threads).

2018-01-12

• 🐛 ✨ Refactored analysis code, removing the invalid (easy to understand, but invalid) PathRequirement based analysis, and using only b-thread now. This design is much cleaner, as it uses less concepts. Also moves us towards "everything is a b-thread" world.
• ✨ Added tests to demonstrate the various states a verification can end in.
• 🐛 Verifiers and runners terminate their threadpools when they are done using them.

2018-01-11

• ✨ During forward execution, b-threads can halt execution using bp.ASSERT(boolean, text).
• ⬆️ Refactored the engine tasks to support raising assertions. Reduced some code duplication in the way.
• ⬆️ Thread pools executing b-threads are now allocated per-executor/verifier (as opposed to using a single static pool).

2017-12-28

• ⬆️ Re-arranged package structure, duplicate and ambiguous packages merged. We now have a clean model/execution/analysis division.
• 🐛 Fixed an equality bug in OrderedSet.

2017-12-22

• 🐛 BSyncStatements now retain information about the b-thread that created them.
• ⬆️ Now using a single ExecutorService for the entire JVM (OK, per class-loader). This makes runtime more efficient, resource-wise.
• 🔄 Using cached thread execution pool instead of the fork-join one (the former seems to make more sense in a BP context).
• ⬆️ The Java threads executing the b-threads now have specific names: bpjs-executor-N (where N is a number starting at 1).
• ✨ New method: bp.getJavaThreadName: Returns the name of the Java thread executing the b-thread while this method was called.
• 🎉 Some changes in this version were requested by actual users. 🎉
• ✨ Documentation updated to mention verification (full-length text to be added post-paper).
• 🐛 BThreadJSProxy.get/setBthread updated to use capital T, like the resp fo the code.
• 🔄 Test clean-up
• 🔄 Documentation clean-up

2017-11-24

• ✨ BProgram allows appending and prepending source code programmatically, using appendSource and prependSource. These can be used to add environment simulation without touching the simulated model. Or just to act as includes, e.g. for common set-ups.
• ✨ Added new class: PathRequirements, to hold path requirements that do not require state (e.g. "no deadlock").
• ✨ DfsBProgramVerifier now has a "debug mode" (set/get via get/isDebugMode). On debug mode, it prints verbose information to System.out.
• ✨ Added new class: BThreadStateVisitedNodeStore, looks only into the states of the b-threads when deciding whether a search node was already visited or not.
• 🐛 InMemoryEventLoggingListener cleans its event log when a run begins, so it can be reused for multiple runs.
• 🔄 Reduced method accessibility in BProgram, so subclassers have harder time getting into trouble.
• :put_trash_in_its_place: BProgramListener renamed to BProgramRunnerListener, since that is the object it listens to.
• :put_trash_in_its_place: NoDeadlock class deleted. Use PathRequirements.NO_DEADLOCK instead.
• ✨ PathRequirements.ACCEPT_ALL, is a new requirement that's always true. Useful for scanning a program state space.

2017-11-23

• ⬆️ DfsProgramVerifier uses FullVisitedNodeStore by default (preferring correctness over speed in the default case).
• ⬆️ Updated the Dining Philosopher example to use advanced features. Also added it as a unit test.
• 🚮 Removed validation package.
• ✨ ContinuationProgramState correctly captures updated variable values. 🎉

2017-11-02

• ✨ the DfsBProgramVerifier is now accepting requirement objects over execution paths, instead of the hard-coded deadlock check.
• ✨ new PathRequirement class. Requirements are passed to the verifiers for making sure the program conforms to them. Two implementation already present:
  • NoDeadlock Breakes when there's a deadlock
  • EventNotPresent Breaks when the last event in the ongoing path is a member of a given event set.
• ✨ the DfsBProgramVerifier is now using listener architecture for reporting progress.
• ✨ new event set from bp: bp.allExcept(es).
• ⬆️ Efficient path stack implementation for BfsBProgramVerifier (no copying, reversal, etc.)
• ⬆️ Mazes.java Updates to fully use the new verifier features

2017-10-30

• ⬆️ Re-created program state cloning based on code from @szegedi. Cloning is now faster, more efficient, and can handle storage of events.

2017-10-16

• ✨ New base class for implementing event selection strategies.
• ✨ OrderedEventSelectionStrategy - A new event selection strategy that honors the order in which events are requested by a given b-thread.
• ✨ PrioritizedBThreadsEventSelectionStrategy - A new event selection strategy that can assign priorities to b-threads.
• ✨ PrioritizedBSyncEventSelectionStrategy - A new event selection strategy that allows b-threads to add priority to their bsyncs.
• ⬆️ LoggingEventSelectionStrategyDecorator also logs selectable events
• ⬆️ BProgram acts nicer when it has a null event selection strategy.

2017-09-10

• ✨ Updated to Rhino 1.7.7.2.

2017-08-18

• ✨ Initial verification added. DfsBProgramVerifier scans the states of a BProgram using DFS, and can return traces where there are no selectable events.

2017-08-06

• ✨ Added a class to compare continuations (base for comparing snapshots).

2017-07-05

• ✨ bsync now has an extra parameter, allowing b-threads to pass hinting data to custom EventSelectionStrategys.
• 🔄 Moved event selection strategy to BProgram.
• ✨ Added a mechanism to log the BProgramState at sync points.

2017-06-08

• ✨ Added documentation for embedding BPjs programs in larger Java apps.

2017-05-16

• ✨ README includes a more prominent reference to the documentation.

2017-05-10

• ✨ Added an adapter class for BProgramListener.
• 🐛 Fixed issues with adding objects to the program's scope.

2017-04-08

• 🚮 Cleaned up the BProgramRunner-BProgram-BProgramSyncSnapshot trio such that listeners don't have to be passed around between them.
• ✨ Cloning of BProgramSyncSnapshot ready. This is the basis for search.

2017-03-22

• ✨ New architecture: Running logic moved from BProgram to BProgramRunner - ongoing.
• ✨ BProgramListeners notified before BPrograms are started.
• 🐛 Fixed a bug where dynamically added b-threads that were added by other dynamically added b-threads would run one cycle too late.
• 🐛 Fixed a bug where external events enqueued from top-level JS code where ignored.

2017-03-21

• ✨ New architecture: Running logic moved from BProgram to BProgramRunner. This will help implementing search.
• ✨ BProgramListeners notified when a b-thread runs to completion.
• ✨ bp.getTime() added.
• ✨ Updated tutorial now includes the bp object.

2017-03-15

• 🚮 Simplified the examples test package.
• 🚮 all and none are now only available via bp.
• 🔄 cleaner scope structure..

2017-03-14

• 🔄 Internal method name clean-ups.
• 🚮 Removed unneeded initializations.
• 🐛 Program and bthread scopes are treated as scopes rather than prototypes.
• ✨ B-Thread scope games eliminated 🎉. Dynamic b-thread addition is now possible from within loops etc. Tutorial updated.
• ✨ More tests.

2017-03-02

• ✨ bp.random added.
• 🔄 Documentation updates
• ✨ Added java accessors for putting and getting variables in the JS program
• 🔄 fat.jar is now uber.jar.

2017-02-03

• ✨ the standard .jar file now contains only BPjs, and no dependencies. Fat jar (the jar that includes dependencies) is available via the releases tab.

2017-02-02

• 🔄 Events class renamed to EventSets. Some cleanup.
• 🔄 emptySet is now none.
• 🔄 all and emptySet are now available to BPjs code via bp.all and bp.none. This is to prevent name collisions with client code.
• 🐛 Fixed an issue with the logger, where logging levels were ignored.
• ✨ Log level can be set by BPjs code, using bp.log.setLevel(l). l is one of Warn, Info, Fine.

2017-01-16

• ✨ Updated documentation to refer to Maven Central
• 🐛 RunFile re-reads files from file system again.
• 🔄 More dead code removal.

2017-01-14

This release in focused on better BPjs-programmer experience and getting the code into a maven-central quality grade.

• 🐛 Fixing Javadoc references.
• 🚮 Positional bsync removed.
• ✨ Better error reporting on event sets defined in JavaScript.
• ✨ Better error reports for generic JS errors.
• ✨ Added StringBProgram: a new class for running BPjs code from a String (rather than a resource or a file).

2017-01-13

• ✨ Adding a BThread is idempotent. Previously, if a BThread was added twice, it would run twice with unexpected results.
• ✨ Basic engine exceptions, plus a friendlier error message when calling bsync outside of a BThread.
• 🔄 More Javadocs and code cleanup (mostly dead code removal).

2017-01-12

• ✨ License (MIT)
• ✨ Preparations for Maven Central
• 🔄 More Javadocs and code cleanup.

2017-01-05

• ✨ RunFile can now accept multiple BPjs files for input, and runs them as a single BProgram. It also has improved help text.

2017-01-03

• ✨ Added continuous code coverage with Coveralls.io (Thanks guys!).
• ✨ Improved test coverage.

2017-01-02

• ✨ Added continuous testing with Travis-CI (Thanks guys!).
• 🎉 Moved from native NetBeans to maven project 🎉 🎉 ✨
• 🐛 Various small issues fixed thanks to static analysis (and NetBeans' Code Inspection tool).
• 🔄 Moved to canonical package structure (il.ac.bgu.cs.bp.*).

2017-01-01

• ✨ Re-arranged code to minimize amount of Context.enter-Context.exit pairs (~x5 performance factor!)
• ✨ Simplified mechanism for handling event selection in BProgram. Replaced a complex Visitor pattern with Java8's Optional.
• 🔄 Improved efficiency for external events handling.
• ✨ More tests for SimpleEventSelectionStrategy.
• ✨ More documentation.
• ✨ Better error messages.
• 🚮 Removed unused code from BProgram.
• 🚮 Removed non-serializable Optional from fields.

2016-12-31

• 🚮 Removed bpjs from JS scope. Programs must use bp now.
• 🚮 Polished the interface for adding BThreads to a program: 1 method instead of 3.
• 🐛 Fixed an issue where external events were re-ordered while checking for daemon mode termination.
• 🐛 A BProgram now quits when there are no more BThreads, even if there are enqueued external events.
• 🐛 Fixed typos in error messages.
• 🔄 Reduces method accessibility to minimum (nothing is public unless it has to be).
• ✨ More documentation.

2016-12-16

• ✨ A class for running bpjs files.
• 👍 Efficient use of Context, so that we don't open and exit it all the time.
• 🚮 More removal of more unused code. We now have less unused code. Less is more, especially with unused code.

2016-12-11

• 🔄 breakUpon is now interrupt. This leaves breakUpon to be later used as a language construct rather than a bsync parameter.

2016-12-05

• 🚮 ✨ 🐘 Big refactoring and clean-up towards enabling search. BThreads removed from engine - main new concept is that an execution of a BThread is a series of BThreadSyncSnapshot, advanced/connected by BPEngineTasks. A BProgram is an execution environment for multiple BThreads (plus some state and management code).

2016-09-18

• 🐛 breakUpon handlers are evaluated in the BThread's context, rather than in the BProgram one.

2016-09-13

Client code / Javascript

• ✨ Updated the logging mechanism from global, single level to 3-level. Code change required: bplog("hello") -> bp.log.info("hello). Also supports warn and fine.
• 🚮 bpjs is deprecated (but still works). Please use bp now.
• 🚮 positional bsync deprecated (but still works). Please use the named-argument variant bsync({request:....}).
• 🚮 BThread is not exposed in Javascript via bt (that was never used).
• ✨ BThreads can now enqueue external events using bp.enqueueExternalEvent().
• ✨ BThreads can now specify a function that will be executed if they are removed because an event in their breakUpon event set was selected. Use setBreakUponHandler( function(event){...} ).

Engine/General

• ✨ Restructured the engine with JS proxies - javascript code has no direct interaction with the Java engine parts!
• 👍 More unit tests and examples

Engine/General

• Restructured the engine with JS proxies - javascript code has no direct interaction with the Java engine parts!
• More unit tests and examples

2016-06-11

• ✨ BEvents now have an associated data object. See example here

• ✨ New way of creating BEvents: a static method named named:

  new BEvent("1stEvent") // old
  BEvent.named("1stEvent") // new and English-like.

  Future usaged include the ability to reuse event instances, but we're not there yet.

• ✨ Added support for Javascript definition of event sets:

  var sampleSet = bpjs.EventSet( function(e){
    return e.getName().startsWith("1st");
  } );

2016-06-10

• ✨ Support for breakUpon in bsyncs:

  bsync( {request:A, waitFor:B, block:C, breakUpon:D})

• ✨ SingleResourceBProgram - a convenience class for the common case of having a BProgram that consists of a single file.

2016-06-01

• 🔄 BProgram's setupProgramScope gets a scope as parameter. So no need to call getGlobalScope, and it's clearer what to do.
• ✨ RWBStatement now knows which BThread instantiated it
• ✨ When a program deadlock, StreamLoggerListener would print the RWBStatements of all BThreads.

Legend:

• 🔄 Change
• ✨New feature
• 🚮 Deprecation
• ⬆️ Upgrade
• 🐛 Bug fix