redis_message_capsule 0.8.1 → 0.8.2

data/README.md

@@ -1,133 +1,95 @@
 # RedisMessageCapsule
 
 Send messages between node or rails apps asynchronously (via redis).
+
 * [report an issue with the ruby version] (https://github.com/arbind/redis_message_capsule/issues)
 * [report an issue with the node version] (https://github.com/arbind/redis_message_capsule-node/issues)
 
-## Installation (with npm for node) (as a gem for ruby)
-
-    $ npm install redis-message-capsule
-    $ gem install redis_message_capsule
-Note that the javascript version is named with dashes, ruby with underscore
+## Installation
 
-## Usage
-RedisMessageCapsule is used in the same way for both node and ruby (just the syntax is different, naturally).
+**in node**:
 
-The pseudo code goes something like this:
+    $ npm install redis_message_capsule
 
-    # 1. Create a capsule that is bound to the redis DB:
-    > load RedisMessageCapsule
-    > capsule = materializeCapsule(redisURL, dbNumber)
+**in ruby**:
 
-    # 2. Create a named channel that you want to send or receive messages on
-    > catChannel = capsule.materializeChannel('cat')
+    $ gem install redis_message_capsule
 
-    # 3.a Either: Send messages on the channel:
-    > catChannel.send('meeeooow')
-    > catChannel.send('roooaaar')
+## Usage
+The purpose of RedisMessageCapsule is to enable separate apps to communicate with each other asynchronously.
 
-    # 3.b Or: Handle the messages that are recieved on the channel:
-    > messageHandler = { |message| doSomethingWith(message) }
-    > catChannel.register(messageHandler) 
+### Make sure redis is running:
+The code below defaults to using redis running on localhost
 
-    # 4. Create as many channels and listeners as you want, using the capsule.
+### Open 2 terminal windows to simulate any mixture of ruby or node apps:
+Both windows can be ruby, can be node, or one can be ruby and one can be node.
 
-    # 5. Create as many capsules as you want (only need one capsule for each redisURL:dbNumber )
+### To Send Messages From Window 1
+**in node**:
 
-The purpose of RedisMessageCapsule is to enable separate apps to communicate with each other asynchronously.
+    $ node
+    require('redis_message_capsule')
+    redisurl = 'redis://127.0.0.1:6379/' 
+    capsule = RedisMessageCapsule.capsule(redisurl)
+    cat = capsule.channel('cat')
+    cat.send('meow')
+    cat.send('meow')
 
-So, normally, one app would do the sending and another would listen for the message.
-However, nothing restricts the same app from doing the sending as well as receiving its own message.
+**in ruby**:
 
-## Advanced Usage
-This is not your typical pub/sub model as messages are not broadcast to all apps that are listening on a channel.
+    $ irb
+    require('redis_message_capsule')
+    redisurl = 'redis://127.0.0.1:6379/' 
+    capsule = RedisMessageCapsule.capsule(redisurl)
+    cat = capsule.channel('cat')
+    cat.send('meow')
+    cat.send('meow')
 
-If multiple apps are listening on a channel, only one will actually receive the message.
-Each app can register multiple handlers for a channel, but only one app will actually get the message for processing.
+### To Receive messages In Window 2
+**in node**:
 
-In ruby, the listeners will block waiting for a message, so the app that is waiting the longest would get the message.
+    $ node
+    require('redis_message_capsule')
+    redisurl = 'redis://127.0.0.1:6379/' 
+    capsule = RedisMessageCapsule.capsule(redisurl)
+    cat = capsule.channel('cat')
+    cat.register(function(err, message){ console.log(message) })
 
-With node, however, there is no guarentee of order, since the listeners are not blocking the event loop.
+**in ruby**:
 
-## Demonstration
-Below are code demonstrations for sending messages between 2 apps (node apps, ruby apps and a combination of both).
+    $ irb
+    require('redis_message_capsule')
+    redisurl = 'redis://127.0.0.1:6379/' 
+    capsule = RedisMessageCapsule.capsule(redisurl)
+    cat = capsule.channel('cat')
+    cat.register { |msg|  puts msg }
 
-* Make sure redis is running
-* Data or object being sent will automatically be serialized to json (in order to teleport through redis)
-  * in node: using obj.toJSON() or JSON.stringify(obj)
-  * in rails: using obj.to_json 
-* Demo for node <-> node: Open 2 terminal windows to send messages between 2 node apps  (outlined below)
-* Demo for ruby <-> ruby: Open 2 terminal windows to send messages between 2 ruby apps  (outlined below)
-* Demo for node <-> ruby: Open 4 terminal windows and do both of the demos above (which are outlined below)
-* Think of each window that you open as a stand-alone app
+### To Send More Messages From Window 1
+**in node**:
 
-### Demo for node <-> node
-In node window 1 - send cat messages:
+    cat.send(9)
+    talk = { say: 'roar', time: new Date() }        // <- to create a hash in node
+    cat.send( talk )
 
-    $ node
-    RedisMessageCapsule = require('redis-message-capsule')
-    redisURL = process.env.REDIS_URL || process.env.REDISTOGO_URL || 'redis://127.0.0.1:6379/' 
-    capsule = RedisMessageCapsule.materializeCapsule(redisURL)
-    cat = capsule.materializeChannel('cat')
-    cat.send('meow')    // will show up in node window 2 (listening to cat)
-    cat.send('meow')    // will show up in node window 2 (listening to cat)
- 
-In node window 2 - listen for cat messages, send messages from dog:
+**in ruby**:
 
-    $ node
-    RedisMessageCapsule = require('redis-message-capsule')
-    redisURL = process.env.REDIS_URL || process.env.REDISTOGO_URL || 'redis://127.0.0.1:6379/' 
-    capsule = RedisMessageCapsule.materializeCapsule(redisURL)
-    cat = capsule.materializeChannel('cat')
-    cat.register( function(err, message){ console.log(message) }  ) 
-    // => meow
-    // => meow    
-    // create a dog channel to send messages to ruby, and start barking
-    dog = capsule.materializeChannel('dog')
-    dog.send('woof')  // will show up in ruby window 2 (listening to dog)
-
-In node window 1 - send more cat messages:
-
-    talk = { say: 'roar', time: new Date() }
     cat.send(9)
+    talk = { say: 'grrrrrr', time: Time.now }       #  <- to create a hash in ruby
     cat.send( talk )
-    // Watch for real-time messages show up in node window 2:
-    // => 9 
-    // => {"say"=>"roar", "time"=>"2012-11-21T208:08:08.808Z"} 
-
-###  Demo for ruby <-> ruby
-In ruby window 1 - send dog messages:
 
-    $ irb
-    require 'redis_message_capsule'
-    redisURL = ENV["REDIS_URL"] || ENV["REDISTOGO_URL"] || "redis://127.0.0.1:6379/"
-    capsule = RedisMessageCapsule.materialize_capsule redisURL
-    dog = capsule.materialize_channel 'dog'
-    dog.send 'bark'
+* Use the module to create as many capsules as you want  (only need one capsule for each redisurl:redisdbnum)
+* Use a capsule to create as many channels as you want   (use 'ns:channelname' to add a namespace to your channel)
+* Use a channel to send as many messages as you want     (be sure the data you send can be serialized to json )
+* Use a channel to register as many handlers as you want (all registered handlers on a channel will get messages)
+* Send messages between any mixture of apps: [ node <-> node ] or [ ruby <-> ruby ] or [ node <-> ruby ]
 
-In ruby window 2 -  listen for dog messages in ruby and send cat messages:
+## Advanced Usage
+This module sends messages in a queue rather than a typical pub/sub model: messages are not broadcast to all apps.
 
-    $ irb
-    require 'redis_message_capsule'
-    redisURL = ENV["REDIS_URL"] || ENV["REDISTOGO_URL"] || "redis://127.0.0.1:6379/"
-    capsule = RedisMessageCapsule.materialize_capsule redisURL
-    dog = capsule.materialize_channel 'dog'
-    dog.register { |msg|  puts "#{msg}!" * 2 }
-    # => woof!woof!
-    # => bark!bark!
-    # create a cat channel to send messages to node
-    cat = capsule.materialize_channel 'cat'
-    cat.send 'purrr' # will show up in node window 2 (listening to cat)
-
-Back in ruby window 1 - send more dog messages:
-
-    talk = { say: 'grrrrrr', time: Time.now }
-    dog.send 2      # will show up in window 4 (listening to dog)
-    dog.send talk   # will show up in window 4 (listening to dog)
-    # Watch for real-time messages to show up in ruby window 2:
-    # => 2 
-    # => {"say"=>"grrrrrr", "time"=>"2012-11-21 08:08:08 -0800"} 
-    # => purr
+### Multiple Listeners on a Channel Will Round Robin
+* If multiple apps are listening on the same channel, only one will actually receive the message and pass it on to its registered handlers for processing.
+* Listeners run in their own thread (in ruby) or fiber(in node) and may block waiting for a message.
+* When a message comes in, only the app that was waiting the longest will receive it.
 
 ## Environment
 In order for 2 apps to send messages to each other, they must bind a capsule to the same redis DB and select the same db number.
@@ -140,7 +102,7 @@ The selected db can also be overriden when materializing a capsule  (examples ar
 
 If 2 apps are not sending messages to each other:
 * check that they are both in the same environment (test, development, production)
-* or be sure to override using same dbNumber when materializing a capsule.
+* or be sure to override using same redisdb when materializing a capsule.
 
 ## Environment for node
 In node use one of the following to set your environment
@@ -151,10 +113,10 @@ In node use one of the following to set your environment
 
 Alternatively, you can specify exactly what you want when materializing a capsule:
 
-    RedisMessageCapsule = require('redis-message-capsule')
-    redisURL = process.env.REDIS_URL || process.env.REDISTOGO_URL || 'redis://127.0.0.1:6379/' 
-    dbNumber = 5
-    capsule = RedisMessageCapsule.materializeCapsule(redisURL, dbNumber)
+    RedisMessageCapsule = require('redis_message_capsule')
+    redisurl = process.env.REDIS_URL || process.env.REDISTOGO_URL || 'redis://127.0.0.1:6379/' 
+    redisdb = 5
+    capsule = RedisMessageCapsule.capsule(redisurl, redisdb)
 
 ## Environment for ruby
 In ruby use one of the following to set your environment
@@ -166,15 +128,15 @@ In ruby use one of the following to set your environment
 Alternatively, you can specify exactly what you want when materializing a capsule:
 
     require 'redis_message_capsule'
-    redisURL = ENV["REDIS_URL"] || ENV["REDISTOGO_URL"] || "redis://127.0.0.1:6379/"
-    dbNumber = 5
-    capsule = RedisMessageCapsule.materialize_capsule redisURL, dbNumber
+    redisurl = ENV["REDIS_URL"] || ENV["REDISTOGO_URL"] || "redis://127.0.0.1:6379/"
+    redisdb = 5
+    capsule = RedisMessageCapsule.capsule redisurl, redisdb
 
 ## To build the gem locally:
     git clone git@github.com:arbind/redis_message_capsule-gem.git
     cd redis_message_capsule-gem
     bundle
-    
+
     gem uninstall redis_message_capsule
     gem build redis_message_capsule.gemspec
     rake install

data/lib/redis_message_capsule/version.rb

@@ -1,3 +1,3 @@
 module RedisMessageCapsule
-  VERSION = "0.8.1"
+  VERSION = "0.8.2"
 end

data/lib/redis_message_capsule.rb

@@ -82,6 +82,9 @@ class RedisMessageCapsule::Capsule
   def materialize_channel(channel_name)
     channels[channel_name] ||= (Channel.new channel_name, redis_client, redis_uri, db_number)
   end
+  alias_method :channel, :materialize_channel
+  alias_method :make_channel, :materialize_channel
+  alias_method :create_channel, :materialize_channel
 
 end
 
@@ -168,7 +171,6 @@ class RedisMessageCapsule::Capsule::Channel::Listener
             element = channel_element.last
             payload = ( JSON.parse(element) rescue {'data' => 'error parsing json!'} )
             message = payload['data']
-            puts @handlers.count
             @handlers.each { |handler| handler.call(message) }
           end
         rescue Exception => e

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis_message_capsule
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-24 00:00:00.000000000 Z
+date: 2012-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis