RubyGems - celluloid_pubsub - Versions diffs - 0.0.5 → 0.0.6 - Mend

celluloid_pubsub 0.0.5 → 0.0.6

Files changed (36) hide show

checksums.yaml +4 -4
data/.gitignore +1 -0
data/.rubocop.yml +1 -1
data/Guardfile +4 -0
data/Rakefile +12 -1
data/bin/inch +16 -0
data/bin/sparkr +16 -0
data/celluloid_pubsub.gemspec +2 -1
data/doc/CelluloidPubsub/Client/PubSubWorker.html +3676 -0
data/doc/CelluloidPubsub/Client.html +340 -0
data/doc/CelluloidPubsub/Reactor.html +3502 -0
data/doc/CelluloidPubsub/Registry.html +234 -0
data/doc/CelluloidPubsub/VERSION.html +204 -0
data/doc/CelluloidPubsub/WebServer.html +4275 -0
data/doc/CelluloidPubsub.html +225 -0
data/doc/_index.html +184 -0
data/doc/class_list.html +58 -0
data/doc/css/common.css +1 -0
data/doc/css/full_list.css +57 -0
data/doc/css/style.css +339 -0
data/doc/file.README.html +226 -0
data/doc/file_list.html +60 -0
data/doc/frames.html +26 -0
data/doc/index.html +226 -0
data/doc/js/app.js +219 -0
data/doc/js/full_list.js +181 -0
data/doc/js/jquery.js +4 -0
data/doc/method_list.html +357 -0
data/doc/top-level-namespace.html +112 -0
data/examples/simple_test.rb +3 -1
data/lib/celluloid_pubsub/client_pubsub.rb +117 -0
data/lib/celluloid_pubsub/reactor.rb +138 -7
data/lib/celluloid_pubsub/registry.rb +3 -0
data/lib/celluloid_pubsub/version.rb +15 -2
data/lib/celluloid_pubsub/web_server.rb +112 -0
metadata +41 -10

data/doc/top-level-namespace.html ADDED Viewed

@@ -0,0 +1,112 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.8.7.6
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
+<script type="text/javascript" charset="utf-8">
+  hasFrames = window.top.frames.main ? true : false;
+  relpath = '';
+  framesUrl = "frames.html#!top-level-namespace.html";
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <div id="header">
+      <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+  <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
+</div>
+      <div id="search">
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+      Class List
+    </a>
+    <a class="full_list_link" id="method_list_link"
+        href="method_list.html">
+      Method List
+    </a>
+    <a class="full_list_link" id="file_list_link"
+        href="file_list.html">
+      File List
+    </a>
+</div>
+      <div class="clear"></div>
+    </div>
+    <iframe id="search_frame"></iframe>
+    <div id="content"><h1>Top Level Namespace
+</h1>
+<dl class="box">
+</dl>
+<div class="clear"></div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="CelluloidPubsub.html" title="CelluloidPubsub (module)">CelluloidPubsub</a></span>
+</p>
+</div>
+    <div id="footer">
+  Generated on Fri Mar 13 12:25:42 2015 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.8.7.6 (ruby-2.0.0).
+</div>
+  </body>
+</html>

data/examples/simple_test.rb CHANGED Viewed

@@ -1,6 +1,7 @@
 require 'bundler/setup'
 require 'celluloid_pubsub'
+# actor that subscribes to a channel
 class Subscriber
   include Celluloid
   include Celluloid::Logger
@@ -18,9 +19,10 @@ class Subscriber
   def on_close(code, reason)
     puts "websocket connection closed: #{code.inspect}, #{reason.inspect}"
     terminate
-   end
   end
+end
+# actor that publishes a message in a channel
 class Publisher
   include Celluloid
   include Celluloid::Logger

data/lib/celluloid_pubsub/client_pubsub.rb CHANGED Viewed

@@ -1,10 +1,49 @@
 module CelluloidPubsub
+  # class used to make a new connection in order to subscribe or publish to a channel
   class Client
+    # worker that subscribes to a channel or publishes to a channel
+    # if it used to subscribe to a channel the worker will dispatch the messages to the actor that made the
+    # connection in the first place.
+    #
+    # @!attribute actor
+    #   @return [Celluloid::Actor] actor to which callbacks will be delegated to
+    #
+    # @!attribute connect_blk
+    #   @return [Proc] Block  that will execute after the connection is opened
+    #
+    # @!attribute client
+    #   @return [Celluloid::WebSocket::Client] A websocket client that is used to chat witht the webserver
+    #
+    # @!attribute options
+    #   @return [Hash] the options that can be used to connect to webser and send additional data
+    #
+    # @!attribute hostname
+    #   @return [String] The hostname on which the webserver runs on
+    #
+    # @!attribute port
+    #  @return [String] The port on which the webserver runs on
+    #
+    # @!attribute path
+    #   @return [String] The hostname on which the webserver runs on
     class PubSubWorker
       include Celluloid
       include Celluloid::Logger
       attr_accessor :actor, :connect_blk, :client, :options, :hostname, :port, :path
+      #  receives a list of options that are used to connect to the webserver and an actor to which the callbacks are delegated to
+      #  when receiving messages from a channel
+      #
+      # @param  [Hash]  options the options that can be used to connect to webser and send additional data
+      # @option options [String] :actor The actor that made the connection
+      # @option options [String]:hostname The hostname on which the webserver runs on
+      # @option options [String] :port The port on which the webserver runs on
+      # @option options [String] :path The request path that the webserver accepts
+      #
+      # @param [Proc] connect_blk  Block  that will execute after the connection is opened
+      #
+      # @return [void]
+      #
+      # @api public
       def initialize(options, &connect_blk)
         parse_options(options)
         raise "#{self}: Please provide an actor in the options list!!!" if @actor.blank?
@@ -12,6 +51,17 @@ module CelluloidPubsub
         @client = Celluloid::WebSocket::Client.new("ws://#{@hostname}:#{@port}#{@path}", Actor.current)
       end
+      # check the options list for values and sets default values if not found
+      #
+      # @param  [Hash]  options the options that can be used to connect to webser and send additional data
+      # @option options [String] :actor The actor that made the connection
+      # @option options [String]:hostname The hostname on which the webserver runs on
+      # @option options [String] :port The port on which the webserver runs on
+      # @option options [String] :path The request path that the webserver accepts
+      #
+      # @return [void]
+      #
+      # @api public
       def parse_options(options)
         raise 'Options is not a hash' unless options.is_a?(Hash)
         @options = options.stringify_keys!
@@ -21,27 +71,62 @@ module CelluloidPubsub
         @path = @options.fetch('path', CelluloidPubsub::WebServer::PATH)
       end
+      #  checks if debug is enabled
+      #
+      #
+      # @return [boolean]
+      #
+      # @api public
       def debug_enabled?
         CelluloidPubsub::WebServer.debug_enabled?
       end
+      # subscribes to a channel . need to be used inside the connect block passed to the actor
+      #
+      # @param [string] channel
+      #
+      # @return [void]
+      #
+      # @api public
       def subscribe(channel)
         subscription_data = { 'client_action' => 'subscribe', 'channel' => channel }
         debug("#{self.class} tries to subscribe  #{subscription_data}") if debug_enabled?
         async.chat(subscription_data)
       end
+      # publishes to a channel some data (can be anything)
+      #
+      # @param [string] channel
+      # @param [#to_s] data
+      #
+      # @return [void]
+      #
+      # @api public
       def publish(channel, data)
         publishing_data = { 'client_action' => 'publish', 'channel' => channel, 'data' => data }
         debug(" #{self.class}  publishl to #{channel} message:  #{publishing_data}") if debug_enabled?
         async.chat(publishing_data)
       end
+      #  callback executes after connection is opened and delegates action to actor
+      #
+      # @return [void]
+      #
+      # @api public
       def on_open
         debug("#{self.class} websocket connection opened") if debug_enabled?
         @connect_blk.call Actor.current
       end
+      # callback executes when actor receives a message from a subscribed channel
+      # and parses the message using JSON.parse and dispatches the parsed
+      # message to the original actor that made the connection
+      #
+      # @param [JSON] data
+      #
+      # @return [void]
+      #
+      # @api public
       def on_message(data)
         debug("#{self.class} received  plain #{data}") if debug_enabled?
         message = JSON.parse(data)
@@ -49,6 +134,15 @@ module CelluloidPubsub
         @actor.async.on_message(message)
       end
+      # callback executes when connection closes
+      #
+      # @param [String] code
+      #
+      # @param [String] reason
+      #
+      # @return [void]
+      #
+      # @api public
       def on_close(code, reason)
         @client.terminate
         terminate
@@ -58,6 +152,15 @@ module CelluloidPubsub
     private
+      # method used to send messages to the webserver
+      # checks too see if the message is a hash and if it is it will transform it to JSON and send it to the webser
+      # otherwise will construct a JSON object that will have the key action with the value 'message" and the key message witth the parameter's value
+      #
+      # @param [Hash] message
+      #
+      # @return [void]
+      #
+      # @api private
       def chat(message)
         final_message = nil
         if message.is_a?(Hash)
@@ -72,6 +175,20 @@ module CelluloidPubsub
       end
     end
+    # method used to make a new connection to the webserver
+    # after the connection is opened it will execute the block that is passed as argument
+    #
+    # @param  [Hash]  options the options that can be used to connect to webser and send additional data
+    # @option options [String] :actor The actor that made the connection
+    # @option options [String]:hostname The hostname on which the webserver runs on
+    # @option options [String] :port The port on which the webserver runs on
+    # @option options [String] :path The request path that the webserver accepts
+    #
+    # @param [Proc] connect_blk Block  that will execute after the connection is opened
+    #
+    # @return [CelluloidPubsub::Client::PubSubWorker]
+    #
+    # @api public
     def self.connect(options = {}, &connect_blk)
       CelluloidPubsub::Client::PubSubWorker.new(options, &connect_blk)
     end

data/lib/celluloid_pubsub/reactor.rb CHANGED Viewed

@@ -1,26 +1,62 @@
 require_relative './registry'
 module CelluloidPubsub
+  # The reactor handles new connections. Based on what the client sends it either subscribes to a channel
+  # or will publish to a channel or just dispatch to the server if command is neither subscribe, publish or unsubscribe
+  # @!attribute websocket
+  #   @return [Reel::WebSocket] websocket connection
+  #
+  # @!attribute server
+  #   @return [CelluloidPubsub::Webserver] the server actor to which the reactor is connected to
+  #
+  # @!attribute mutex
+  #   @return [Mutex] mutex used to lock when subscribing to a channel
+  #
+  # @!attribute channels
+  #   @return [Array] array of channels to which the current reactor has subscribed to
   class Reactor
     include Celluloid
     include Celluloid::IO
     include Celluloid::Logger
-    attr_accessor :websocket, :server, :mutex
+    attr_accessor :websocket, :server, :mutex, :channels
+    #  rececives a new socket connection from the server
+    #  and initiates a new mutex that can be used when subsribing to a channel
+    #
+    # @param  [Reel::WebSocket] websocket
+    #
+    # @return [void]
+    #
+    # @api public
     def work(websocket, server)
       @server = server
       @mutex = Mutex.new
+      @channels = []
       @websocket = websocket
       info "Streaming changes for #{websocket.url}" if @server.debug_enabled?
       async.run
     end
+    # reads from the socket the message
+    # and dispatches it to the handle_websocket_message method
+    # @see #handle_websocket_message
+    #
+    # @return [void]
+    #
+    # @api public
     def run
       while message = @websocket.read
         handle_websocket_message(message)
       end
     end
+    # method used to parse a JSON object into a Hash object
+    #
+    # @param [JSON] message
+    #
+    # @return [Hash]
+    #
+    # @api public
     def parse_json_data(message)
       debug "Reactor read message  #{message}" if @server.debug_enabled?
       json_data = nil
@@ -34,11 +70,37 @@ module CelluloidPubsub
       json_data
     end
+    # method that handles the message received from the websocket connection
+    # first will try to parse the message {#parse_json_data}  and then it will dispatch
+    # it to another method that will decide depending the message what action
+    # should the reactor take {#handle_parsed_websocket_message}
+    #
+    # @see #parse_json_data
+    # @see #handle_parsed_websocket_message
+    #
+    # @param [JSON] message
+    #
+    # @return [void]
+    #
+    # @api public
     def handle_websocket_message(message)
       json_data = parse_json_data(message)
       handle_parsed_websocket_message(json_data)
     end
+    # method that checks if the data is a Hash
+    #
+    # if the data is a hash then will stringify the keys and will call the method {#delegate_action}
+    # that will handle the message, otherwise will call the method {#handle_unknown_action}
+    #
+    # @see #delegate_action
+    # @see #handle_unknown_action
+    #
+    # @param [Hash] json_data
+    #
+    # @return [void]
+    #
+    # @api public
     def handle_parsed_websocket_message(json_data)
       if json_data.is_a?(Hash)
         json_data = json_data.stringify_keys
@@ -49,6 +111,27 @@ module CelluloidPubsub
       end
     end
+    # method that checks if the data is a Hash
+    #
+    # if the data is a hash then will stringify the keys and will call the method {#delegate_action}
+    # that will handle the message, otherwise will call the method {#handle_unknown_action}
+    #
+    # @see #delegate_action
+    # @see #handle_unknown_action
+    #
+    # @param [Hash] json_data
+    # @option json_data [String] :client_action The action based on which the reactor will decide what action should make
+    #
+    #   Possible values are:
+    #     unsubscribe_client
+    #     unsubscribe
+    #     subscribe
+    #     publish
+    #
+    #
+    # @return [void]
+    #
+    # @api public
     def delegate_action(json_data)
       case json_data['client_action']
         when 'unsubscribe_all'
@@ -64,44 +147,92 @@ module CelluloidPubsub
       end
     end
+    # the method will delegate the message to the server in an asyncronous way by sending the current actor and the message
+    # @see {CelluloidPubsub::WebServer#handle_dispatched_message}
+    #
+    # @param [Hash] json_data
+    #
+    # @return [void]
+    #
+    # @api public
     def handle_unknown_action(json_data)
       debug "Trying to dispatch   to server  #{json_data}" if @server.debug_enabled?
       @server.async.handle_dispatched_message(Actor.current, json_data)
     end
+    # the method will unsubscribe a client by closing the websocket connection if has unscribed from all channels
+    # and deleting the reactor from the channel list on the server
+    #
+    # @param [String] channel
+    #
+    # @return [void]
+    #
+    # @api public
     def unsubscribe_client(channel)
       return unless channel.present?
-      @websocket.close
-      @server.unsubscribe_client(Actor.current, channel)
+      @channels.delete(channel)
+      @websocket.close if @channels.blank?
+      @server.subscribers[channel].delete_if do |hash|
+        hash[:reactor] == Actor.current
+      end
     end
+    # the method will terminate the current actor
+    #
+    #
+    # @return [void]
+    #
+    # @api public
     def shutdown
       terminate
     end
+    # this method will add the current actor to the list of the subscribers {#add_subscriber_to_channel}
+    # and will write to the socket a message for succesful subscription
+    #
+    # @see #add_subscriber_to_channel
+    #
+    # @param [String] channel
+    # @param [Object] message
+    #
+    # @return [void]
+    #
+    # @api public
     def start_subscriber(channel, message)
       return unless channel.present?
-      @mutex.lock
       begin
         add_subscriber_to_channel(channel, message)
         debug "Subscribed to #{channel} with #{message}" if @server.debug_enabled?
         @websocket << message.merge('client_action' => 'successful_subscription', 'channel' => channel).to_json
       rescue => e
         raise [e, e.respond_to?(:backtrace) ? e.backtrace : '', channel, message].inspect
-      ensure
-        @mutex.unlock
       end
     end
+    # adds the curent actor the list of the subscribers for a particular channel
+    # and registers the new channel
+    #
+    # @param [String] channel
+    # @param [Object] message
+    #
+    # @return [void]
+    #
+    # @api public
     def add_subscriber_to_channel(channel, message)
+      @channels << channel
       CelluloidPubsub::Registry.channels << channel unless CelluloidPubsub::Registry.channels.include?(channel)
       @server.subscribers[channel] ||= []
       @server.subscribers[channel] << { reactor: Actor.current, message: message }
     end
+    # unsubscribes all actors from all channels and terminates the curent actor
+    #
+    # @return [void]
+    #
+    # @api public
     def unsubscribe_all
       CelluloidPubsub::Registry.channels.map do |channel|
-        @subscribers[channel].each do |hash|
+        @server.subscribers[channel].each do |hash|
           hash[:reactor].websocket.close
         end
         @server.subscribers[channel] = []

data/lib/celluloid_pubsub/registry.rb CHANGED Viewed

@@ -1,7 +1,10 @@
 module CelluloidPubsub
+  # class used to register new channels and save them in memory
   class Registry
     include ActiveSupport::Configurable
     class << self
+      # @!attribute channels
+      #   @return [Array] array of channels to which actors have subscribed to
       attr_accessor :channels
     end
     @channels = []

data/lib/celluloid_pubsub/version.rb CHANGED Viewed

@@ -1,14 +1,27 @@
-module CelluloidPubsub # Returns the version of the currently loaded Rails as a <tt>Gem::Version</tt>
+# Returns the version of the gem  as a <tt>Gem::Version</tt>
+module CelluloidPubsub
+  #  it prints the gem version as a string
+  #
+  # @return [String]
+  #
+  # @api public
   def self.gem_version
     Gem::Version.new VERSION::STRING
   end
+  # module used to generate the version string
+  # provides a easy way of getting the major, minor and tiny
   module VERSION
+    # major release version
     MAJOR = 0
+    # minor release version
     MINOR = 0
-    TINY = 5
+    # tiny release version
+    TINY = 6
+    # prelease version ( set this only if it is a prelease)
     PRE = nil
+    # generates the version string
     STRING = [MAJOR, MINOR, TINY, PRE].compact.join('.')
   end
 end