Difference between revisions of "The BPJ Library"

Latest revision as of 12:40, 27 April 2014

Examples

See examples in, e.g., BPJ/BPJCore110 -> bp.src.examples

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
• Instantiate or extend the BThread class.
• 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

• The execution environment and event-selection mechanism and for the application b-threads.
• An object of the class BProgram
• One instance of BProgram, called bp, is instantiated and made public and static for ready use by the application programmer.
• 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 B-Application

• A container and entry point for the application program.
• Class BApplication
• The programmer provides an instance of this class by implementing the main method and runBApplication method.
• The method main() should starts the b-application providing the class name of the application program and the package where it can be found. Be sure to specify these correctly as problems in loading the main class may not be reported correctly.

Example:

static public void main(String arg[]) {
try {
BProgram.startBApplication(AlternatingTaps.class, "bp.unittest");
} catch (Exception e) {
e.printStackTrace();
}
}

• In the method runBApplication instantiate and start your b-threads.
• You must assign unique real number priority to each b-thread. The smaller the value, the higher the priority.
• in runBApplication start any other parts (non-BP) of your application.
• runBApplication may exit, or may wait for all b-threads to end.

Example:

 public void runBApplication()    {
    System.out.println("runBApplication () at " + this);
    bp.add(new AddHotThreeTimes(), 1.0);
    bp.add(new AddColdThreeTimes(), 3.0);
    bp.add(new Interleave(), 4.0);
    bp.startAll();
  }

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.
• Example: The b-thread defaultOMoves requests all possible 9 O moves, with center first, then corners, and then the edge squares.

package tictactoe.bThreads.tactics;
import static bp.BProgram.bp;
import static bp.eventSets.EventSetConstants.none;
import tictactoe.events.O;
import bp.BThread;
import bp.eventSets.RequestableEventSet;
import bp.exceptions.BPJException;
/**
 * BThread that request all possible 9 moves - as default moves.
 * they "kick in" if no other strategy recommends anything.
 * 	 */
/**
 */
@SuppressWarnings("serial")
public class DefaultOMoves extends BThread {]
	@Override
	public void runBThread() throws BPJException {
		RequestableEventSet defaultMoves = new RequestableEventSet();
		defaultMoves.add(new O(1, 1));
 	        defaultMoves.add(new O(0, 0));
 		defaultMoves.add(new O(0, 2));
		defaultMoves.add(new O(2, 0));
		defaultMoves.add(new O(2, 2));
		defaultMoves.add(new O(0, 1));
		defaultMoves.add(new O(1, 0));
		defaultMoves.add(new O(1, 2));
		defaultMoves.add(new O(2, 1));
		while (true) {
			bp.bSync(defaultMoves, none, none);
		}
	} // end runBThread method
 	@Override
	public String toString() {
		return "DefaultMoves";
	}
} // end class

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.

Dynamic B-Threads

• New b-threads may be added by external (non behavioral) applications modules, or by b-threads
• A Java application, such as a GUI listener can inject behavioral events into a BPJ application by creating a dynamic b-thread, adding it to the BProgram, and starting it. When the new b-thread starts, its first bSync will join the next bSync of the rest of the b-threads.

In the following example, a listener method detects a button click on the square (cell) in the board in the game of Tic-Tac-Toe, and adds a seperatly defined b-thread ClickHandler that requests an X-player event for this square

   public void actionPerformed(ActionEvent myEvent) {
       final TTTButton btt = ((TTTButton) myEvent.getSource());
       BThread sc = new ClickHandler(btt.row,btt.col);
       bp.add(sc,20.0);
       sc.startBThread();
   }

   public class ClickHandler extends BThread {
       private int row,col;
       public ClickHandler(int row,int col) {
              this.row = row;
              this.col = col;
       }
       public void runBThread() {
              try {
                   bp.bSync(new Click(row, col) , none ,none );
              } catch (Exception e) {
                       e.printStackTrace();
                }
       }
       public String toString() {
              return "ClickHandler(" + row + "," + col + ")";
       }
   }

• A running Java thread can also register itself ed as a b-thread, using the bp.add API call, join in the synchronization scheme, request, block and wait for events, and subsequently deregister using bp.remove. This allows a Java thread to block itself when not registered with the B-Program, and thus not cause suspension of the entire behavioral program.