lightstreamer 0.8 → 0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2fbedc6ddd408cf66740c82acb37a83fb1954b13
-  data.tar.gz: e259733aa9ab2bd100a1cee9a58ea120de44614c
+  metadata.gz: 75687f5d599512c6623967cd0e005f67c616e3f2
+  data.tar.gz: b8eadafa92da0812fa59803e44b371d4537aeedb
 SHA512:
-  metadata.gz: a47999d9791bf4eb11671fadf6ed949ff3bed475d7856ce2ae1a9f99dceba78608b52ac630ba58a5425a1154c6807ab9aa7e2937119f3e8136051a81be82be84
-  data.tar.gz: 689b06550c0ff39e08ec1042a80e6aa99ab47ddeaa92c0acd6f064eef6bcb6e9be202b90a19627c878157e3d41c795e1b131245ed0538364faf2e15d9dfff5cf
+  metadata.gz: e8a46f18e3bd81a5635c660caea2911e1f04f5503476293e37bebd49bf0a45a3f28a980bc546b8d316a419aad5c0b550d5134e1dab62ff7a513cf81fe20299e7
+  data.tar.gz: 273ec4437edcde9a079a0f7c51e83701751caae948a776c623d89443ed7f9f25eb556c9255fda11d44e1c4b76785fae93b19d19b56d731938dd0e3eb34ad129e

data/CHANGELOG.md

@@ -1,10 +1,16 @@
 # Lightstreamer Changelog
 
+### 0.9 — August 4, 2016
+
+- Replaced the `Lightstreamer::Session#error` attribute with a new `Lightstreamer::Session#on_error` callback to enable
+  more efficient error handling and notification
+- Fixed issues with `Lightstreamer::Session#bulk_subscription_start`
+
 ### 0.8 — August 2, 2016
 
 - Added support for Lightstreamer's `COMMAND` and `RAW` subscription modes
 - Added support for Lightstreamer's polling mode and switching an active session between streaming and polling
-- `Lightstreamer::Subscription#item_data` now return `nil` if the requested item has never had any data set
+- `Lightstreamer::Subscription#item_data` now returns `nil` if the requested item has never had any data set
 - Renamed `Lightstreamer::Subscription#adapter` to `Lightstreamer::Subscription#data_adapter` and the `--adapter`
   command-line option to `--data-adapter`
 - The `--mode` command-line option is now required because the default value of `merge` has been removed

data/README.md

@@ -15,11 +15,11 @@ provided command-line client. Written against the
 Includes support for:
 
 - Streaming and polling connections
-- The four Lightstreamer subscription modes: `command`, `distinct`, `merge` and `raw`
-- Automatic management of table content when in `command` mode
+- All subscription modes: command, distinct, merge and raw
+- Automatic management of table content when in command mode
 - Silent subscriptions
-- Item snapshots
-- Unfiltered subscriptions and asynchronous overflow handling
+- Item snapshots and end-of-snapshot notifications
+- Unfiltered subscriptions and overflow notifications
 - Bulk subscription creation
 - Synchronous and asynchronous message sending
 - Detailed error reporting and error handling callbacks
@@ -43,23 +43,28 @@ The two primary classes that make up the public API are:
 - [`Lightstreamer::Session`](http://www.rubydoc.info/github/rviney/lightstreamer/Lightstreamer/Session)
 - [`Lightstreamer::Subscription`](http://www.rubydoc.info/github/rviney/lightstreamer/Lightstreamer/Subscription)
 
-The following code snippet demonstrates how to create a Lightstreamer session, build a subscription, then print
-streaming output as it arrives.
+The following code demonstrates how to create a Lightstreamer session, build a subscription, then use a thread-safe
+queue to print streaming output as it arrives.
 
 ```ruby
 require 'lightstreamer'
 
-# Create a new session that connects to the Lightstreamer demo server, which needs no authentication
+# Create a new session that connects to the Lightstreamer demo server
 session = Lightstreamer::Session.new server_url: 'http://push.lightstreamer.com',
                                      adapter_set: 'DEMO', username: '', password: ''
 
+# Add a simple error handler that just raises the error and so terminates the application
+session.on_error do |error|
+  raise error
+end
+
 # Connect the session
 session.connect
 
 # Create a new subscription that subscribes to thirty items and to four fields on each item
-subscription = session.build_subscription items: (1..30).map { |i| "item#{i}" },
+subscription = session.build_subscription data_adapter: 'QUOTE_ADAPTER', mode: :merge,
+                                          items: (1..30).map { |i| "item#{i}" },
                                           fields: [:ask, :bid, :stock_name, :time],
-                                          mode: :merge, data_adapter: 'QUOTE_ADAPTER'
 
 # Create a thread-safe queue
 queue = Queue.new
@@ -73,7 +78,7 @@ end
 # Start streaming data for the subscription and request an initial snapshot
 subscription.start snapshot: true
 
-# Loop printing out new data as soon as it becomes available on the queue
+# Print new data as soon as it becomes available on the queue
 loop do
   data = queue.pop
   puts "#{data[:time]} - #{data[:stock_name]} - bid: #{data[:bid]}, ask: #{data[:ask]}"
@@ -82,10 +87,10 @@ end
 
 ## Usage — Command-Line Client
 
-This gem provides a simple command-line client that can connect to a Lightstreamer server, activate a
-subscription, then print streaming output from the server as it becomes available.
+This gem provides a simple command-line client that can connect to a Lightstreamer server and display
+live streaming output for a set of items and fields.
 
-To print streaming data from the demo server run the following command:
+To stream data from Lightstreamer's demo server run the following command:
 
 ```
 lightstreamer --server-url http://push.lightstreamer.com --adapter-set DEMO \
@@ -101,7 +106,7 @@ lightstreamer help stream
 
 ## Documentation
 
-API documentation is available [here](http://www.rubydoc.info/github/rviney/lightstreamer).
+API documentation is available [here](http://www.rubydoc.info/github/rviney/lightstreamer/master).
 
 ## Contributors
 

data/lib/lightstreamer.rb

@@ -1,3 +1,5 @@
+require 'thread'
+
 require 'excon'
 require 'thor'
 require 'uri'

data/lib/lightstreamer/cli/commands/stream_command.rb

@@ -20,26 +20,36 @@ module Lightstreamer
       option :maximum_update_frequency, desc: 'The maximum number of updates per second for each item'
 
       def stream
-        @queue = Queue.new
+        prepare_stream
 
-        create_session
-        create_subscription
+        puts "Session ID: #{@session.session_id}"
 
         loop do
-          puts @queue.pop unless @queue.empty?
+          data = @queue.pop
 
-          raise @session.error if @session.error
+          if data.is_a? Lightstreamer::LightstreamerError
+            puts "Error: #{data}"
+            break
+          end
+
+          puts data
         end
       end
 
       private
 
+      def prepare_stream
+        @queue = Queue.new
+
+        create_session
+        create_subscription
+      end
+
       def create_session
         @session = Lightstreamer::Session.new session_options
         @session.connect
         @session.on_message_result(&method(:on_message_result))
-
-        puts "Session ID: #{@session.session_id}"
+        @session.on_error(&method(:on_error))
       end
 
       def create_subscription
@@ -79,6 +89,10 @@ module Lightstreamer
       def on_end_of_snapshot(_subscription, item_name)
         @queue.push "End of snapshot for item #{item_name}"
       end
+
+      def on_error(error)
+        @queue.push error
+      end
     end
   end
 end

data/lib/lightstreamer/session.rb

@@ -25,13 +25,6 @@ module Lightstreamer
     # @return [String, nil]
     attr_reader :adapter_set
 
-    # If an error occurs on the stream connection that causes the session to terminate then details of the error will be
-    # stored in this attribute. If the session is terminated as a result of calling {#disconnect} then the error will be
-    # {Errors::SessionEndError}.
-    #
-    # @return [LightstreamerError, nil]
-    attr_reader :error
-
     # The server-side bandwidth constraint on data usage, expressed in kbps. If this is zero then no limit is applied.
     #
     # @return [Float]
@@ -58,8 +51,7 @@ module Lightstreamer
     # @option options [Boolean] :polling_enabled Whether polling mode is enabled. See {#polling_enabled} for details.
     #                 Defaults to `false`.
     def initialize(options = {})
-      @subscriptions = []
-      @subscriptions_mutex = Mutex.new
+      @mutex = Mutex.new
 
       @server_url = options.fetch :server_url
       @username = options[:username]
@@ -68,7 +60,8 @@ module Lightstreamer
       @requested_maximum_bandwidth = options[:requested_maximum_bandwidth].to_f
       @polling_enabled = options[:polling_enabled]
 
-      @on_message_result_callbacks = []
+      @subscriptions = []
+      @callbacks = { on_message_result: [], on_error: [] }
     end
 
     # Connects a new Lightstreamer session using the details passed to {#initialize}. If an error occurs then
@@ -76,8 +69,6 @@ module Lightstreamer
     def connect
       return if @stream_connection
 
-      @error = nil
-
       @stream_connection = StreamConnection.new self
       @stream_connection.connect
 
@@ -110,9 +101,7 @@ module Lightstreamer
       @stream_connection.disconnect if @stream_connection
       @processing_thread.exit if @processing_thread
 
-      @subscriptions.each do |subscription|
-        subscription.instance_variable_set :@active, false
-      end
+      @subscriptions.each { |subscription| subscription.instance_variable_set :@active, false }
 
       @processing_thread = @stream_connection = nil
     end
@@ -124,9 +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
-      return unless @stream_connection
-
-      control_request :force_rebind
+      control_request :force_rebind if @stream_connection
     end
 
     # Builds a new subscription for this session with the specified options. Note that ths does not activate the
@@ -149,7 +136,7 @@ module Lightstreamer
     def build_subscription(options)
       subscription = Subscription.new self, options
 
-      @subscriptions_mutex.synchronize { @subscriptions << subscription }
+      @mutex.synchronize { @subscriptions << subscription }
 
       subscription
     end
@@ -162,7 +149,7 @@ module Lightstreamer
     def remove_subscription(subscription)
       subscription.stop
 
-      @subscriptions_mutex.synchronize { @subscriptions.delete subscription }
+      @mutex.synchronize { @subscriptions.delete subscription }
     end
 
     # This method performs a bulk {Subscription#start} on all the passed subscriptions. Calling {Subscription#start} on
@@ -177,10 +164,11 @@ module Lightstreamer
     # @return [Array<LightstreamerError, nil>]
     def bulk_subscription_start(*subscriptions)
       request_bodies = subscriptions.map do |subscription|
-        PostRequest.request_body session_id, *subscription.start_control_request_args
+        args = subscription.start_control_request_args
+        PostRequest.request_body({ LS_session: session_id, LS_op: args.first }.merge(args[1]))
       end
 
-      errors = PostRequest.bulk_execute @stream_connection.control_address, request_bodies
+      errors = PostRequest.bulk_execute control_request_url, request_bodies
 
       # Set @active to true on all subscriptions that did not have an error
       errors.each_with_index do |error, index|
@@ -232,7 +220,7 @@ module Lightstreamer
     #
     # @param [Proc] callback The callback that is to be run.
     def on_message_result(&callback)
-      @on_message_result_callbacks << callback
+      @mutex.synchronize { @callbacks[:on_message_result] << callback }
     end
 
     # Sends a request to this session's control connection. If an error occurs then a {LightstreamerError} subclass will
@@ -241,34 +229,49 @@ module Lightstreamer
     # @param [Symbol] operation The control operation to perform.
     # @param [Hash] options The options to send with the control request.
     def control_request(operation, options = {})
-      url = URI.join(@stream_connection.control_address, '/lightstreamer/control.txt').to_s
+      PostRequest.execute control_request_url, options.merge(LS_session: session_id, LS_op: operation)
+    end
 
-      PostRequest.execute url, options.merge(LS_session: session_id, LS_op: operation)
+    # 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.
+    #
+    # @param [Proc] callback The callback that is to be run.
+    def on_error(&callback)
+      @mutex.synchronize { @callbacks[:on_error] << callback }
     end
 
     private
 
+    def control_request_url
+      URI.join(@stream_connection.control_address, '/lightstreamer/control.txt').to_s
+    end
+
     # Starts the processing thread that reads and processes incoming data from the stream connection.
     def create_processing_thread
       @processing_thread = Thread.new do
         Thread.current.abort_on_exception = true
 
-        loop do
-          line = @stream_connection.read_line
-          break if line.nil?
-
-          process_stream_line line
-        end
+        loop { break unless processing_thread_tick @stream_connection.read_line }
 
-        # The stream connection has terminated so the session is assumed to be over
-        @error = @stream_connection.error
         @processing_thread = @stream_connection = nil
       end
     end
 
+    def processing_thread_tick(line)
+      if line
+        process_stream_line line
+        true
+      else
+        @mutex.synchronize { @callbacks[:on_error].each { |callback| callback.call @stream_connection.error } }
+        false
+      end
+    end
+
     # Processes a single line of incoming stream data. This method is always run on the processing thread.
     def process_stream_line(line)
-      return if @subscriptions.any? { |subscription| subscription.process_stream_data line }
+      return if @mutex.synchronize { @subscriptions.any? { |subscription| subscription.process_stream_data line } }
       return if process_send_message_outcome line
 
       warn "Lightstreamer: unprocessed stream data '#{line}'"
@@ -279,8 +282,10 @@ module Lightstreamer
       outcome = SendMessageOutcomeMessage.parse line
       return unless outcome
 
-      @on_message_result_callbacks.each do |callback|
-        callback.call outcome.sequence, outcome.numbers, outcome.error
+      @mutex.synchronize do
+        @callbacks[:on_message_result].each do |callback|
+          callback.call outcome.sequence, outcome.numbers, outcome.error
+        end
       end
 
       true

data/lib/lightstreamer/stream_connection.rb

@@ -172,7 +172,7 @@ module Lightstreamer
     def process_body_line(line)
       if line =~ /^LOOP( \d+|)$/
         @loop = true
-      elsif line =~ /^END( \d+|)/
+      elsif line =~ /^END( \d+|)$/
         @error = Errors::SessionEndError.new line[4..-1]
       elsif !line.empty?
         @queue.push line

data/lib/lightstreamer/subscription.rb

@@ -56,8 +56,9 @@ module Lightstreamer
     #
     # @private
     def initialize(session, options)
-      @session = session
+      @mutex = Mutex.new
 
+      @session = session
       @items = options.fetch(:items)
       @fields = options.fetch(:fields)
       @mode = options.fetch(:mode).to_sym
@@ -65,8 +66,6 @@ module Lightstreamer
       @selector = options[:selector]
       @maximum_update_frequency = sanitize_frequency options[:maximum_update_frequency]
 
-      @data_mutex = Mutex.new
-
       clear_data
       clear_callbacks
     end
@@ -148,7 +147,7 @@ module Lightstreamer
     # Clears all current data stored for this subscription. New data will continue to be processed as it becomes
     # available.
     def clear_data
-      @data_mutex.synchronize { @data = (0...items.size).map { SubscriptionItemData.new } }
+      @mutex.synchronize { @data = (0...items.size).map { SubscriptionItemData.new } }
     end
 
     # Returns a copy of the current data of one of this subscription's items. If {#mode} is `:merge` then the returned
@@ -163,7 +162,7 @@ module Lightstreamer
       index = @items.index item_name
       raise ArgumentError, 'Unknown item' unless index
 
-      @data_mutex.synchronize { @data[index].data && @data[index].data.dup }
+      @mutex.synchronize { @data[index].data && @data[index].data.dup }
     end
 
     # Sets the current data for the item with the specified name. This is only allowed when {mode} is `:command` or
@@ -177,7 +176,7 @@ module Lightstreamer
       index = @items.index item_name
       raise ArgumentError, 'Unknown item' unless index
 
-      @data_mutex.synchronize { @data[index].set_data item_data, mode }
+      @mutex.synchronize { @data[index].set_data item_data, mode }
     end
 
     # Adds the passed block to the list of callbacks that will be run when new data for this subscription arrives. The
@@ -187,7 +186,7 @@ module Lightstreamer
     #
     # @param [Proc] callback The callback that is to be run when new data arrives.
     def on_data(&callback)
-      @data_mutex.synchronize { @callbacks[:on_data] << callback }
+      @mutex.synchronize { @callbacks[:on_data] << callback }
     end
 
     # Adds the passed block to the list of callbacks that will be run when the server reports an overflow for this
@@ -198,7 +197,7 @@ module Lightstreamer
     #
     # @param [Proc] callback The callback that is to be run when an overflow is reported for this subscription.
     def on_overflow(&callback)
-      @data_mutex.synchronize { @callbacks[:on_overflow] << callback }
+      @mutex.synchronize { @callbacks[:on_overflow] << callback }
     end
 
     # Adds the passed block to the list of callbacks that will be run when the server reports an end-of-snapshot
@@ -209,12 +208,12 @@ module Lightstreamer
     #
     # @param [Proc] callback The callback that is to be run when an overflow is reported for this subscription.
     def on_end_of_snapshot(&callback)
-      @data_mutex.synchronize { @callbacks[:on_end_of_snapshot] << callback }
+      @mutex.synchronize { @callbacks[:on_end_of_snapshot] << callback }
     end
 
     # Removes all {#on_data}, {#on_overflow} and {#on_end_of_snapshot} callbacks present on this subscription.
     def clear_callbacks
-      @data_mutex.synchronize { @callbacks = { on_data: [], on_overflow: [], on_end_of_snapshot: [] } }
+      @mutex.synchronize { @callbacks = { on_data: [], on_overflow: [], on_end_of_snapshot: [] } }
     end
 
     # Processes a line of stream data if it is relevant to this subscription. This method is thread-safe and is intended
@@ -242,7 +241,7 @@ module Lightstreamer
     def process_update_message(message)
       return unless message
 
-      @data_mutex.synchronize do
+      @mutex.synchronize do
         @data[message.item_index].send "process_new_#{mode}_data", message.data.dup
         run_callbacks :on_data, @items[message.item_index], @data[message.item_index].data, message.data
       end
@@ -251,13 +250,13 @@ module Lightstreamer
     def process_overflow_message(message)
       return unless message
 
-      @data_mutex.synchronize { run_callbacks :on_overflow, @items[message.item_index], message.overflow_size }
+      @mutex.synchronize { run_callbacks :on_overflow, @items[message.item_index], message.overflow_size }
     end
 
     def process_end_of_snapshot_message(message)
       return unless message
 
-      @data_mutex.synchronize { run_callbacks :on_end_of_snapshot, @items[message.item_index] }
+      @mutex.synchronize { run_callbacks :on_end_of_snapshot, @items[message.item_index] }
     end
 
     def run_callbacks(callback_type, *args)

data/lib/lightstreamer/version.rb

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

metadata

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