lightstreamer 0.10 → 0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3c3233354e9c3f4b4200e693ad85cca5c0608a5a
-  data.tar.gz: 84d6e92653bf54b3bd74de5ca789714c7f47e011
+  metadata.gz: 712d0f7cae7367c26efde5f75b0481bb5a3d90a3
+  data.tar.gz: 77a6882d44273754bb5c85a7739bb614860b7b82
 SHA512:
-  metadata.gz: 012b09b619a2c3c21913096639fcbd3962f6ad34618e5629a85434062f289308711aa546928e3b12d98d847f3d4e175988db70c02086cbaf2f3f6f9d741d634d
-  data.tar.gz: 3dce2858bcbc74bf1b35304f23fb600e68e846c4cfbc0916358a3f8308d5367e3cd69f5c7f7a1e92ed01d88869973bfba294f3eaae7e212742996ceaab78028f
+  metadata.gz: e6eec1efbbd9e79c891798f8833a820396caa40b0bbb275eee686b95cc93689651e7703495949953d66ea80e95278e0b3f2203e2ad032a1861981426d082473b
+  data.tar.gz: 6164a9f932129439f3870081d55962ebae8f35f44169269f366bd64d2222d66d6bbd14e25fd92b9d59bfe7d3bff8ec52f8f8a5af8ee44a4cd6c144ccd9635377

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Lightstreamer Changelog
 
+### 0.11 — August 20, 2016
+
+- Added `Lightstreamer::Session#stop_subscriptions` for stopping multiple subscriptions in one request
+- Renamed `Lightstreamer::Session#bulk_subscription_start` to `Lightstreamer::Session#start_subscriptions`
+- Added support for combining all subscription actions via `Lightstreamer::Session#perform_subscription_actions`
+  which allows subscription start, unsilence and stop requests to be easily bundled together
+- Fixed `Subscription#id` only being callable on the main thread
+
 ### 0.10 — August 5, 2016
 
 - Added support for shared subscription start options to `Lightstreamer::Session#bulk_subscription_start`

data/README.md

@@ -20,7 +20,7 @@ Includes support for:
 - Silent subscriptions
 - Item snapshots and end-of-snapshot notifications
 - Unfiltered subscriptions and overflow notifications
-- Bulk subscription creation
+- Performing multiple subscription actions in a single request
 - Synchronous and asynchronous message sending
 - Detailed error reporting and error handling callbacks
 
@@ -64,7 +64,7 @@ session.connect
 # Create a new subscription that subscribes to thirty items and to four fields on each item
 subscription = session.build_subscription data_adapter: 'QUOTE_ADAPTER', mode: :merge,
                                           items: (1..30).map { |i| "item#{i}" },
-                                          fields: [:ask, :bid, :stock_name, :time],
+                                          fields: [:ask, :bid, :stock_name, :time]
 
 # Create a thread-safe queue
 queue = Queue.new

data/lib/lightstreamer/post_request.rb

@@ -1,5 +1,5 @@
 module Lightstreamer
-  # This module contains helper methods for sending single and bulk POST requests to a Lightstreamer server and
+  # This module contains helper methods for sending single and multiple POST requests to a Lightstreamer server and
   # handling the possible error responses.
   #
   # @private
@@ -12,7 +12,7 @@ module Lightstreamer
     # @param [String] url The URL to send the POST request to.
     # @param [Hash] query The POST request's query params.
     def execute(url, query)
-      errors = bulk_execute url, [request_body(query)]
+      errors = execute_multiple url, [request_body(query)]
       raise errors.first if errors.first
     end
 
@@ -26,7 +26,7 @@ module Lightstreamer
     #
     # @return [Array<LightstreamerError, nil>] The execution result of each of the passed bodies. If an entry is `nil`
     #         then no error occurred when executing that body.
-    def bulk_execute(url, bodies)
+    def execute_multiple(url, bodies)
       response = Excon.post url, body: bodies.join("\r\n"), expects: 200, connect_timeout: 15
 
       response_lines = response.body.split("\n").map(&:strip)

data/lib/lightstreamer/session.rb

@@ -2,7 +2,7 @@ module Lightstreamer
   # This class is responsible for managing a Lightstreamer session, and along with the {Subscription} class forms the
   # primary API for working with Lightstreamer. Start by calling {#initialize} with the desired server URL and other
   # options, then call {#connect} to initiate the session. Once connected create subscriptions using
-  # {#build_subscription} and then start streaming data by calling {Subscription#start} or {#bulk_subscription_start}.
+  # {#build_subscription} and then start streaming data by calling {Subscription#start} or {#start_subscriptions}.
   # See the {Subscription} class for details on how to consume the streaming data as it arrives.
   class Session
     # The URL of the Lightstreamer server to connect to. Set by {#initialize}.
@@ -94,14 +94,14 @@ module Lightstreamer
 
     # Disconnects this Lightstreamer session and terminates the session on the server. All worker threads are exited.
     def disconnect
-      control_request :destroy if @stream_connection
+      control_request LS_op: :destroy if @stream_connection
 
       @processing_thread.join 5 if @processing_thread
     ensure
       @stream_connection.disconnect if @stream_connection
       @processing_thread.exit if @processing_thread
 
-      @subscriptions.each { |subscription| subscription.instance_variable_set :@active, false }
+      @subscriptions.each { |subscription| subscription.after_control_request :stop }
 
       @processing_thread = @stream_connection = nil
     end
@@ -113,7 +113,7 @@ module Lightstreamer
     # it forces the stream connection to rebind using the new setting. If an error occurs then a {LightstreamerError}
     # subclass will be raised.
     def force_rebind
-      control_request :force_rebind if @stream_connection
+      control_request LS_op: :force_rebind if @stream_connection
     end
 
     # Builds a new subscription for this session with the specified options. Note that ths does not activate the
@@ -152,29 +152,62 @@ module Lightstreamer
       @mutex.synchronize { @subscriptions.delete subscription }
     end
 
-    # This method performs a bulk {Subscription#start} on all the passed subscriptions. Calling {Subscription#start} on
-    # each subscription individually would also work but requires a separate POST request to be sent for every
-    # subscription, whereas this request starts all of the passed subscriptions in a single POST request which is
-    # significantly faster for a large number of subscriptions. The return value is an array with one entry per
-    # subscription and indicates the error state returned by the server for that subscription's start request, or `nil`
-    # if no error occurred.
+    # This method performs {Subscription#start} on all the passed subscriptions. Calling {Subscription#start} on each
+    # subscription individually would also work but requires a separate POST request to be sent for every subscription,
+    # whereas this method starts all of the passed subscriptions in a single POST request which is significantly faster
+    # for a large number of subscriptions. The return value is an array with one entry per subscription and indicates
+    # the error state returned by the server for that subscription's start request, or `nil` if no error occurred.
     #
     # @param [Array<Subscription>] subscriptions The subscriptions to start.
-    # @param [Hash] options The options to start all subscriptions with. See {Subscription#start} for details on the
+    # @param [Hash] options The options to start the subscriptions with. See {Subscription#start} for details on the
     #        supported options.
     #
     # @return [Array<LightstreamerError, nil>]
-    def bulk_subscription_start(subscriptions, options = {})
-      request_bodies = subscriptions.map do |subscription|
-        args = subscription.start_control_request_args options
-        PostRequest.request_body({ LS_session: session_id, LS_op: args.first }.merge(args[1]))
+    def start_subscriptions(subscriptions, options = {})
+      details = subscriptions.map { |subscription| { subscription: subscription, action: :start, options: options } }
+
+      perform_subscription_actions details
+    end
+
+    # This method performs {Subscription#stop} on all the passed subscriptions. Calling {Subscription#stop} on each
+    # subscription individually would also work but requires a separate POST request to be sent for every subscription,
+    # whereas this method stops all of the passed subscriptions in a single POST request which is significantly faster
+    # for a large number of subscriptions. The return value is an array with one entry per subscription and indicates
+    # the error state returned by the server for that subscription's stop request, or `nil` if no error occurred.
+    #
+    # @param [Array<Subscription>] subscriptions The subscriptions to stop.
+    #
+    # @return [Array<LightstreamerError, nil>]
+    def stop_subscriptions(subscriptions)
+      details = subscriptions.map { |subscription| { subscription: subscription, action: :stop } }
+
+      perform_subscription_actions details
+    end
+
+    # This method takes an array of subscriptions and actions to perform on those subscriptions. The supported actions
+    # are `:start`, `:unsilence` and `:stop`. Calling {Subscription#start}, {Subscription#unsilence} or
+    # {Subscription#stop} on each subscription individually would also work but requires a separate POST request to be
+    # sent for each action, whereas this method performs all of the specified actions in a single POST request which is
+    # significantly faster for a large number of actions. The return value is an array with one entry per action and
+    # indicates the error state returned by the server for that action, or `nil` if no error occurred. It will have the
+    # same number of entries as the passed `details` array.
+    #
+    # @param [Array<Hash>] actions This array describes the subscription actions to perform. Each entry must be a hash
+    #        containing a `:subscription` key specifying the {Subscription}, and an `:action` key specifying the action
+    #        to perform on the subscription (either `:start`, `:unsilence` or `:stop`). If `:action` is `:start` then an
+    #        `:options` key can be specified, and the supported options are the same as for {Subscription#start}.
+    #
+    # @return [Array<LightstreamerError, nil>]
+    def perform_subscription_actions(actions)
+      request_bodies = actions.map do |hash|
+        PostRequest.request_body hash.fetch(:subscription).control_request_options(hash.fetch(:action), hash[:options])
       end
 
-      errors = PostRequest.bulk_execute control_request_url, request_bodies
+      errors = PostRequest.execute_multiple control_request_url, request_bodies
 
-      # Set @active to true on all subscriptions that did not have an error
+      # Update the state of subscriptions that did not have an error
       errors.each_with_index do |error, index|
-        subscriptions[index].instance_variable_set :@active, true if error.nil?
+        actions[index][:subscription].after_control_request actions[index][:action] unless error
       end
     end
 
@@ -183,7 +216,7 @@ module Lightstreamer
     #
     # @param [Float] bandwidth The new requested maximum bandwidth, expressed in kbps.
     def requested_maximum_bandwidth=(bandwidth)
-      control_request :constrain, LS_requested_max_bandwidth: bandwidth if connected?
+      control_request LS_op: :constrain, LS_requested_max_bandwidth: bandwidth if connected?
       @requested_maximum_bandwidth = bandwidth.to_f
     end
 
@@ -228,16 +261,15 @@ module Lightstreamer
     # Sends a request to this session's control connection. If an error occurs then a {LightstreamerError} subclass will
     # be raised.
     #
-    # @param [Symbol] operation The control operation to perform.
-    # @param [Hash] options The options to send with the control request.
-    def control_request(operation, options = {})
-      PostRequest.execute control_request_url, options.merge(LS_session: session_id, LS_op: operation)
+    # @param [Hash] query The details of the control request query.
+    def control_request(query = {})
+      PostRequest.execute control_request_url, query.merge(LS_session: session_id)
     end
 
     # Adds the passed block to the list of callbacks that will be run when this session encounters an error on its
-    # processing thread caused by an error with the steam connection. The block will be called on a worker thread and so
-    # the code that is run by the block must be thread-safe. The argument passed to the block is `|error|`, which will
-    # be a {LightstreamerError} subclass detailing the error that occurred.
+    # processing thread caused by an error with the stream connection. The block will be called on a worker thread and
+    # so the code that is run by the block must be thread-safe. The argument passed to the block is `|error|`, which
+    # will be a {LightstreamerError} subclass detailing the error that occurred.
     #
     # @param [Proc] callback The callback that is to be run.
     def on_error(&callback)

data/lib/lightstreamer/subscription.rb

@@ -76,7 +76,7 @@ module Lightstreamer
     #
     # @private
     def id
-      @id ||= ID_GENERATOR.next
+      @id ||= self.class.next_id
     end
 
     # Starts streaming data for this Lightstreamer subscription. If an error occurs then a {LightstreamerError} subclass
@@ -97,38 +97,23 @@ module Lightstreamer
     def start(options = {})
       return if @active
 
-      session.control_request(*start_control_request_args(options))
-      @active = true
-    end
-
-    # Returns the arguments to pass to to {Session#control_request} in order to start this subscription with the given
-    # options.
-    #
-    # @param [Hash] options The options to start the subscription with.
-    #
-    # @private
-    def start_control_request_args(options = {})
-      operation = options[:silent] ? :add_silent : :add
-
-      options = { LS_table: id, LS_mode: mode.to_s.upcase, LS_id: items, LS_schema: fields, LS_selector: selector,
-                  LS_data_adapter: data_adapter, LS_requested_max_frequency: maximum_update_frequency,
-                  LS_snapshot: options.fetch(:snapshot, false) }
-
-      [operation, options]
+      session.control_request control_request_options(:start, options)
+      after_control_request :start
     end
 
     # Unsilences this subscription if it was initially started in silent mode by passing `silent: true` to {#start}. If
     # this subscription was not started in silent mode then this method has no effect. If an error occurs then a
     # {LightstreamerError} subclass will be raised.
     def unsilence
-      session.control_request :start, LS_table: id
+      session.control_request control_request_options(:unsilence)
+      after_control_request :unsilence
     end
 
     # Stops streaming data for this Lightstreamer subscription. If an error occurs then a {LightstreamerError} subclass
     # will be raised.
     def stop
-      session.control_request :delete, LS_table: id if @active
-      @active = false
+      session.control_request control_request_options(:stop) if @active
+      after_control_request :stop
     end
 
     # Sets this subscription's maximum update frequency. This can be done while a subscription is streaming data in
@@ -140,7 +125,7 @@ module Lightstreamer
     #        details.
     def maximum_update_frequency=(new_frequency)
       new_frequency = sanitize_frequency new_frequency
-      session.control_request :reconf, LS_table: id, LS_requested_max_frequency: new_frequency if @active
+      session.control_request LS_op: :reconf, LS_table: id, LS_requested_max_frequency: new_frequency if @active
       @maximum_update_frequency = new_frequency
     end
 
@@ -181,7 +166,8 @@ module Lightstreamer
 
     # Adds the passed block to the list of callbacks that will be run when new data for this subscription arrives. The
     # block will be called on a worker thread and so the code that is run by the block must be thread-safe. The
-    # arguments passed to the block are `|subscription, item_name, item_data, new_data|`. If {#mode} is `:distinct`
+    # arguments passed to the block are `|subscription, item_name, item_data, new_data|`. The `item_data` argument will
+    # be an array if {#mode} is `:command`, for all other modes it will be a hash. Note that if {#mode} is `:distinct`
     # or `:raw` then `item_data` and `new_data` will be the same.
     #
     # @param [Proc] callback The callback that is to be run when new data arrives.
@@ -230,9 +216,39 @@ module Lightstreamer
       return true if process_end_of_snapshot_message EndOfSnapshotMessage.parse(line, id, items)
     end
 
+    # Returns the control request arguments to use to perform the specified action on this subscription.
+    #
+    # @private
+    def control_request_options(action, options = nil)
+      case action.to_sym
+      when :start
+        start_control_request_options options
+      when :unsilence
+        { LS_session: session.session_id, LS_op: :start, LS_table: id }
+      when :stop
+        { LS_session: session.session_id, LS_op: :delete, LS_table: id }
+      end
+    end
+
+    # Performs any required updates to this subscription's state after a control request succeeds.
+    #
+    # @private
+    def after_control_request(action)
+      @active = true if action == :start
+      @active = false if action == :stop
+    end
+
     private
 
-    ID_GENERATOR = (1..Float::INFINITY).each
+    class << self
+      # Returns the next unique numeric subscription ID.
+      #
+      # @private
+      def next_id
+        @next_id ||= 0
+        @next_id += 1
+      end
+    end
 
     def sanitize_frequency(frequency)
       frequency.to_s == 'unfiltered' ? :unfiltered : frequency.to_f
@@ -264,5 +280,15 @@ module Lightstreamer
 
       true
     end
+
+    def start_control_request_options(options)
+      options ||= {}
+
+      operation = options[:silent] ? :add_silent : :add
+
+      { LS_session: session.session_id, LS_op: operation, LS_table: id, LS_mode: mode.to_s.upcase, LS_id: items,
+        LS_schema: fields, LS_selector: selector, LS_snapshot: options.fetch(:snapshot, false),
+        LS_requested_max_frequency: maximum_update_frequency, LS_data_adapter: data_adapter }
+    end
   end
 end

data/lib/lightstreamer/version.rb

@@ -1,4 +1,4 @@
 module Lightstreamer
   # The version of this gem.
-  VERSION = '0.10'.freeze
+  VERSION = '0.11'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lightstreamer
 version: !ruby/object:Gem::Version
-  version: '0.10'
+  version: '0.11'
 platform: ruby
 authors:
 - Richard Viney
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-05 00:00:00.000000000 Z
+date: 2016-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: excon