nodus 0.3.1

data/Rakefile

@@ -0,0 +1,55 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+require 'git'
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://guides.rubygems.org/specification-reference/ for more options
+  gem.name        = "nodus"
+  gem.homepage    = "http://github.com/exsig/nodus"
+  gem.license     = "MIT"
+  gem.summary     = "Something between a Kahn Process Network and Algorithmic Skeleton for parallel pipelining and signal processing"
+  gem.description = %Q{EXPERIMENTAL. A form of data-flow programming based loosely on Kahn Process Networks. Will allow
+                       for setting up operational components that can be pipelined together in a graph. Assumes all
+                       components (nodes) are 'online' algorithms with more or less steady-state resource utilization
+                       for continuous streams of data.}.gsub(/\s+/,' ')
+  gem.email       = "joseph.wecker@exsig.com"
+  gem.authors     = ["Joseph Wecker"]
+
+  # (dependencies are defined in the Gemfile)
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+desc "Code coverage detail"
+task :simplecov do
+  ENV['COVERAGE'] = "true"
+  Rake::Task['test'].execute
+end
+
+task :default => :test
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ''
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "nodus #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.3.1

data/dia.rb

@@ -0,0 +1,29 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), 'lib'))
+require 'nodus'
+include Nodus
+
+class A < Node
+  input :x
+  output :x
+end
+
+class B < Node
+  input :x
+  output :x
+end
+
+a = A[]
+b = B[]
+
+a.add_subscriber(b)
+
+puts a.to_dot

data/doc/desc.md

@@ -0,0 +1,191 @@
+Composition Rules
+-----------------
+
+Compositions should be parameterized one way or another- built dynamically and allowing for variable interpolation.
+
+Most composition nodes are given a `NodeList`, which consists of either:
+  * An ordered list of nodes (although order doesn't always matter)
+  * OR, a design-time function that calculates the list of nodes
+  * OR, a run-time function that calculates the list of nodes depending on token data (in which case we need to require
+    some sort of template / worst-case scenario etc. so that we can determine composition at a higher level? or maybe a
+    range specifier?)
+  * (with port-specifiers for individual nodes if necessary)
+
+Most accept one or more kernels (== `lambda`, `proc`, `block`, or misc. `class` constant with specific handlers/behavior)
+
+If a class handler, it will probably want to implement one or more of:
+  - Data Handler
+  - Upstream Exception Handler
+  - Downstream Exception Handler ?
+  - OOB Message Handler (such as N/A)
+
+### Core Custom Node
+
+#### Port types:
+
+`parameter: (optional[<default>] | required)`
+
+`| input:  (operational<output-port[s]> | consumed  [control]) x (optional | required)`
+
+`| output: ( operational<input-port[s]> | generated [control]) x (tap      |  primary)`
+
+
+
+##### Parameters
+  - **parameter**(default=nil): w/ optional default... specialized optional or required input port (probably not
+    implemented as actual message channel). Also possibly enforce the fact that it can't be connected to a stream.
+    Possibly composable / or able to be overridden kind of in parallel to other compositions. **optional** or
+    **required**. *These are also outputs. i.e., they are readable.* In fact they are intrinsicly different than normal
+    ports because they must be set before any real data comes through the node.
+
+##### Inputs
+  - **operational**(out-port[s]): port has paired output port that is stream-synchronized with this input.
+  - **control**: specialized (and implied) end-point used to help node make decisions. e.g., state / out-of-band messages
+  - **consumed**: End-point / Sink. Node reads input but doesn't have corresponding synchronized output.
+  - **optional**: Node can run without this being connected to anything (although not sure if they can connect at some
+    later point in time...)
+
+##### Outputs
+  - **operational**(in-port[s]): port has paired input port and this output adds to (or passes through) those input tokens.
+  - **controller**: Specialized (and implied) generated port used to help other nodes make decisions. Also state & out of band messages.
+  - **generated**: Origin / Generator. Node generates stream / it has no corresponding input port.
+  - **tap-point**: Output port that can optionally be tapped into (usually meaning it already has a listener within the node).
+
+
+#### Helpers / Quick Builders
+
+ - **Simple Generator**
+ - **Simple Processor**
+ - **Simple Consumer** = **Simple Fold**
+ - **Simple Projection**
+
+### Axiomatic
+
+**Node:**
+  * I=0..n (input ports) and O=0..n (output ports). Most of the time a static number, but sometimes a range of available
+    ports.
+
+**Connector:**
+  * *AdHoc*
+  * Given an arbitrary list of nodes, allows specifying connection pairs between available inputs/outputs.
+  * Result is a node with all remaining unconnected input and output ports
+  * Can also connect values to parameter inputs
+  * Essentially a curry function
+
+**Pipe:**
+  * *AdHoc*
+  * Connects member nodes on specified or default ports (specialized connector)
+  * All member nodes except last must have at least one output
+  * All member nodes except for first must have at least one input
+  * (like connector) result defined by unconnected inputs/outputs (usually just one main input and one main output)
+
+**Concurrent:**
+  * *AdHoc*
+  * Executes members concurrently. Input & output streams are all inputs and outputs of members.
+
+**Join:**
+  * *Stream-Synchronized*
+  * Token aware- meant to merge parallel branches of a single stream
+  * Unlimited input connections
+  * Listens for NOPs
+
+**Multiply:**
+  * *Stream-Synchronized*
+  * Single input port split into specified number of output ports
+  * Each branch (implicitly?) has its own parallel context on the token
+
+**View:**
+  * *Stream-Synchronized*
+  * Given a token, select a different set of fields to be the current context for downstream nodes
+
+**Filter:**
+  * *Stream-Synchronized* (NOP) OR *Projection* (Drop)
+  * Drop or NOP tokens matching certain criteria
+
+**Select:**
+  * *Stream-Synchronized* (NOP) OR *Projection* (Drop)
+  * Drop or NOP tokens not matching certain criteria
+
+### Composites
+
+
+**MultiMap**
+  * Multiply + Concurrent(Filter or Select, View, Node) + Join
+
+**Mux** (multiplex)
+  * *AdHoc* to *Stream-Synchronized*
+  * Multiple input streams
+  * Output token for each input token on _any_ input stream
+
+**Tap**
+  * *Stream-Synchronized*
+  * A Multiply, but defined differently so that it can be injected in another node (?) without changing that node's
+    functionality.
+  * Specify tap-point of other-node when constructing.
+
+**Runner**
+  * Usually automatically created
+  * Wraps a list of nodes into concurrent. Any inputs given stdin or integer sequences (?) and all outputs are
+    multiplexed to stdout.
+
+**StateSwitch**
+  * Has a state port and various output streams- state port helps it decide which filter/select branches are chosen
+    (allow either drop or nop?)
+
+**Split**
+  * Multiply + Concurrent(Filter or Select [with DROP], View, (optional Node))
+  * Like MultiMap except non-matching records are dropped- effectively creating unique streams
+
+As first token propagates, it's stream-id propagates with it. Nodes that are vertically stateful and therefore need to
+guarantee that the same stream is feeding them tokens at all time then use it for comparison.
+
+
+Scratch
+--------
+
+Instead of streams / branches maybe just dynamic recognition of which channels have something other than a 1:1
+input/output token ratio? I.e., which streams are totally synchronous so to speak...
+
+Lifecycle
+  - if it has non-delayed parameterization, it spawns and sets its parameters
+  - it can be given the output node at creation time, parameterization-time, or any time (even after it has received tokens from
+    at least one inbound stream) before it tries to emit a token on that stream.
+  - internal state machine runs until it needs its first token (if applicable) (or until it's output queue fills up too
+    much)
+  - proceeds to run state machine
+
+
+
+Compose Classes or Instances (or both)??
+
+
+Phases
+1. Kernel-design time:
+   - designate input/output ports/streams
+2. Design-time:
+   - specify bindings as much as possible
+   - compose
+   - pre-initialize/parameterize as appropriate
+   - specify process network / highest level compositions
+3. Pre-runtime:
+   - static compliance-check
+   - display process network graph
+   - warnings / errors as appropriate
+4. Runtime:
+   - dynamic parameterization as appropriate
+   - dynamic running nodes as appropriate
+   - contexts and real stream instances
+
+
+Specialized (out of band) input/output ports
+  - new output available
+  - new input available (?)
+  - output subscribed by...
+  - input bound by...
+
+  (allows nodes to communicate in an out-of-band fassion... easier to simply specify the peer object in initialize and
+  make sure every node has a general out-of-band communication channel where senders say who they are?)
+
+* Inputs can be bound to only one output
+* Outputs can be subscribed to by any number of other nodes
+* Binding to a node itself assumes the correct input/output if only one of either is available

data/doc/example.node

@@ -0,0 +1,89 @@
+
+
+
+
+node :app,      :the_gen >> :a >> :b
+node :the_gen,  1..1000
+node :a, 
+
+N[:app] = N[:the_gen] >> N[:a] >> N[:b]
+
+
+Nodus::Node.new do
+  app               = the_gen | a | b | stdout
+
+  the_gen(max=1000) = { 1..max } # Generator because no arity
+  a                 = {|x| x * 2 }
+  b                 = {|x| x + 100 }
+end
+
+  #pseudo_tick(first) = {
+
+# Basic: 
+
+
+
+# class TheNode < Nodus::Node
+#   def parameterize
+#   end
+# 
+#   def process
+# 
+#   end
+# end
+
+# class Ticker
+#   include Node
+# 
+#   def initialize(symbol)
+#     @symbol = symbol
+#   end
+# 
+#   def looped_run
+#     @last_price ||= 60 + rand(30)
+#     @last_price += @rand(-4..4)
+#     emit @last_price
+#   end
+# end
+
+class Ticker
+  def initialize(symbol)
+    @symbol = symbol
+  end
+
+  def each
+    loop do
+      @last_price ||= 60 + rand(30)
+      @last_price += @rand(-4..4)
+      emit [@last_price, Time.now]
+    end
+  end
+end
+
+
+def ticker_for(symb, high, low)
+  Pipe[Ticker.new(symb), Switch[->(x,_){x > high}, ->(x,t){ puts "+++ #{t}: Price above #{high}: #{x}" },
+                                ->(x,_){x < low }, ->(x,t){ puts "--- #{t}: Price below #{low }: #{x}" }]]
+end
+
+
+
+# node to node transformations
+# Composition operators NodusClass[...] expected to return another kind of Nodus class.
+# --- shorthand for currying parameters (including changing the description) via inheritance
+#
+# parameters = standardized key/value pairs so specialization works
+#            = always allow lambda/proc so it gets evaluated per incoming token(?) (implies parameterization gets set
+#            more than once...  hmmm... maybe a bad idea)
+#
+
+
+# P[N[:rand_dist_exp,5],
+# 
+# 
+# pipe rand_dist_exp(5)
+# 
+# junction(rand_dist_exp(5),
+#          rand_dist_exp(5),
+#          rand_dist_gaus(0,2)) 
+# 

data/doc/nodes.rb

@@ -0,0 +1,77 @@
+
+# | Node        | Input  | Output |
+# | ----------- | ------ | ------ |
+# | Processor   | 1/1    | 1/1    |
+# | View        | 1/1    | 1/1    |
+# | Generator   | 1/0    | 1/1    |
+# | Branch/Tap  | 1/1    | 1/n    |
+# | Recombine   | 1/n    | 1/1    |
+
+# | Set         | 0/0    | n
+# | Projection  | 1/1    | 1b/1b  |
+# | Sink        | 1/1    | 1b/1b  |
+# | Mux         | n/n*1  | 1/1    |
+# | Zip         | n/n*1  | 1/1    |
+# | Switch      | 1/1    | n/n*1  |
+# | StateSwitch | 2/2*1  | n/n*1  |
+# | Junction    | n/m    | o/p    |
+
+
+class Node
+  attr_reader :dot_style, :name
+  def initialize(name)
+    @name = name
+    @style_attrs = {}
+    style :shape,     :circle
+    style :fontname,  'Helvetica'
+    style :color,     '#222222'
+    style :fontcolor, '#444444'
+  end
+
+  def style(k,v)
+    @style_attrs[k] = v.to_s
+  end
+end
+
+class RootNode < Node
+  # (override how it's displayed)
+  # one or more g
+end
+
+class StandaloneNode < Node
+  # Starts with a generator
+end
+
+class Generator < Node
+  def initialize(*)
+    super
+    style :shape,       :trapezium
+    style :orientation, 270
+    style :style,       :filled
+    style :fillcolor,   '#CCEEDD'
+  end
+end
+
+
+class Branch < Node
+  def initialize(*)
+    super
+    style :shape,       :triangle
+    style :orientation, 90
+    style :style,       :filled
+    style :fillcolor,   '#EEDDCC'
+    style :label,       ''
+  end
+end
+
+class Merge < Node
+  def initialize(*)
+    super
+    style :shape,       :triangle
+    style :orientation, 270
+    style :style,       :filled
+    style :fillcolor,   '#EEDDCC'
+    style :label,       ''
+  end
+end
+