grafos-ml/okapi — pull request #7 by kilburn (2014-03-30 19:45:26+00:00)
Title: New facilities to implement multi-stage algorithms.

Implementing multi-stage algorithms is currently a bit cumbersome. Essentially, there are two different approaches:

1. Use a single `Computation` class: track the algorithm stage through an aggregated flag, and use `if`s to perform one computation or another according to that flag.
2. Use multiple `Computation` classes and use a custom `MasterCompute` to switch classes when appropriate.

These approaches work, but lead to cumbersome non-modular code. Furthermore, it is hard to perform stage transitions when these are not fully controlled by the `MasterCompute` (that is, when vertices may trigger algorithm stage changes). Using the new multistage facilities, the resulting code is now simpler and cleaner. The basic instructions are the following:

1. Implement an enumerator listing the stages of your algorithm
2. Implement a master that extends `MultistageMasterComputation`
3. Implement a `StageComputation` for each of the stages of your computation

Aside from the cleaner and more organized result when using these new multi-stage facilities, there is a major advantage: stage transition handling.

Your new master can allow vertices to vote to change the stage of the algorithm. Thus, vertices can vote when they "think" a transition should happen. Thereafter, the master collects vertices votes, and changes (or not) the algorithm stage according to some election rules.

Examples of built-in elections include:
- majority election: a simple majority among the vertices that voted is enough to induce a stage change.
- unanimity election: all vertices must vote, and vote for the same transition in order for it to happen.

and a few more (find them in the `ml.grafos.okapi.multistage.votes` package).

This pull request includes a fully commented example of a (dummy) multi-stage algorithm in the `MultistageMasterComputeTest` class that can be used as a reference to implement other multistage algorithms.