bud 0.0.2

data/docs/rebl.md

@@ -0,0 +1,99 @@
+REBL stands for "Read Eval Bud Loop" and is Bud's REPL.  Running REBL by typing in "rebl" causes the "rebl>" prompt to appear.  Input is either a collection definition, Bud statement, or REBL command.  REBL commands are prefixed by "/"; all other input is interpreted as Bud code.  If the input begins with either "table", "scratch" or "channel" (the currently-supported collection types), then the input is processed as a collection definition.  Otherwise, the input is processed as a Bud rule.
+
+Rules are not evaluated until a user enters one of the evaluation commands; either "/tick [x]" (tick x times, or once if optional argument x is not specified), or "/run" (runs in the background until a breakpoint is hit, execution stops, or a user inputs "/stop").  Rules may be added or deleted at any time, and collections may similarly be added at any time.
+
+A breakpoint is a Bud rule that has the "breakpoint" scratch on its left-hand-side.  The "/run" command will stop executing at the end of any timestep where a "breakpoint" tuple was derived.  Another invocation of "/run" will continue executing from the beginning of the next timestep.
+
+Let's step through two examples to better understand REBL.  The first example is a centralized all-pairs-all-paths example in a graph, the second example is a distributed ping-pong example.  These examples illustrate the use of the commands, which can be listed from within rebl by typing "/help".
+
+
+# Shortest Paths Example
+
+Let's start by declaring some collections.  "link" represents directed edges in a graph.  "path" represents all pairs of reachable nodes, with the next hop and cost of the path.
+
+    rebl> table :link, [:from, :to, :cost]
+    rebl> table :path, [:from, :to, :next, :cost]
+
+"/lscollections" confirms that the collections are defined.
+
+    rebl> /lscollections
+    1: table :link, [:from, :to, :cost]
+    2: table :path, [:from, :to, :next, :cost]
+
+We now define some rules to populate "path" based on "link".
+
+    rebl> path <= link {|e| [e.from, e.to, e.to, e.cost]}
+    rebl> temp :j <= (link*path).pairs(:to => :from)
+    rebl> path <= j { |l,p| [l.from, p.to, p.from, l.cost+p.cost] }
+
+Furthermore, we decide to print out paths to stdout.
+
+    rebl> stdio <~ path.inspected
+
+We provide some initial data to "link".
+
+    rebl> link <= [['a','b',1],['a','b',4],['b','c',1],['c','d',1],['d','e',1]]
+
+Ticking prints out the paths to stdout.
+
+    rebl> /tick
+    ["a", "c", "b", 5]
+    ["a", "e", "b", 4]
+    ["a", "b", "b", 1]
+    ["b", "d", "c", 2]
+    ["a", "c", "b", 2]
+    ["a", "d", "b", 6]
+    ["b", "e", "c", 3]
+    ["b", "c", "c", 1]
+    ["a", "d", "b", 3]
+    ["c", "e", "d", 2]
+    ["a", "e", "b", 7]
+    ["a", "b", "b", 4]
+    ["d", "e", "e", 1]
+    ["c", "d", "d", 1]
+
+This might be a bit annoying though.  Let's try to remove that rule using "/rmrule".  First, we need to figure out which rule it is, using "/lsrules".
+
+    rebl> /lsrules
+    5: link <= [['a','b',1],['a','b',4],['b','c',1],['c','d',1],['d','e',1]]
+    1: path <= link {|e| [e.from, e.to, e.to, e.cost]}
+    2: temp :j <= (link*path).pairs(:to => :from)
+    3: path <= j { |l,p| [l.from, p.to, p.from, l.cost+p.cost] }
+    4: stdio <~ path.inspected
+
+Looks like it's rule 4.
+
+    rebl> /rmrule 4
+
+Note how ticking no longer prints out the paths.
+
+    rebl> /tick
+
+
+# Ping-Pong Example
+
+We begin by starting up two instances of REBL on the same machine in different terminal windows.  Take note of the port number printed when REBL starts up.  For example, we might have:
+
+REBL1 : "Listening on localhost:33483"
+REBL2 : "Listening on localhost:48183"
+
+In each REBL, let us now define the following collections and rules:
+
+    rebl> channel :ping, [:@dst, :src]
+    rebl> ping <~ ping.map {|p| [p.src, p.dst]}
+
+In REBL1, type in an initial ping to start things off:
+
+    rebl> ping <~ [["localhost:48183", ip_port]]
+
+Note that no messages are exchanged until we either type "/tick [x]" or "/run".  Note that this program will run forever, as pings will contiuously be exchanged.  Let's set a breakpoint so both REBLs break once they've received their first ping.  In both REBLs, type:
+
+    rebl> breakpoint <= ping
+
+Note that the schema of "breakpoint" is unimportant.
+
+Now, let us "/run" both REBLs.  At a leisurely pace, type in "/run" to each REBL.  Hmm, what happened?  Type "/dump ping" on each REBL to see if it got a ping packet:
+
+    rebl> /dump ping
+
+Pings are no longer being exchanged.  Of course, if you want to remove a breakpoint, it is as simple as using "/lsrule" and "/rmrule x", where x is the rule ID shown by "/lsrule".  If you type a "/run" command and want to stop execution, simply type the "/stop" command.

data/docs/ruby_hooks.md

@@ -0,0 +1,19 @@
+## Ruby/Bloom interactions in Bud ##
+Bud embeds Bloom as a [DSL](http://en.wikipedia.org/wiki/Domain-specific_language) in Ruby.  On a given node, it is often useful to run a Ruby thread, and pass information to and from Bloom-land and Ruby-land.  If nothing else, this allows the Ruby process hosting the Bud evaluator to monitor its progress.
+
+As described in the [Getting Started](getstarted.md) document, we embed Bloom code into Ruby by including the `Bud` module in some Ruby class, and putting Bloom blocks into the class.  We then typically allocate a new instance of that class in Ruby, and invoke either its `run` method or `run_bg` method.  Since the Bud runtime typically runs indefinitely, the blocking `run` call essentially hands the thread over to Bud.  The `run_bg` call puts the Bud runtime into a second thread and returns to the caller.
+
+To support the `run_bg` case further, the Bud runtime provides hooks for  Ruby threads to register code with the runtime for execution during Bloom timesteps.  These hooks always run at the end of a timestep, after all Bloom statements have been processed for that timestep.  There are two basic types of hooks:
+
+* The Bud module provides a Ruby method called `sync_do`, which takes a block of code, and hands it to the Bud runtime for execution at the end of a timestep.  The Bud runtime is blocked during this execution, so the state of all Bud collections is fixed for the duration of the block of Ruby code. This is also a blocking call for the caller.  Bud also supplies `async_do`, which hands off the code block to the Bud runtime to be executed, but returns immediately to the caller without waiting for the runtime.
+
+* The Bud module provides a Ruby method called `register_callback`.  Given the name of a Bud collection, this method arranges for the given block of Ruby code to be invoked at the end of any timestep in which any tuples have been inserted into the specified collection. The code block is passed the collection as an argument; this provides a convenient way to examine the items inserted during that timestep. Note that because the Bud runtime is blocked while the callback is invoked, it can also examine any other Bud state freely.
+
+## Bud and Ruby-driven Side Effects ##
+The Bloom language itself is a pure logic language based in Dedalus.  Like any logic language, it has no notion of "mutable state" or "side effects".  Each item that appears in a Bloom collection at timestep T will *forever* be recorded as having been in that collection at timestep T, at least in a formal sense. The temporal logic of Dedalus is a lot like a versioning system, where old versions of items are never removed.
+
+In the context of the existing Bud prototype, though, it easy to step outside the bright lines of pure Bloom using straight Ruby code and libraries.  Methods like `sync_do` and callbacks allow Ruby code to be run that can mess with Bloom collections in a way that Bloom doesn't model.  Similarly, Ruby blocks *within* the rhs of a Bloom statement (e.g. after a collection name or a `pairs` call) can produce visible side-effects in unpredictable ways.  In particular, be aware that side-effecting Ruby code within a Bloom block may be called an *arbitrary* number of times during a single Bloom timestep, as it works its way to fixpoint.  
+
+If you must pollute your Bloom statements with side-effecting Ruby, please do it with *idempotent* side-effecting Ruby.  Thank you.
+
+In future versions of the Bud runtime we plan to limit the Ruby that gets invoked in the Bloom context, and keep you safe from these tendencies.  (As with a lot of the Bloom design, we hope to do this in a way that won't make you feel handicapped, just gently cradled in disorderly goodness.)

data/docs/visualizations.md

@@ -0,0 +1,75 @@
+# Visualizations
+
+BUD programs compile naturally to dataflows, and dataflows have a natural graphical representation.  Plotting a program as a graph can be useful to developers at various stages of program design, implementation and debugging.  BUD predicate dependency graphs (or PDGs) are described on [[PDGs]].
+
+BUD ships with two visualization utilities, __plotter__ and __visualizer__.  Both use _GraphViz_ to draw a directed graph representing the program state and logic.  __plotter__ provides a static analysis of the program, identifying sources and sinks of the dataflow, unconnected components, and points of order corresponding to logically nonmonotonic path edges. __visualizer__ is an offline debugging tool that analyses the trace of a (local) BUD execution and provides an interactive representation of runtime state over time.
+
+## The Plotter 
+
+[[https://github.com/bloom-lang/bud/blob/master/util/budplot]]
+
+The __plotter__ is a visual static analysis tool that aids in design and early implementation.  The most common uses of the __plotter__ are:
+
+1. Visual sanity checking: does the dataflow look like I expected it to look?
+2. Ensuring that a particular set of mixins is fully specified: e.g., did I forget to include a concrete implementation of a protocol required by other modules?
+   The Bloom module system, abstract interfaces and concrete implementations are described in more detail in [[modules]].
+3. Identifying dead code sections
+4. Experimenting with different module compositions
+5. Identifying and iteratively refining a program's points of order
+
+
+    $ ruby budplot 
+    USAGE:
+    ruby budplot LIST_OF_FILES LIST_OF_MODULES
+
+As its usage message indicates, __plotter__ expects a list of ruby input files, followed by a list of BUD modules to mix in.
+
+    $ ruby budplot kvs/kvs.rb ReplicatedKVS
+    Warning: underspecified dataflow: ["my_id", true]
+    Warning: underspecified dataflow: ["add_member", true]
+    Warning: underspecified dataflow: ["send_mcast", true]
+    Warning: underspecified dataflow: ["mcast_done", false]
+    fn is ReplicatedKVS_viz_collapsed.svg
+    $ open -a /Applications/Google\ Chrome.app/ ReplicatedKVS_viz_collapsed.svg
+
+__ReplicatedKVS__ includes the __MulticastProtocol__ and __MembershipProtocol__ protocols, but does not specify which implementation of these abstractions to use.  The program is underspecified, and this is represented in the resulting graph (ReplicatedKVS_viz_collapsed.svg) by a node labeled "??" in the dataflow.
+
+    $ ruby budplot kvs/kvs.rb ReplicatedKVS BestEffortMulticast StaticMembership
+    fn is ReplicatedKVS_BestEffortMulticast_StaticMembership_viz_collapsed.svg
+    $ open -a /Applications/Google\ Chrome.app/ ReplicatedKVS_BestEffortMulticast_StaticMembership_viz_collapsed.svg
+
+
+## The Visualizer
+
+[[https://github.com/bloom-lang/bud/blob/master/util/budvis]]
+
+To enable tracing, we need to set __:trace => true__ in the __BUD__ constructor, and optionally provide a __:tag__ to differentiate between traces by a human-readable name (rather than by object_id).  I modified the unit test `test/tc_kvs.rb` as follows:
+
+    - v = BestEffortReplicatedKVS.new(@opts.merge(:port => 12345))
+    - v2 = BestEffortReplicatedKVS.new(@opts.merge(:port => 12346))
+
+    + v = BestEffortReplicatedKVS.new(@opts.merge(:tag => 'dist_primary', :port => 12345, :trace => true))
+    + v2 = BestEffortReplicatedKVS.new(@opts.merge(:tag => 'dist_backup', :port => 12346, :trace => true))
+
+
+Then I ran the unit test:
+
+    $ ruby test/tc_kvs.rb 
+    Loaded suite test/tc_kvs
+    Started
+    .Created directory: TC_BestEffortReplicatedKVS_dist_primary_2160259460_
+    Created directory: TC_BestEffortReplicatedKVS_dist_primary_2160259460_/bud_
+    Created directory: TC_BestEffortReplicatedKVS_dist_backup_2159579740_
+    Created directory: TC_BestEffortReplicatedKVS_dist_backup_2159579740_/bud_
+    ..
+    Finished in 4.366793 seconds.
+    
+    3 tests, 14 assertions, 0 failures, 0 errors
+
+Then I ran the visualization utility:
+
+    $ ruby budvis TC_BestEffortReplicatedKVS_dist_primary_2160259460_/
+
+And finally opened the (chronological) first output file:
+
+    $ open -a /Applications/Google\ Chrome.app/ TC_BestEffortReplicatedKVS_dist_primary_2160259460_/tm_0_expanded.svg

data/examples/README

@@ -0,0 +1 @@
+A few simple examples are included here, but for more detailed and useful examples please see the [bud-sandbox](http://github.com/bloom-lang/bud-sandbox) repository.

data/examples/basics/hello.rb

@@ -0,0 +1,12 @@
+require 'rubygems'
+require 'bud'
+
+class HelloWorld
+  include Bud
+
+  bloom do
+    stdio <~ [["hello world!"]]
+  end
+end
+
+HelloWorld.new.tick