bud 0.0.2

data/docs/getstarted.md

@@ -0,0 +1,296 @@
+# Getting Started with Bud #
+In this document we'll do a hands-on tour of Bud and its Bloom DSL for Ruby.  We'll start with some examples, and introduce concepts as we go.
+
+## Installation ##
+You know the drill!
+
+    % gem install bud
+
+This installs four things:
+
+* The `Bud` module, to embed Bloom code in Ruby.
+* The `rebl` executable: an interactive shell for trying out Bloom.
+* The `budplot` and `budvis` executables: graphical tools for visualizing and debugging Bloom programs.
+
+## First Blooms ##
+
+### Hello, Clouds! ###
+It seems kind of a silly to do the old "Hello, World" example in a distributed programming language, but no tutorial would be complete without it...
+
+Open up a rebl prompt, and paste in the following:
+
+    stdio <~ [['Hello,'], ['Clouds']]
+    /tick
+    /q
+
+You should see something like this:
+
+    % rebl
+    Welcome to rebl, the interactive Bloom terminal.
+
+    Type: /h for help
+          /q to quit
+
+    rebl> stdio <~ [['Hello,'], ['Clouds']]
+    rebl> /tick
+    Hello,
+    Clouds
+    rebl> /q
+
+    Rebellion quashed.
+    %
+    
+Let's take this apart:
+
+1. The first line you pasted is a Bloom statement. It says (roughly) "merge the two strings 'Hello,' and 'Clouds' into the standard I/O (terminal) output stream."    Note that rebl doesn't execute that statement immediately!  It just remembers it as part of a set of statements.
+2. The second line starts with a slash, meaning it's a command to rebl.  It tells rebl to "tick" the Bloom runtime--that is, to evaluate the set of statements we've typed so far in a single atomic "timestep".  
+3. The third line is short for `/quit`.  (By the way, rebl auto-completes its commands with the tab key if you like.)
+
+For fun and illustration, start up rebl again and paste in this minor variation:
+
+    stdio <~ [['Hello,'], ['Clouds'], ['Clouds']]
+    /tick
+    /tick
+    /q
+    
+What happened?  
+
+First, note that the basic data structures in Bloom are *sets* of objects, which means they have no duplicates, and they have no defined order for their elements.  So you should only see 'Clouds' once on the terminal.  And in fact you may see 'Clouds' and 'Hello,' in either order. That is not a bug, that is a reflection of the disorderly set of values being placed into stdio during a given timestep!  (If you're a fan of duplicates and/or ordering, don't sweat it.  We'll show you how to achieve them.  But remember: Bloom is *disorderly* for a good reason--to reflect the reality of distributed systems execution.  So we're going to try and get you comfortable with being disorderly by default, to protect your ability to write simpler distributed code.  You'll need to use some additional syntax to impose order on in the disorderly context of a distributed system, but it's worth it!)
+
+Second, note that our Bud program's one statement merges the values on its right-hand-side (rhs) into the left-hand-side (lhs) at *every* timestep--every time you say `/tick`. If you ran this program as a server, it would generate an infinite stream of chatter! Generally it doesn't make sense to write server code with constants on the rhs of statements.  We'll see more sensible examples soon.
+
+### Tables and Scratches ###
+Before we dive into writing server code, let's try a slightly more involved single-timestep example.  Start up rebl again, and paste in the following:
+
+    table :clouds
+    clouds <= [[1, "Cirrus"], [2, "Cumulus"]]
+    stdio <~ clouds.inspected
+    
+Now tick your rebl, but don't quit yet.  
+
+    /tick
+    
+Hopefully the output looks sensible.  A few things to note here:
+
+1. the first line we pasted in is a Bloom *collection declaration*.  It declares the existence of a `table` named `clouds`.  By default, Bloom collections hold \[key, value\] pairs: i.e., arrays with the first field being a unique key, and the second a value. (Given an item `i` in a Bloom collection, you can access those fields as `i.key` and `i.val` respectively, or as `i[0]` and `i[1]`).
+2. The second line uses Bloom's `<=` merge operator.  This *instantaneously* merges the contents from the rhs of the statement into the lhs within the same timestep.
+
+3. The third line uses Bloom's `<~` merge operator.  We'll spend more time on the meaning of this operator later; for now just be aware that statements with `stdio` on the lhs *must* use `<~`.  (If you like, try starting over with `<=` instead of `<~` in that statement and see what happens.)
+4. the `inspected` method of BudCollections converts arrays of values into strings suitable for printing.  (Again, if you like you can try the program again, leaving out the `.inspected` method.)
+
+Now, let's use rebl's `lsrules` and `rmrule` commands to remove a Bloom statement (a.k.a. "rule") from our program.  Assuming you didn't quit from the last rebl prompt, you can proceed as follows:
+
+    /lsrules
+    /rmrule 1
+    /lsrules
+    
+Have a look at the output of each of those rebl commands--they're fairly self-explanatory.  You should see that we deleted the rule that instantaneously merged strings into the `clouds` table.  Now tick your rebl again.
+
+    /tick
+    /q
+    
+You still get output values on this second tick because the clouds table stored its content--even though the statement that populated that table was removed.
+
+In many cases we don't want a collection to retain its contents across ticks.  For those cases, we have `scratch` collections.  Start up a new rebl and try this variant of the previous example:
+
+    scratch :passing_clouds
+    passing_clouds <= [[3, "Nimbus"], [2, "Cumulonimbus"]]
+    stdio <~ passing_clouds.inspected
+    /tick
+    /lsrules
+    /rmrule 1
+    /tick
+    /q
+    
+See how the second tick produced no output this time?  After the first timestep, the passing\_clouds scratch collection did not retain its contents.  And without the first statement to repopulate it during the second timestep, it remained empty.
+
+### Summing Up ###
+In these initial examples we learned about a few simple but important things:
+
+* **rebl**: the interactive Bloom terminal and its `/` commands.
+* **Bloom collections**: unordered sets of items, which are set up by collection declarations.  So far we have seen persistent `table` and transient `scratch` collections.  By default, collections are structured as \[key,value\] pairs.
+* **Bloom statements**: expressions of the form *lhs op rhs*, where the lhs is a collection and the rhs is either a collection or an array-of-arrays.   
+* **Bloom timestep**: an atomic single-machine evaluation of a block of Bloom statements.
+* **Bloom merge operators**:
+  * The `<=` merge operator for *instantaneously* merging things into a collection.
+  * The `<~` merge operator for *asynchronously* merging things into collections outside the control of tick evaluation: e.g. terminal output.* 
+* **stdio**: a built-in Bloom collection that, when place on the rhs of an asynch merge operator `<~`, prints its contents to stdout.
+* **inspected**: a method of Bloom collections that transforms the elements to be suitable for textual display on the terminal.
+
+## Chat, World! ##
+Now that we've seen a bit of Bloom, we're ready to write our first interesting service that embeds Bloom code in Ruby.  We'll implement a simple client-server "chat" service. The full code for this program is in the `examples/chat` directory of the Bud distribution.  (Lest there be any confusion at this point, please note that Bloom isn't specifically designed for client/server designs.  Many examples in the [bud-sandbox](http://github.com/bloom-lang/bud-sandbox) repository are more like "peer-to-peer" or "agent-based" designs, which tend to work out as neatly as this one or moreso.)
+
+**Basic idea**: The basic idea of this program is that clients will connect to a chatserver process across the Internet.  When a client first connects to the server, the server will remember its address and nickname.  The server will also accept messages from clients, and relay them to other clients.
+
+Even though we're getting ahead of ourselves, let's have a peek at the Bloom statements that implement the server in `examples/chat/chat_server.rb`:
+
+    nodelist <= signup.payloads
+    mcast <~ (mcast * nodelist).pairs { |m,n| [n.key, m.val] }
+
+That's it!  There is one statement for each of the two sentences describing the behavior of the "basic idea" above.  We'll go through these two statements in more detail shortly.  But it's nice to see right away how concisely and naturally a Bloom program can fit our intuitive description of a distributed service.
+
+### The Server Side ###
+
+Now that we've satisfied our need to peek, let's take this a bit more methodically.  First we need declarations for the various Bloom collections we'll be using.  We put the declarations that are common to both client and server into file `examples/chat/chat_protocol.rb`:
+
+    module ChatProtocol
+      state do
+        channel :mcast
+        channel :connect
+      end
+      
+    DEFAULT_ADDR = "localhost:12345"
+    end
+
+This defines a [Ruby mixin module](http://www.ruby-doc.org/docs/ProgrammingRuby/html/tut_modules.html) called `ChatProtocol` that has a couple special Bloom features:
+
+1. It contains a Bloom `state` block, containing collection declarations.  When embedding Bloom in Ruby, all Bloom collection declarations must appear in a `state` block of this sort.
+2. This particular state block uses a kind of Bloom collection we have not seen before: a `channel`.  A channel collection is a special kind of scratch used for network communication.  It has a few key features:
+
+  * Unlike the default \[key,value\] structure of scratches and tables, channels default to the structure \[address,payload\]: the first field is a destination IP string of the form 'host:port', and the second field is a payload to be delivered to that destination--typically a Ruby array.  (For the record, the default key of a channel collection is the *pair* \[address,payload\]).
+  * Any Bloom statement with a channel on the lhs must use the async merge (`<~`) operator.  This instructs the runtime to attempt to deliver each rhs item to the address stored therein. In an async merge, each item in the collection on the right will appear in the collection on the lhs *eventually*.  But this will not happen instantaneously, and it might not happen atomically--items in the collection on the rhs may "straggle in" individually over time at the destination.  And if you're unlucky, this may happen after an arbitrarily long delay (possibly never).  The use of `<~` for channels reflects the typical uncertainty of real-world network delivery.  (Don't worry, the Bud sandbox provides libraries to wrap that uncertainty up in convenient ways.)
+
+Given this protocol (and the Ruby constant at the bottom), we're now ready to examine `examples/chat/chat_server.rb` in more detail:
+
+    require 'rubygems'
+    require 'bud'
+    require 'chat_protocol'
+
+    class ChatServer
+      include Bud
+      include ChatProtocol
+
+      state { table :nodelist }
+
+      bloom do
+        nodelist <= connect.payloads
+        mcast <~ (mcast * nodelist).pairs { |m,n| [n.key, m.val] }
+      end
+    end
+
+    if ARGV.first
+      addr = ARGV.first
+    else
+      addr = ChatProtocol::DEFAULT_ADDR
+    end
+
+    ip, port = addr.split(":")
+    puts "Server address: #{ip}:#{port}"
+    program = ChatServer.new(:ip => ip, :port => port.to_i)
+    program.run
+
+    
+The first few lines get the appropriate Ruby classes and modules loaded via `require`.  We then define the ChatServer class which mixes in the `Bud` module and the ChatProtocol module we looked at above.  Then we have another `state` block that declares one additional collection, the `nodelist` table.  
+
+With those preliminaries aside, we have our first `bloom` block, which is how Bloom statements are embedded into Ruby. Let's revisit the two Bloom statements that make up our server.  
+
+The first is pretty simple: 
+
+     nodelist <= connect.payloads
+
+This says that whenever messages arrive on the channel named "connect", their payloads (i.e. their non-address field) should be instantaneously merged into the table nodelist, which will store them persistently.  Note that nodelist has a \[key/value\] pair structure, so we expect the payloads will have that structure as well.
+
+The next Bloom statement is more complex.  Remember the description in the "basic idea" at the beginning of this section: the server needs to accept inbound chat messages from clients, and forward them to other clients.  
+
+    mcast <~ (mcast * nodelist).pairs { |m,n| [n.key, m.val] }
+    
+The first thing to note is the lhs and operator in this statement.  We are merging items (asynchronously, of course!) into the mcast channel, where they will be sent to their eventual destination.  
+
+The rhs is our first introduction to the `*` operator of Bloom collections, and the `pairs` method after it.  You can think of the `*` operator as "all-pairs": it produces a Bloom collection containing all pairs of mcast and nodelist items.  The `pairs` method iterates through these pairs, passing them through a code block via the block arguments `m` and `n`. Finally, for each such pair the block produces an item containing the `key` attribute of the nodelist item, and the `val` attribute of the mcast item.  This is structured as a proper \[address, value\] entry to be merged back into the mcast channel.  Putting this together, this statement *multicasts inbound payloads on the mcast channel to all nodes in the chat*.
+
+The remaining lines of plain Ruby simply instantiate and run the ChatServer class (which includes the `Bud` module) using an ip and port given on the command line (or the default from ChatProtocol.rb).
+
+#### `*`'s and Clouds ####
+You can think of out use of the `*` operator in the rhs of the second statement in a few different ways:
+
+* If you're familiar with event-loop programming, this implements an *event handler* for messages on the mcast channel: whenever an mcast message arrives, this handler performs lookups in the nodelist table to form new messages.  (It is easy to add "filters" to these handlers.)  The resulting messages are dispatched via the mcast channel accordingly.  This is a very common pattern in Bloom programs: handling channel messages via lookups in a table.
+
+* If you're familiar with SQL databases, the rhs is essentially a query that is run at each timestep, performing a CROSS JOIN of the mcast and nodelist "tables", with the SELECT clause captured by the block. (It is easy to add WHERE clauses to these joins.)  The resulting "tuples" are "inserted" into the lhs asynchronously (and typical on remote nodes).  This is a general-purpose way to think about the * operator. But as you've already seen, many common use cases for Bloom's * operator don't "feel" like database queries, because one or more of the collections is a scratch that is "driving" the program.
+
+We expect that people doing distributed programming are probably familiar with both of these metaphors, and they're both useful.  It's fairly common to think about rules in the first form, although the second form is actually closer to the underlying semantics of the language (which come from a temporal logic called [Dedalus](http://www.eecs.berkeley.edu/Pubs/TechRpts/2009/EECS-2009-173.html)).
+
+### The Client side ###
+Given our understanding of the server, the client should be pretty simple.  It needs to send an appropriately-formatted message on the `connect` channel to the server, send/receive messages on the `mcast` channel, and print the messages it receives to the screen.
+
+And here's the code:
+
+    require 'rubygems'
+    require 'bud'
+    require 'chat_protocol'
+
+    class ChatClient
+      include Bud
+      include ChatProtocol
+
+      def initialize(nick, server, opts)
+        @nick = nick
+        @server = server
+        super opts
+      end
+
+      # send connection request to server on startup
+      bootstrap do
+        connect <~ [[@server, [ip_port, @nick]]]
+      end
+
+      bloom :chatter do
+        # send mcast requests to server
+        mcast <~ stdio do |s|
+          [@server, [ip_port, @nick, Time.new.strftime("%I:%M.%S"), s.line]]
+        end
+        # pretty-print mcast msgs from server on terminal
+        stdio <~ mcast do |m|
+          [left_right_align(m.val[1].to_s + ": " \
+                            + (m.val[3].to_s || ''),
+                            "(" + m.val[2].to_s + ")")]
+        end
+      end
+
+      # format chat messages with timestamp on the right of the screen
+      def left_right_align(x, y)
+        return x + " "*[66 - x.length,2].max + y
+      end
+    end
+
+    if ARGV.length == 2
+      server = ARGV[1]
+    else
+      server = ChatProtocol::DEFAULT_ADDR
+    end
+
+    puts "Server address: #{server}"
+    program = ChatClient.new(ARGV[0], server, :read_stdin => true)
+    program.run
+
+The ChatClient class has a typical Ruby `initialize` method that sets up two local instance variables: one for this client's nickname, and another for the 'IP:port' address string for the server.  It then calls the initializer of the Bud superclass passing along a hash of options.
+
+The next block in the class is the first Bloom `bootstrap` block we've seen.  This is a set of Bloom statements that are evaluated only once, just before the first "regular" timestep of the system.  In this case, we bootstrap the client by sending a message to the server on the connect channel, containing the client's address (via the built-in Bud instance method `ip_port`) and chosen nickname.  
+
+After that comes a bloom block, with the name `:chatter`.  It contains two statements: one to take stdio input from the terminal and send it to the server via mcast, and another to receive mcasts and place them on stdio output.  The first statement has the built-in `stdio` scratch on the rhs: this includes any lines of terminal input that arrived since the last timestep.  For each line of terminal input, the `do...end` block formats an `mcast` message destined to the address in the instance variable `@server`, with an array as the payload.  The rhs of the second statement takes `mcast` messages that arrived since the last timestep.  For each message `m`, the `m.val` expression in the block returns the message payload; the call to the Ruby instance method `left_right_align` formats the message so it will look nice on-screen.  These formatted strings are placed (asynchronously, as before) into `stdio` on the left.
+
+The remaining lines are Ruby driver code to instantiate and run the ChatClient class (which includes the `Bud` module) using arguments from the command line.  Note the option `:read_stdin => true` to `ChatClient.new`: this causes the Bud runtime to capture stdin via the built-in `stdio` collection.
+
+### Running the chat ###
+You can try out our little chat program on a single machine by issuing each of the following shell commands from the `examples/chat` subdir within a separate window:
+
+    # ruby chatserver.rb
+
+    # ruby chat.rb alice
+
+    # ruby chat.rb bob
+
+    # ruby chat.rb harvey
+    
+Alternatively you can run the server and clients on separate nodes, specifying the server's IP:port pair on the command-line (consistently).
+    
+### Summing Up ###
+In this section we saw a number of features that we missed in our earlier single-timestep examples in rebl:
+
+* **state blocks**: Embedding of Bloom collection declarations into Ruby.
+* **bloom blocks**: Embedding of Bloom statements into Ruby.
+* **bootstrap blocks**: for one-time statements to be executed before the first timestep.
+* **channel collections**: collection types that enable sending/receiving asynchronous, unreliable messages
+* **the * operator and pairs method**: the way to combine items from multiple collections.
+
+# The Big Picture and the Details #
+Now that you've seen some working Bloom code, hopefully you're ready to delve deeper.  The [README](README.md) provides links to places you can go for more information.  Have fun and [stay in touch](http://groups.google.com/group/bloom-lang)!

data/docs/intro.md

@@ -0,0 +1,36 @@
+# *Bud*: Ruby <~ Bloom #
+
+Bud is a prototype of the [*Bloom*](http://bloom-lang.org) language for distributed programming, embedded as a DSL in Ruby.  "Bud" stands for *Bloom under development*.  The current 0.0.1 release is the initial alpha, targeted at "friends and family" who would like to engage at an early stage in the language design.
+
+## Distributed Code in Bloom ##
+The goal of Bloom is to make distributed programming far easier than it has been with traditional languages.  The key features of Bloom are:
+
+1. *Disorderly Programming*: Traditional languages like Java and C are based on the [von Neumann model](http://en.wikipedia.org/wiki/Von_Neumann_architecture), where a program counter steps through individual instructions in order. Distributed systems don’t work like that. Much of the pain in traditional distributed programming comes from this mismatch:  programmers are expected to bridge from an ordered programming model into a disorderly reality that executes their code.  Bloom was designed to match--and to exploit--the disorderly reality of distributed systems.   Bloom programmers write code made of unordered collections of statements, and use explicit constructs to impose order when needed.
+
+2. *A Collected Approach to Data Structures*: Taking a cue from successfully-parallelized models like MapReduce and SQL, the standard data structures in Bloom are *disorderly collections*, rather than scalar variables and nested structures like lists, queues and trees. Disorderly collection types reflect the realities of non-deterministic ordering inherent in distributed systems. Bloom provides simple, familiar syntax for manipulating these structures. In Bud, much of this syntax comes straight from Ruby, with a taste of MapReduce and SQL.
+
+3. *CALM Consistency*: Bloom enables powerful compiler analysis techniques based on the [CALM principle](http://db.cs.berkeley.edu/papers/cidr11-bloom.pdf) to reason about the consistency of your distributed code.  The Bud prototype includes program analysis tools that can point out precise *points of order* in your program: lines of code where a coordination library should be plugged in to ensure distributed consistency.
+
+4. *Concise Code*: Bloom is a very high-level language, designed with distributed code in mind.  As a result, Bloom programs tend to be far smaller (often [orders of magnitude](http://boom.cs.berkeley.edu) smaller) than equivalent programs in traditional imperative languages.
+
+## Alpha Goals and Limitations ##
+
+We had three main goals in preparing this release.  The first was to flesh out the shape of the Bloom language: initial syntax and semantics, and the "feel" of embedding it as a DSL.  The second goal was to build tools for reasoning about Bloom programs: both automatic program analysis, and tools for surfacing that analysis to developers.
+
+The third goal was to start a feedback loop with developers interested in the potential of the ideas behind the language.  We are optimistic that the principles underlying Bloom can make distributed programming radically simpler.  But we realize that those ideas only matter if programmers can adopt them naturally.  We intend Bud to be the beginning of an iterative design partnership with developers who see value in betting early on these ideas, and shaping the design of the language.  
+
+In developing this alpha release, we explicitly set aside some issues that we intend to revisit in future.  The first limitation is performance: Bud 0.0.1 is not intended to excel in single-node performance in terms of either latency, throughput or scale.  We do expect major improvements on all these fronts in future releases: many of the known performance problems have known solutions that we've implemented in prior systems, and we intend to revisit them for our beta release.  The second main limitation involves integration issues embedding Bloom as a DSL in Ruby.  In the spectrum from flexibility to purity, we leaned decidedly toward flexibility.  The barriers between Ruby and Bloom code are very fluid in the alpha, and we do relatively little to prevent programmers from ad-hoc mixtures of the two.  Aggressive use of Ruby within Bloom statements is likely to do something *interesting*, but not necessarily predictable or desirable.  This is an area where we expect to learn more from experience, and make some more refined decisions for the beta release.
+
+### Friends and Family: Come On In ###
+Although our team has many years of development experience, Bud is still open-source academic software built on a decidedly personal scale.
+
+This 0.0.1 alpha is targeted at "friends and family", and at developers who'd like to become same.  This is definitely the bleeding edge: we're in a rapid  cycle of learning about this new style of programming, and exposing what we learn in new iterations of the language.  If you'd like to jump on the wheel with us and play with Bud, we'd love your feedback--both success stories and constructive criticism.
+
+## Getting Started ##
+We're shipping Bud with a [sandbox](http://github.com/bloom-lang/bud-sandbox) of libraries and example applications for distributed systems.  These illustrate the language and how it can be used, and also can serve as mixins for new code you might want to write.  You may be surprised at how short the provided Bud code is, but don't be fooled.
+
+To get you started with Bud, we've provided a [quick-start tutorial](getstarted.md), instructions for [deploying distributed Bud](deployer.md) programs on Amazon's EC2 cloud, and a number of other docs you can find linked from the [README](README.md).
+
+We welcome both constructive criticism and (hopefully occasional) smoke-out-your-ears, hair-tearing shouts of frustration.  Please point your feedback cannon at the [Bloom mailing list](http://groups.google.com/group/bloom-lang) on Google Groups.
+
+Happy Blooming!

data/docs/modules.md

@@ -0,0 +1,112 @@
+# Code Structuring and Reuse in BUD
+
+## Language Support
+
+### Ruby Mixins
+
+The basic unit of reuse in BUD is the mixin functionality provided by Ruby itself.  BUD code is structured into modules, each of which may have its own __state__ and__bootstrap__ block and any number of __bloom__ blocks (described below).  A module or class may mix in a BUD module via Ruby's _include_ statement.  _include_ causes the specified module's code to be expanded into the local scope.
+
+### Bloom Blocks
+
+While the order and grouping of BUD rules have no semantic significance, rules can be grouped and tagged within a single module using __bloom__ blocks.  Bloom blocks serve two purposes:
+ 
+ 1. Improving readability by grouping related or dependent rules together.
+ 2. Supporting name-based overriding.
+
+(1) is self-explanatory.  (2) represents one of several extensibility mechanisms provided by BUD.  If a Module B includes a module A which contains a basket X, B may supply a bloom block X and in so doing replaces the set of rules defined by (A.)X with its own set.  For example:
+
+    require 'rubygems'
+    require 'bud'
+    
+    module Hello
+      state do
+        interface input, :stim
+      end
+      bloom :hi do
+        stdio <~ stim {|s| ["Hello, #{s.val}"]}
+      end
+    end
+    
+    module HelloTwo
+      include Hello
+      bloom :hi do
+        stdio <~ stim{|s| ["Hello, #{s.key}"]}
+      end
+    end
+    
+    class HelloClass
+      include Bud
+      include HelloTwo
+    end
+    
+    h = HelloClass.new
+    h.run_bg
+    h.sync_do{h.stim <+ [[1,2]]}
+
+The program above will print "Hello, 1", because the module HelloTwo overrides the bloom block named __hi__.  If we give the bloom block in HelloTwo a distinct name, the program will print "Hello, 1" and "Hello, 2" (in no guaranteed order).
+
+
+### The BUD Module Import System
+
+For simple programs, composing modules via _include_ is often sufficient.  But the flat namespace provided by mixins can make it difficult or impossible to support certain types of reuse.  Consider a module Q that provides a queue-like functionality via an input interface _enqueue_ and an output interface _dequeue_, each with a single attribute (payload).  A later module may wish to employ two queues (say, to implement a scheduler).  But it cannot include Q twice!  It would be necessary to rewrite Q's interfaces so as to support multiple ``users.'' 
+
+In addition to _include_, BUD supports the _import_ keyword, which instantiates a BUD module under a namespace alias.  For example:
+
+    module UserCode
+      import Q => :q1
+      import Q => :q2
+
+      bloom do
+        # insert into the first queue
+        q1.enqueue <= [....]
+      end
+    end
+
+
+## Techniques
+
+### Structuring 
+
+In summary, BUD extends the basic Ruby code structuring mechanisms (classes and modules) with bloom blocks, for finer-granularity grouping of rules 
+within modules, and the import system, for scoped inclusion.
+
+### Composition
+
+Basic code composition can achieved using the Ruby mixin system.  If the flat namespace causes ambiguity (as above) or hinders readability, the import system provides the ability to scope code inclusions.
+
+### Extension and Overriding
+
+Extending the existing functionality of a BUD program can be achieved in a number of ways.  The simplest (but arguably least flexible) is via bloom block overriding, as described in the Hello example above.  
+
+The import system can be used to implement finer-grained overriding, at the collection level.  Consider a module BlackBox that provides an input interface __iin__ and an output interface __iout__.  Suppose that we wish to "use" BlackBox, but need to provide additional functionality.  We may extend one or both of its interfaces by _import_'ing BlackBox, redeclaring the interfaces, and gluing them together.  For example, the module UsesBlackBox shown below interposes additional logic (indicated by ellipses) upstream of BlackBox's input interface, and provides ``extended'' BlackBox functionality.
+
+    module UsesBlackBox
+      import BlackBox => :bb
+      state do
+        interface input, :iin
+        interface output, :iout
+      end
+
+      bloom do
+        [ .... ] <= iin
+        bb.iin <= [ .... ]
+        iout <= bb.iout
+      end
+    end
+
+### Abstract Interfaces and Concrete Implementations
+
+In the previous example, UsesBlackBox extended the functionality of BlackBox by _interposing_ additional logic into its dataflow. 
+It was able to do this transparently because both implementations had the same externally visible interface: inserting tuples into __iin__ causes tuples to appear in __iout__.  In some (extremely underspecified) sense, the definition of this pair of interfaces constitutes an abstract contract which both implementations implement -- and the dependency of UsesBlackBox on Blackbox is just a detail of UsesBlackBox's implementation.
+
+The basic Ruby module system inherited by Bud may be used, by convention, to enable code reuse and hiding via the separation of abstract interfaces and concrete implementations.  Instead of reiterating the schema definitions in multiple state blocks, we will often instead declare a protocol module as follows:
+
+    module BBProtocol
+      # Contract: do XXXXXXXXXXX
+      state do
+        interface input, :iin
+        interface output, :iout
+      end
+    end
+
+Each implementation of the protocol would then include BBProtocol.  Though the interpreter treats this as an ordinary Ruby mixin, the interpretation is that by including BBProtocol, both BlackBox and UsesBlackBox _implement_ the protocol.  A downstream developer may then write code against the external interface, committing only when necessary to a fully-specified implmentation.

data/docs/operational.md

@@ -0,0 +1,96 @@
+# An Operational View Of Bloom #
+You may ask yourself: well, what does a Bloom program *mean*?  You may ask yourself: How do I read this Bloom code?  ([You may tell yourself, this is not my beautiful house.](http://www.youtube.com/watch?v=I1wg1DNHbNU)  But I digress.)
+
+There is a formal answer to these questions about Bloom, but there's also a more more approachable answer.  *Very* briefly, the formal answer is that Bloom's semantics are based in model theory, via a temporal logic language called *Dedalus* that is described in [a paper from Berkeley](http://www.eecs.berkeley.edu/Pubs/TechRpts/2009/EECS-2009-173.html). 
+
+While that's nice for proving theorems (and writing [program analysis tools](visualizations.md)), many programmers don't find model-theoretic discussions of semantics terribly helpful or even interesting. It's usually easier to think about how the language *works* at some level, so you can reason about how to use it.
+
+That's the goal of this document: to provide a relatively simple, hopefully useful intuition for how Bloom is evaluated.  This is not the only way to evaluate Bloom, but it's the intuitive way to do it, and basically the way that the Bud implementation works (modulo some optimizations).  
+
+## Bloom Timesteps ##
+Bloom is designed to be run on multiple machines, with no assumptions about coordinating their behavior or resources.  
+
+Each machine runs an evaluator that works in a loop, as depicted in this figure: 
+
+![Bloom Loop](bloom-loop.png?raw=true)
+
+Each iteration of this loop is a *timestep* for that node; each timestep is associated with a monotonically increasing timestamp (which is accessible via the `budtime` method in Bud). Timesteps and timestamps are not coordinated across nodes; any such coordination has to be programmed in the Bloom language itself.
+
+A Bloom timestep has 3 main phases:
+
+1. *setup*: All scratch collections are set to empty.  Network messages and periodic timer events are received from the runtime and placed into their designated `channel` and `periodic` scratches, respectively, to be read in the rhs of statements.  Note that a batch of multiple messages/events may be received at once.
+2. *logic*: All Bloom statements for the program are evaluated.  In programs with recursion through instantaneous merges (`<=`), the statements are repeatedly evaluated until a *fixpoint* is reached: i.e. no new lhs items are derived from any rhs.
+3. *transition*: Items derived on the lhs of deferred operators (`<+`, `<-`) are placed into/deleted from their corresponding collections, and items derived on the lhs of asynchronous merge (`<~`) are handed off to external code (i.e. the local operating system) for processing.
+
+It is important to understand how the Bloom collection operators fit into these timesteps:
+
+* *Instantaneous* merge (`<=`) occurs within the fixpoint of phase 2.
+* *Deferred* operations include merge (`<+`) and delete (`<-`), and are handled in phase 3.  Their effects become visible atomically to Bloom statements in phase 2 of the next timestep.
+* *Asynchronous* merge (`<~`) is initiated during phase 3, so it cannot affect the current timestep.  When multiple items are on the rhs of an async merge, they may "appear" independently spread across multiple different future local timesteps.
+
+
+## Atomicity: Timesteps and Deferred Operators ##
+
+The only instantaneous Bloom operator is a merge (`<=`), which can only introduce additional items into a collection--it can not delete or change existing items.  As a result, all state within a Bloom timestep is *immutable*: once an item is in a collection at timestep *T*, it stays in that collection throughout timestep *T*.
+
+To get atomic state change in Bloom, you exploit the combination of two language features: 
+
+1. the immutability of state in a single timestep, and 
+2. the uninterrupted sequencing of consecutive timesteps.  
+
+State "update" is achieved in Bloom via a pair of deferred statements, one positive and one negative, like so:
+
+    buffer <+ [[1, "newval"]]
+    buffer <- buffer {|b| b if b.key == 1}
+
+This atomically replaces the entry for key 1 with the value "newval" at the start of the next timestep.
+
+Any reasoning about atomicity in Bloom programs is built on this simple foundation.  It's really all you need.  In the bud-sandbox we show how to build more powerful atomicity constructs using it, including things like enforcing [message ordering across timesteps](https://github.com/bloom-lang/bud-sandbox/tree/master/ordering), and protocols for [agreeing on ordering of distributed updates](https://github.com/bloom-lang/bud-sandbox/tree/master/paxos) across all nodes.
+
+## Recursion in Bloom ##
+Because Bloom is data-driven rather than call-stack-driven, recursion may feel a bit unfamiliar at first.
+
+Have a look at the following classic "transitive closure" example, which computes multi-hop paths in a graph based on a collection of one-hop links:
+
+    state do
+      table :link, [:from, :to, :cost]
+      table :path, [:from, :to, :cost]
+    end
+
+    bloom :make_paths do
+      # base case: every link is a path
+      path <= link {|e| [e.from, e.to, e.cost]}
+
+      # recurse: path of length n+1 made by a link to a path of length n
+      path <= (link*path).pairs(:to => :from) do |l,p|
+        [l.from, p.to, l.cost+p.cost]
+      end
+    end
+    
+The recursion in the second Bloom statement is easy to see: the lhs and rhs both contain the path collection, so path is defined in terms of itself.
+
+You can think of this being computed by reevaluating the bloom block over and over--within a single timestep--until no more new paths are found.  In each iteration, we find new paths that are one hop longer than the longest paths found previously.  When no new items are found in an iteration, we are at what's called a *fixpoint*.
+
+Hopefully that description is fairly easy to understand.  You can certainly construct more complicated examples of recursion--just as you can in a traditional language (e.g., simultaneous recursion.)  But understanding this example of simple recursion is probably sufficient for most needs.
+
+## Non-monotonicity and Strata ##
+
+Consider augmenting the previous path-finding program to compute only the "highest-cost" paths between each source and destination, and print them out.  We can do this by adding another statement to the above:
+
+    bloom :print_highest do
+      stdio <~ path.argmax([:from, :to], :cost)
+    end
+
+The `argmax` expression in the rhs of this statement finds the items in path that have the maximum cost for each `[from, to]` pair.
+  
+It's interesting to think about how to evaluate this statement.  Consider what happens after a single iteration of the path-finding logic listed above.  We will have 1-hop paths between some pairs.  But there will likely be multi-hop paths between those pairs that cost more.  So it would be premature after a single iteration to put anything out on stdio.  In fact, we can't be sure what should go out to stdio until we have hit a fixpoint with respect to the path collection.  That's because `argmax` is a logically *non-monotonic* operator: as we merge more items into its input collection, it may have to "retract" an output they would previously have produced. 
+
+The Bud runtime takes care of this problem for you under the covers, by breaking your statements in *strata* (layers) via a process called *stratification*.  The basic idea is simple.  The goal is to postpone evaluating non-monotonic operators until fixpoint is reached on their input collections.  Stratification basically breaks up the statements in a Bloom program into layers that are separated by non-monotonic operators, and evaluates the layers in order.  
+
+For your reference, the basic non-monotonic Bloom operators include `group, reduce, argmin, argmax`.  Also, statements that embed Ruby collection methods in their blocks are often non-monotonic--e.g., methods like `all?, empty?, include?, none?` and `size`.
+
+Note that it is possible to write a program in Bloom that is *unstratifiable*: there is no way to separate it into layers like this.  This arises when some collection is recursively defined in terms of itself, and there is a non-monotonic method along the recursive dependency chain.  A simple example of this is as follows:
+
+    glass <= one_item {|t| ['full'] if glass.empty? }
+
+Consider the case where we start out with glass being empty.  Then we know the fact `glass.empty?`, and the bloom statement says that `(glass.empty? => not glass.empty?)` which is equivalent to `(glass.empty? and not glass.empty?)` which is a contradiction.  The Bud runtime detects cycles through non-monotonicity for you automatically when you instantiate your class.