We look at BPjs, the library for running behavioral programs written in Javascript. This presentation looks at the project goals, common usages, etc.

1. DEEP DIVE
INTO
BPJS
BP Group Meeting 2017-07-12
Michael Bar-Sinai

2. Agenda
• Project Vision, Goal, Other much profound issues
• The Code Repo
• Code
• Packages, Main classes
• Structure at runtime
• Structure at verification?
• Sample Usage

3. Project Vision
• Create an common infrastructure for BP research
• Allow Code reuse
• Facilitate Research Community
• Be the most boringest part of any
BP research
• cf. ROS, R, NumPy, iPython…
BP
AD
LSC
Search
ModelChecking
Robocode
IoT
Satellite
Event
Selection
StrategyYourResearchHere

4. BPjs in Research Setting
1. Standalone (just run BPjs code)
• Download BPjs-X.Y.Z.uber.jar from the releases page
• $ java -jar BPjs-X.Y.Z.uber.jar src1.js src2.js …
2. Embedded (used as a decision engine for a larger system)
• Download above jar and add to project classpath, or add as maven dependency,
or fork the sample project on GitHub
3. Post-process
• Pre-processor creates the b-program code and send to BPjs for execution
• Either through embedding the library or through piping code to above jar’s stdin
4. 2 and 3 combined

5. Vision ☞ Engineering Aims*
• Definition of "done": Coded, unit-tested, documented
• Enable rather than dictate: When a few implementations may
make sense, define an interface and allow users to mix and
match…
• Minimal Setup with reasonable defaults: …and provide an OK
default implementation
• Play well with others: Open source (MIT), Maven, Pure Java
• Look Inviting: Code available online, open CI and code coverage,
have positive internet footprint.
* Not saying we’re there yet

6. In the Repo
High-level
documentation
Written in Sphinx, published using RTD

7. In the Repo
All code
Including the unit tests.

8. In the Repo
Front repo page

9. In the Repo
Mostly Harmless
Git stuff
CI configuration
Project License
maven thingy
NetBeans thingy
main maven thingy

10. Branching
• Master: Always stable (“done”).
Normally last version here also
available as a release and in Maven
Central
• Develop: Should always compile and
pass tests (under CI). Small changes go
directly here.
• Feature Branches: For larger changes
that might require breaking builds.
⚠ For developing BPjs itself. NOT for client code that does not require changes to the BPjs core.

11. Systems and Services
clip art: http://cliparts.co/laptop-pictures-and-images
git
git
git
triggered
triggered
triggered
Manual (release)
triggered
Click system icons visit
them online

12. Code
(finally)

13. Packages
• Runtime engine
• (most action here)
• Classes intended as
application starting
points
• Search (verification)

14. Classes of Note
• BEvent Event in BP. Has name and maybe JS data. Also, a set that contains only itself
• BSyncStatement The runtime representation of the parameters passed to bsync.
Contains request, wait-for, block, and interrupt events. Might also contain metadata.
• BProgram “Classic” b-program in the BP sense. Plus, contains event selection
strategy and a queue of external events. Abstract. Cannot run on its own.
• StringBProgram A BProgram whose source comes from a string
• SingleResourceBProgram A BProgram whose source comes from a .js file
bundled with the code
• EventSelectionStrategy Based on a b-program state, produces set of selectable
events (run and verification), and selects a single event (run only). Interface. BPjs
comes with SimpleEventSelectionStrategy, which uses random event
selection.

15. More Classes of Note
• BProgramRunner Runs a BProgram, informs listeners.
• BProgramListener BPjs comes with
BProgramListenerAdapter,
InMemoryEventLoggingListener,
StreamLoggerListener
• BThreadSyncSnapshot Captured status of a b-thread when it
called bsync.
• BProgramSyncSnapshot Captured status of a b-program during
a synchronization point. Also contains external event queue.

16. No BThread Class (!)
• BThreads are emergent phenomenon of progression between
BThreadSyncSnaphots
BTSS BTSS BTSS BTSSStartBThread ResumeBThread ResumeBThread
ResumeBThread
BTSSBTSSBTSS
BTSS
ResumeBThreadResumeBThreadResumeBThread
Resume

17. Structure at Runtime

18. Structure during Verification
TBD

19. How to:
• Instantiate a SingleResourceBProgram with the resource’s name
• Pass that to a BProgramRunner
• Call BProgramRunner#start()
Run a BP program from a resource file
Client
Code
BProgramRunner SingleResourceBProgram
src.js
reads
creates

20. How to:
• Instantiate a StringBProgram, pass the source to the C’tor
• Pass the StringBProgram to a BProgramRunner
• Call BProgramRunner#start()
Run a BP program from a String
Client
Code
BProgramRunner StringResourceBProgram
- source:String
creates

21. How to:
• Instantiate a BProgram
• Pass it to a BProgramRunner
• Register a new StreamLoggerListener
(no-args C’tor defaults to stdout)
• Call BProgramRunner#start()
Run a BP program and log events to stdout
Client
Code
BProgramRunner BProgram
creates
EventLoggerListener
- out:OutputStream

22. How to:
• Instantiate a BProgram
• Pass it to a BProgramRunner
• Register a new StreamLoggerListener
(no-args C’tor defaults to stdout)
• Call BProgramRunner#start()
Run a BP program and log events to stdout
Client
Code
BProgramRunner BProgram
creates
EventLoggerListener
- out:OutputStream
A File
Pass a PrintStream to that file to the C’tor

23. How to:
• Create a EventStrategySelection decorator
that performs the needed inspections
• Instantiate a BProgram, pass it to
a BProgramRunner
• Set the BProgram’s ESS to a
decorated instance
• BProgramRunner#run
• e.g. LoggingEventSelectionStrategyDecorator
Inspect a BProgram's state at Sync point
Client
Code
BProgramRunner BProgram
creates
EventSelectionStrategy
InspectorESS
reports

24. How to:
• Before execution starts:
Put values in the program’s global scope.
• During Execution:
Enqueue external events.
Pass data TO a BProgram

25. How to:
• Read from its global scope
getFromGlobalScope(name, class)
• Listen to events using a
BProgramEventListener
Get data FROM a BProgram

26. Sample Usage
How Bad is
Random Event Selection

27. 1)
Create
a Fair
ESS
Extend
SimpleEvent
SelectionStr
ategy

28. 2) Write a Simple Program

29. 3)
Collect
Wait
Times
Using a
BProgramListener.
Note use of the
adapter variant

31. QUESTIONS?

32. DEEP DIVE INTO BPJS
Thanks