cassandra-driver 0.1.0.alpha1 → 1.0.0.beta.1

data/lib/cassandra/reconnection.rb

@@ -0,0 +1,49 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  module Reconnection
+    # Reconnection schedule
+    # @note actual reconnection schedules returned from
+    #   {Cassandra::Reconnection::Policy} implementation don't need to inherit
+    #   this class. This class exists for documentation purposes only.
+    class Schedule
+      # @return [Numeric] the next reconnection interval in seconds
+      def next
+      end
+    end
+
+    # A reconnection policy
+    # @note actual reconnection policies supplied as `:reconnection_policy`
+    #   option to {Cassandra.connect} don't need to inherit this class, only
+    #   implement its methods. This class exists for documentation purposes
+    #   only.
+    class Policy
+      # Returns a reconnection schedule
+      #
+      # @abstract implementation should be provided by an actual policy
+      # @note reconnection schedule doesn't need to extend
+      #   {Cassandra::Reconnection::Schedule}, only conform to its interface
+      # @return [Cassandra::Reconnection::Schedule] reconnection schedule
+      def schedule
+      end
+    end
+  end
+end
+
+require 'cassandra/reconnection/policies'

data/lib/cassandra/reconnection/policies.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+require 'cassandra/reconnection/policies/constant'
+require 'cassandra/reconnection/policies/exponential'

data/lib/cassandra/reconnection/policies/constant.rb

@@ -0,0 +1,48 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  module Reconnection
+    module Policies
+      # A reconnection policy that returns a constant reconnection interval
+      class Constant < Policy
+        # @private
+        class Schedule
+          def initialize(interval)
+            @interval = interval
+          end
+
+          def next
+            @interval
+          end
+        end
+
+        # @param interval [Numeric] reconnection interval (in seconds)
+        def initialize(interval)
+          @schedule = Schedule.new(Float(interval))
+        end
+
+        # @return [Cassandra::Reconnection::Schedule] reconnection schedule
+        #   with constant interval
+        def schedule
+          @schedule
+        end
+      end
+    end
+  end
+end

data/lib/cassandra/reconnection/policies/exponential.rb

@@ -0,0 +1,79 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  module Reconnection
+    module Policies
+      # A reconnection policy that returns a constant exponentially growing
+      # reconnection interval up to a given maximum
+      class Exponential < Policy
+        # @private
+        class Schedule
+          def initialize(start, max, exponent)
+            @interval = start
+            @max      = max
+            @exponent = exponent
+          end
+
+          def next
+            @interval.tap { backoff if @interval < @max }
+          end
+
+          private
+
+          def backoff
+            new_interval = @interval * @exponent
+
+            if new_interval >= @max
+              @interval = @max
+            else
+              @interval = new_interval
+            end
+          end
+        end
+
+        # @param start    [Numeric] beginning interval
+        # @param max      [Numeric] maximum reconnection interval
+        # @param exponent [Numeric] (2) interval exponent to use
+        #
+        # @example Using this policy
+        #   policy   = Cassandra::Reconnection::Policies::Exponential.new(0.5, 10, 2)
+        #   schedule = policy.schedule
+        #   schedule.next # 0.5
+        #   schedule.next # 1.0
+        #   schedule.next # 2.0
+        #   schedule.next # 4.0
+        #   schedule.next # 8.0
+        #   schedule.next # 10.0
+        #   schedule.next # 10.0
+        #   schedule.next # 10.0
+        def initialize(start, max, exponent = 2)
+          @start    = start
+          @max      = max
+          @exponent = exponent
+        end
+
+        # @return [Cassandra::Reconnection::Schedule] an exponential
+        #   reconnection schedule
+        def schedule
+          Schedule.new(@start, @max, @exponent)
+        end
+      end
+    end
+  end
+end

data/lib/cassandra/result.rb

@@ -0,0 +1,215 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  class Result
+    include Enumerable
+
+    # Query execution information, such as number of retries and all tried hosts, etc.
+    # @return [Cassandra::Execution::Info]
+    def execution_info
+      @info ||= Execution::Info.new(@keyspace, @statement, @options, @hosts, @consistency, @retries, @trace_id ? Execution::Trace.new(@trace_id, @client) : nil)
+    end
+
+    # @return [Boolean] whether it has any rows
+    def empty?
+    end
+
+    # @return [Integer] rows count
+    def size
+    end
+    alias :length :size
+
+    # @yieldparam row [Hash] current row
+    # @return [Enumerator, self] returns Enumerator if no block given
+    def each
+    end
+    alias :rows :each
+    alias :each_row :each
+
+    # @return [Boolean] whether no more pages are available
+    def last_page?
+    end
+
+    # Loads next page synchronously
+    #
+    # @param options [Hash] additional options, just like the ones for
+    #   {Cassandra::Session#execute}
+    #
+    # @return [Cassandra::Result, nil] returns `nil` if last page
+    #
+    # @see Cassandra::Session#execute
+    def next_page(options = nil)
+    end
+
+    # Loads next page asynchronously
+    #
+    # @param options [Hash] additional options, just like the ones for
+    #   {Cassandra::Session#execute_async}
+    #
+    # @return [Cassandra::Future<Cassandra::Result, nil>] `nil` if last
+    #   page
+    #
+    # @see Cassandra::Session#execute
+    def next_page_async(options = nil)
+    end
+  end
+
+  # @private
+  module Results
+    class Paged < Result
+      def initialize(rows, paging_state, trace_id, keyspace, statement, options, hosts, consistency, retries, client, futures_factory)
+        @rows           = rows
+        @paging_state   = paging_state
+        @trace_id       = trace_id
+        @keyspace       = keyspace
+        @statement      = statement
+        @options        = options
+        @hosts          = hosts
+        @consistency    = consistency
+        @retries        = retries
+        @client         = client
+        @futures        = futures_factory
+      end
+
+      # Returns whether or not there are any rows in this result set
+      def empty?
+        @rows.empty?
+      end
+
+      # Returns count of underlying rows
+      def size
+        @rows.size
+      end
+      alias :length :size
+
+      def each(&block)
+        if block_given?
+          @rows.each(&block)
+          self
+        else
+          @rows.each
+        end
+      end
+      alias :rows :each
+      alias :each_row :each
+
+      # Returns true when there are no more pages to load.
+      def last_page?
+        @paging_state.nil?
+      end
+
+      # Returns the next page or nil when there is no next page.
+      #
+      # @return [Cassandra::Result]
+      def next_page(options = nil)
+        next_page_async(options).get
+      end
+
+      def next_page_async(options = nil)
+        return @futures.value(nil) if @paging_state.nil?
+
+        options = options ? @options.override(options) : @options
+
+        if @statement.is_a?(Statements::Simple)
+          @client.query(@statement, options, @paging_state)
+        else
+          @client.execute(@statement, options, @paging_state)
+        end
+      end
+
+      def inspect
+        "#<Cassandra::Result:0x#{self.object_id.to_s(16)} @rows=#{@rows.inspect} @last_page=#{@paging_state.nil?}>"
+      end
+    end
+
+    class Void < Result
+      def initialize(trace_id, keyspace, statement, options, hosts, consistency, retries, client, futures_factory)
+        @trace_id    = trace_id
+        @keyspace    = keyspace
+        @statement   = statement
+        @options     = options
+        @hosts       = hosts
+        @consistency = consistency
+        @retries     = retries
+        @client      = client
+        @futures     = futures_factory
+      end
+
+      # Returns whether or not there are any rows in this result set
+      def empty?
+        true
+      end
+
+      # Returns count of underlying rows
+      def size
+        0
+      end
+      alias :length :size
+
+      # Iterates over each row in the result set.
+      #
+      # @yieldparam row [Hash] each row in the result set as a hash
+      # @return [Cassandra::Result]
+      def each(&block)
+        if block_given?
+          NO_ROWS.each(&block)
+          self
+        else
+          NO_ROWS.each
+        end
+      end
+      alias :rows :each
+      alias :each_row :each
+
+      # Returns true when there are no more pages to load.
+      #
+      # This is only relevant when you have requested paging of the results with
+      # the `:page_size` option to {Cassandra::Client::Client#execute} or
+      # {Cassandra::Client::PreparedStatement#execute}.
+      #
+      # @see Cassandra::Client::Client#execute
+      def last_page?
+        true
+      end
+
+      # Returns the next page or nil when there is no next page.
+      #
+      # This is only relevant when you have requested paging of the results with
+      # the `:page_size` option to {Cassandra::Client::Client#execute} or
+      # {Cassandra::Client::PreparedStatement#execute}.
+      #
+      # @see Cassandra::Client::Client#execute
+      def next_page_async(options = nil)
+        @futures.value(nil)
+      end
+
+      def next_page(options = nil)
+        nil
+      end
+
+      def inspect
+        "#<Cassandra::Result:0x#{self.object_id.to_s(16)} @rows=[] @last_page=true>"
+      end
+
+      private
+
+      NO_ROWS = [].freeze
+    end
+  end
+end

data/lib/cassandra/retry.rb

@@ -0,0 +1,142 @@
+# encoding: utf-8
+
+#--
+# Copyright 2013-2014 DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#++
+
+module Cassandra
+  module Retry
+    module Policy
+      # Decides wether to retry a read and at what consistency level.
+      # 
+      # @note this method may be called even if required_responses >= received
+      #   responses if data_present is false.
+      # 
+      # @param statement [Cassandra::Statement] the original statement that timed out
+      # @param consistency [Symbol] the original consistency level for the
+      #   request, one of {Cassandra::CONSISTENCIES}
+      # @param required [Integer] the number of responses required to achieve
+      #   requested consistency level
+      # @param received [Integer] the number of responses received by the time
+      #   the query timed out
+      # @param retrieved [Boolean] whether actual data (as opposed to data
+      #   checksum) was present in the received responses.
+      # @param retries [Integer] the number of retries already performed
+      # 
+      # @abstract implementation should be provided by an actual policy
+      # @return [Cassandra::Policies::Retry::Decision] a retry decision
+      #
+      # @see Cassandra::Retry::Policy#try_again
+      # @see Cassandra::Retry::Policy#reraise
+      # @see Cassandra::Retry::Policy#ignore
+      def read_timeout(statement, consistency, required, received, retrieved, retries)
+      end
+
+      # Decides wether to retry a write and at what consistency level.
+      # 
+      # @param statement [Cassandra::Statement] the original statement that timed out
+      # @param consistency [Symbol] the original consistency level for the
+      #   request, one of {Cassandra::CONSISTENCIES}
+      # @param type [Symbol] One of `:simple`, `:batch`, `:unlogged_batch`,
+      #   `:counter` or `:batch_log`
+      # @param required [Integer] the number of acks required to achieve
+      #   requested consistency level
+      # @param received [Integer] the number of acks received by the time the
+      #   query timed out
+      # @param retries [Integer] the number of retries already performed
+      # 
+      # @abstract implementation should be provided by an actual policy
+      # @return [Cassandra::Policies::Retry::Decision] a retry decision
+      #
+      # @see Cassandra::Retry::Policy#try_again
+      # @see Cassandra::Retry::Policy#reraise
+      # @see Cassandra::Retry::Policy#ignore
+      def write_timeout(statement, consistency, type, required, received, retries)
+      end
+
+      # Decides wether to retry and at what consistency level on an Unavailable
+      # exception.
+      # 
+      # @param statement [Cassandra::Statement] the original Statement that timed out
+      # @param consistency [Symbol] the original consistency level for the
+      #   request, one of {Cassandra::CONSISTENCIES}
+      # @param required [Integer] the number of replicas required to achieve
+      #   requested consistency level
+      # @param alive [Integer] the number of replicas received by the time the
+      #   query timed out
+      # @param retries [Integer] the number of retries already performed
+      # 
+      # @abstract implementation should be provided by an actual policy
+      # @return [Cassandra::Policies::Retry::Decision] a retry decision
+      #
+      # @see Cassandra::Retry::Policy#try_again
+      # @see Cassandra::Retry::Policy#reraise
+      # @see Cassandra::Retry::Policy#ignore
+      def unavailable(statement, consistency, required, alive, retries)
+      end
+
+      private
+
+      # Returns a decision that signals retry at a given consistency
+      #
+      # @param consistency [Symbol] consistency level for the retry, one of
+      #   {Cassandra::CONSISTENCIES}
+      # @return [Cassandra::Policies::Retry::Decision] tell driver to retry
+      def try_again(consistency)
+        Decisions::Retry.new(consistency)
+      end
+
+      # Returns a decision that signals to driver to reraise original error to
+      # the application
+      #
+      # @return [Cassandra::Policies::Retry::Decision] tell driver to reraise
+      def reraise
+        DECISION_RERAISE
+      end
+
+      # Returns a decision that signals to driver to ignore the error
+      #
+      # @return [Cassandra::Policies::Retry::Decision] tell driver to ignore the error
+      #   and return an empty result to the application
+      def ignore
+        DECISION_IGNORE
+      end
+    end
+
+    # @private
+    module Decisions
+      class Retry
+        attr_reader :consistency
+
+        def initialize(consistency)
+          @consistency = consistency
+        end
+      end
+
+      class Reraise
+      end
+
+      class Ignore
+      end
+    end
+
+    # @private
+    DECISION_RERAISE = Decisions::Reraise.new
+    # @private
+    DECISION_IGNORE  = Decisions::Ignore.new
+  end
+end
+
+require 'cassandra/retry/policies'