The BPJ Library

The BPJ Library

See examples, e.g., BPJ/BPJCore110 -> bp.src.unittest.helloworld BPJ/Examples -> TicTacToe Events B-threads B-Program(s) A main method:

Events

• Reflect the elements of behavior of your application (and its environment) – what you want to see in a trace.
• Instantiate or extend Event class
• Optional string name in constructor or in setName();
• Optional data fields
• See later on Event Sets

B-Threads

• Contain the logic of your application
• You code runBThread() method
• Use events to affect system behavior
• Call bSync() method to request, wait for or block events
• You code import static bp.BProgram.bp
• Use Java freely – but don’t wait for slow things (GUI interaction should be done separately).
• Avoid or minimize side effects and external dependencies that are not event-driven
• Events should be natural system behavior - minimize usage of events for pure inter-b-thread communication.
• You may instantiate multiple instances of same b-thread class – possibly with constructor parameters
• Parameters may be manually specified during instantiation or generated by the application - see Tic-Tac-Toe example.

The B-Program

• A container and execution environment for b-threads.
• You only need to instantiate it.
• BProgram externalizes the public variable lastEvent that can be seen by b-threads.
• Usually – there is just one BProgram per application, running all your b-threads, but you may have several b-programs in parallel.
• You may change run-time parameters of the b-program by calling methods to set them.

The bSync() Method

• bSync(RequestableEventInterface,EventSetInterface,EventSetInterface)
• Three parameters:
  • Requested Events:
  • Waited-for events (a.k.a “watched events”)
  • Blocked events
• Drives the collective execution mechanism:
  • Synchronizes the b-thread with the others – waits until all b-threads call bSync().
  • When all b-threads are waiting in bSync – the first event that is requested and is not blocked is selected. The search order is by b-thread priority, and within it – order of events in requestable event set.
  • All b-threads that have the selected event in their requested events set or in their waited-for event set are resumed.
  • B-threads can examine the event triggered by the last bSync in bp.lastEvent. Don’t modify this field; don’t rely on it past another bSync() call.
  • This synchronization assumes that all b-threads will be good citizens and will not wait long (e.g., will not be involved in GUI input)

Event Sets and Interfaces

• The parameters to bSync are three sets of events, or sets of sets.
• Nesting of set containment is allowed, and not limited.
• RequestableEventInterface:
  • Required for requested event parameter of bSync();
  • Can be used also for waited-for and blocked.
  • Must contain an ordered set of concrete events, or ordered sets of requestableEventInterface (nesting of sets).
  • Implemented by RequestedEventsSet
• EventSetInterface:
  • Can be used for waited-for and blocked events.
  • The method contains() determines membership in the EventSetInterface object.
  • This set can describe very large or infinite sets of events, or be used to filter events.
  • The set can contain another EventSetInterface (neesting of sets).
  • Cannot be used as the requested events parameter of bSync(), because it does not provide an interator over the concrete events.
  • Implemented by EventSet
• RequestableEventSet: Implements both interfaces above
• EventSet: implements only EventSetInterface
• Event: The Event class implements the above interfaces. An individual event can be used instead of any of these sets. An event is also a set that contains the event.

Special Event Sets

• None: the empty set - contains no event. Used in calls to bSync() when one of the three parameters should be empty.
• All: contains all events. Most commonly used in bSync() when a b-thread such as a logger waits for all events.
• EventsOfClass: all events of a given class.
• Composable event sets
  • Available in BPJContrib (***ToDo: add BPJContrib to the package)
  • Allows specification of, e.g., theEventSet(A).and( not( theEventSet(B).or(C) ).xor( theEventSet(A).nand(c) ) )

anyOf( A, B, theEventSet(C).and(not(d)) )

The Application and the Main Method

• In the main method insert the line BProgram.startBApplication(my-app-class, my-package);
• You need to provide the method runBApplicatio. In it:
  • Instantiate and add b-threads to the b-program
  • Start the b-threads
  • You must assign unique real number priority to each b-thread. The smaller the value, the higher the priority.
  • Start any other parts (non-BP) of your application.
  • runBApplication may exit, or may wait for all b-threads to end.
• Example (see BPJ package for more detail):

import static bp.BProgram.bp; public class my-app-class implements BApplication {

  public void runBApplication() {
    bp.add(new my-Bthread-1(), mypriority1); 
    bp.add(new my-Bthread-2(), mypriority2); 
    . . . 
    bp.startAll();
   } 
  } 

Dynamic B-Threads

• New b-threads may be added by external (non behavioral) applications modules, or by b-threads
• A running Java thread may be registered as a b-thread and subsequently deregistered as follows:...

See examples in...

Injecting External Events

ToDo: add text here

[[Download | Prev] | Model Checking with BPmc