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

celluloid_pubsub 0.0.5 → 0.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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