yugabyte-ycql-driver 3.2.3.1

data/lib/cassandra/listener.rb

@@ -0,0 +1,87 @@
+# encoding: utf-8
+
+#--
+# Copyright 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
+  # Cassandra state listener.
+  #
+  # @abstract Actual state listener implementations don't need to inherit from
+  #   this class as long as they conform to its interface. This class exists
+  #   solely for documentation purposes
+  #
+  # @see Cassandra::Cluster#register
+  class Listener
+    # This method is called whenever a host is considered to be up, whether
+    #   by Cassandra's gossip exchange or when the driver has successfully
+    #   established a connection to it.
+    #
+    # @param host [Cassandra::Host] a host instance
+    # @return [void]
+    def host_up(host)
+    end
+
+    # This method is called whenever a host is considered to be down, whether
+    #   by Cassandra's gossip exchange or when the driver failed to establish
+    #   any connections to it.
+    #
+    # @param host [Cassandra::Host] a host instance
+    # @return [void]
+    def host_down(host)
+    end
+
+    # This method is called whenever a host is discovered by the driver,
+    #   whether because it is a completely new node or if its
+    #   {Cassandra::Host#datacenter} or {Cassandra::Host#rack} have changed.
+    #
+    # @param host [Cassandra::Host] a host instance
+    # @return [void]
+    def host_found(host)
+    end
+
+    # This method is called whenever a host leaves the cluster, whether
+    #   because it is completely gone or if its {Cassandra::Host#datacenter} or
+    #   {Cassandra::Host#rack} have changed.
+    #
+    # @param host [Cassandra::Host] a host instance
+    # @return [void]
+    def host_lost(host)
+    end
+
+    # This method is called whenever a new keyspace is created.
+    #
+    # @param keyspace [Cassandra::Keyspace] a keyspace instance
+    # @return [void]
+    def keyspace_created(keyspace)
+    end
+
+    # This method is called whenever an existing keyspace is changed. This
+    # happens when a new table is created or an existing table is dropped or
+    # altered.
+    #
+    # @param keyspace [Cassandra::Keyspace] a keyspace instance
+    # @return [void]
+    def keyspace_changed(keyspace)
+    end
+
+    # This method is called whenever an existing keyspace is dropped.
+    #
+    # @param keyspace [Cassandra::Keyspace] a keyspace instance
+    # @return [void]
+    def keyspace_dropped(keyspace)
+    end
+  end
+end

data/lib/cassandra/load_balancing.rb

@@ -0,0 +1,121 @@
+# encoding: utf-8
+
+#--
+# Copyright 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 LoadBalancing
+    # A list of possible load balancing distances that
+    # {Cassandra::LoadBalancing::Policy#distance} must return
+    DISTANCES = [:ignore, :local, :remote].freeze
+
+    # @abstract Actual load balancing policies don't need to extend this class,
+    #   only implement its methods. This class exists for documentation
+    #   purposes only.
+    class Policy
+      # Allows policy to initialize with the cluster instance. This method is
+      # called once before connecting to the cluster.
+      #
+      # @param cluster [Cassandra::Cluster] current cluster instance
+      # @return [void]
+      def setup(cluster)
+      end
+
+      # Allows policy to release any external resources it might be holding.
+      # This method is called once the cluster has been terminated after calling
+      # {Cassandra::Cluster#close}
+      #
+      # @param cluster [Cassandra::Cluster] current cluster instance
+      # @return [void]
+      def teardown(cluster)
+      end
+
+      # @see Cassandra::Listener#host_up
+      def host_up(host)
+      end
+
+      # @see Cassandra::Listener#host_down
+      def host_down(host)
+      end
+
+      # @see Cassandra::Listener#host_found
+      def host_found(host)
+      end
+
+      # @see Cassandra::Listener#host_lost
+      def host_lost(host)
+      end
+
+      # Returns a distance that determines how many connections (if any) the
+      # driver will open to the host.
+      #
+      # @param host [Cassandra::Host] a host instance
+      # @return [Symbol] distance to host. Must be one of
+      #   {Cassandra::LoadBalancing::DISTANCES}
+      def distance(host)
+      end
+
+      # Load balancing plan is used to determine the order in which hosts
+      #   should be tried in case of a network failure.
+      #
+      # @note Hosts that should be ignored, must not be included in the Plan
+      #
+      # @param keyspace [String] current keyspace of the {Cassandra::Session}
+      # @param statement [Cassandra::Statement] actual statement to be executed
+      # @param options [Cassandra::Execution::Options] execution options to be used
+      # @raise [NotImplementedError] override this method to return a plan
+      # @return [Cassandra::LoadBalancing::Plan] a load balancing plan
+      def plan(keyspace, statement, options)
+      end
+
+      # @private
+      def inspect
+        "#<#{self.class.name}:0x#{object_id.to_s(16)}>"
+      end
+    end
+
+    # A load balancing plan is used to determine the order of hosts for running
+    # queries, preparing statements and establishing connections.
+    # @abstract Plans returned by {Cassandra::LoadBalancing::Policy#plan}
+    #   implementations don't need to extend this class, only implement its
+    #   methods. This class exists for documentation purposes only.
+    class Plan
+      # @return [Boolean] whether the plan contains any more hosts
+      def has_next?
+      end
+
+      # @return [Cql::Host] next host to try
+      def next
+      end
+    end
+
+    # @private
+    class EmptyPlan
+      def has_next?
+        false
+      end
+
+      def next
+        nil
+      end
+    end
+
+    # @private
+    EMPTY_PLAN = EmptyPlan.new
+  end
+end
+
+require 'cassandra/load_balancing/policies'

data/lib/cassandra/load_balancing/policies.rb

@@ -0,0 +1,20 @@
+#--
+# Copyright 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/load_balancing/policies/dc_aware_round_robin'
+require 'cassandra/load_balancing/policies/round_robin'
+require 'cassandra/load_balancing/policies/token_aware'
+require 'cassandra/load_balancing/policies/white_list'

data/lib/cassandra/load_balancing/policies/dc_aware_round_robin.rb

@@ -0,0 +1,172 @@
+# encoding: utf-8
+
+#--
+# Copyright 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 LoadBalancing
+    module Policies
+      class DCAwareRoundRobin < Policy
+        # @private
+        LOCAL_CONSISTENCIES = [:local_quorum, :local_one].freeze
+        # @private
+        EMPTY_ARRAY         = [].freeze
+
+        # @private
+        class Plan
+          def initialize(local, remote, index)
+            @local  = local
+            @remote = remote
+            @index  = index
+
+            @local_remaining  = @local_total  = local.size
+            @remote_remaining = @remote_total = remote.size
+          end
+
+          def has_next?
+            @local_remaining > 0 || @remote_remaining > 0
+          end
+
+          def next
+            if @local_remaining > 0
+              @local_remaining -= 1
+              i = (@index % @local_total)
+              @index += 1
+
+              return @local[i]
+            end
+
+            if @remote_remaining > 0
+              @remote_remaining -= 1
+              i = (@index % @remote_total)
+              @index += 1
+
+              return @remote[i]
+            end
+          end
+        end
+
+        include MonitorMixin
+
+        def initialize(datacenter = nil,
+                       max_remote_hosts_to_use = 0,
+                       use_remote_hosts_for_local_consistency = false)
+          datacenter              &&= String(datacenter)
+          max_remote_hosts_to_use &&= Integer(max_remote_hosts_to_use)
+
+          Util.assert_not_empty(datacenter) { 'datacenter cannot be empty' } unless datacenter.nil?
+
+          unless max_remote_hosts_to_use.nil?
+            Util.assert(max_remote_hosts_to_use >= 0) do
+              'max_remote_hosts_to_use must be nil or >= 0'
+            end
+          end
+
+          # If use_remote* is true, max_remote* must be > 0
+          if use_remote_hosts_for_local_consistency
+            Util.assert(max_remote_hosts_to_use.nil? || max_remote_hosts_to_use > 0,
+                        'max_remote_hosts_to_use must be nil (meaning unlimited) or > 0 when ' \
+                        'use_remote_hosts_for_local_consistency is true')
+          end
+
+          @datacenter = datacenter
+          @max_remote = max_remote_hosts_to_use
+          @local      = ::Array.new
+          @remote     = ::Array.new
+          @position   = 0
+
+          @use_remote = !!use_remote_hosts_for_local_consistency
+
+          mon_initialize
+        end
+
+        def host_up(host)
+          @datacenter = host.datacenter if !@datacenter && host.datacenter
+
+          if host.datacenter.nil? || host.datacenter == @datacenter
+            synchronize { @local = @local.dup.push(host) }
+          elsif @max_remote.nil? || @remote.size < @max_remote
+            synchronize { @remote = @remote.dup.push(host) }
+          end
+
+          self
+        end
+
+        def host_down(host)
+          if host.datacenter.nil? || host.datacenter == @datacenter
+            synchronize do
+              @local = @local.dup
+              @local.delete(host)
+            end
+          else
+            synchronize do
+              @remote = @remote.dup
+              @remote.delete(host)
+            end
+          end
+
+          self
+        end
+
+        def host_found(host)
+          self
+        end
+
+        def host_lost(host)
+          self
+        end
+
+        def distance(host)
+          if host.datacenter.nil? || host.datacenter == @datacenter
+            @local.include?(host) ? :local : :ignore
+          else
+            @remote.include?(host) ? :remote : :ignore
+          end
+        end
+
+        def plan(keyspace, statement, options)
+          local = @local
+
+          remote = if LOCAL_CONSISTENCIES.include?(options.consistency) && !@use_remote
+                     EMPTY_ARRAY
+                   else
+                     @remote
+                   end
+
+          total = local.size + remote.size
+
+          return EMPTY_PLAN if total == 0
+
+          position  = @position % total
+          @position = position + 1
+
+          Plan.new(local, remote, position)
+        end
+
+        # @private
+        def inspect
+          "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+          "datacenter=#{@datacenter.inspect}, " \
+          "use_remote=#{@use_remote.inspect}, " \
+          "max_remote=#{@max_remote.inspect}, " \
+          "local=#{@local.inspect}, " \
+          "remote=#{@remote.inspect}, " \
+          "position=#{@position.inspect}>"
+        end
+      end
+    end
+  end
+end

data/lib/cassandra/load_balancing/policies/round_robin.rb

@@ -0,0 +1,141 @@
+# encoding: utf-8
+
+#--
+# Copyright 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 LoadBalancing
+    module Policies
+      class RoundRobin < Policy
+        # @private
+        class Plan
+          def initialize(hosts, index)
+            @hosts = hosts
+            @index = index
+
+            @total = @remaining = hosts.size
+          end
+
+          def has_next?
+            @remaining > 0
+          end
+
+          def next
+            return if @remaining == 0
+
+            @remaining -= 1
+            index  = @index
+            @index = (index + 1) % @total
+
+            @hosts[index]
+          end
+        end
+
+        include MonitorMixin
+
+        def initialize
+          @hosts    = ::Array.new
+          @position = 0
+
+          mon_initialize
+        end
+
+        # Adds this host to rotation
+        #
+        # @param host [Cassandra::Host] a host instance
+        # @return [Cassandra::LoadBalancing::Policies::RoundRobin] self
+        # @see Cassandra::Listener#host_up
+        def host_up(host)
+          synchronize { @hosts = @hosts.dup.push(host) }
+
+          self
+        end
+
+        # Removes this host from rotation
+        #
+        # @param host [Cassandra::Host] a host instance
+        # @return [Cassandra::LoadBalancing::Policies::RoundRobin] self
+        # @see Cassandra::Listener#host_down
+        def host_down(host)
+          synchronize do
+            @hosts = @hosts.dup
+            @hosts.delete(host)
+          end
+
+          self
+        end
+
+        # Noop
+        #
+        # @param host [Cassandra::Host] a host instance
+        # @return [Cassandra::LoadBalancing::Policies::RoundRobin] self
+        # @see Cassandra::Listener#host_found
+        def host_found(host)
+          self
+        end
+
+        # Noop
+        #
+        # @param host [Cassandra::Host] a host instance
+        # @return [Cassandra::LoadBalancing::Policies::RoundRobin] self
+        # @see Cassandra::Listener#host_lost
+        def host_lost(host)
+          self
+        end
+
+        # Returns distance to host. All hosts in rotation are considered
+        # `:local`, all other hosts - `:ignore`.
+        #
+        # @param host [Cassandra::Host] a host instance
+        # @return [Symbol] `:local` for all hosts in rotation and `:ignore` for
+        #   all other hosts.
+        # @see Cassandra::LoadBalancing::Policy#distance
+        def distance(host)
+          @hosts.include?(host) ? :local : :ignore
+        end
+
+        # Returns a load balancing plan that rotates hosts by 1 each time a
+        # plan is requested.
+        #
+        # @param keyspace [String] current keyspace of the {Cassandra::Session}
+        # @param statement [Cassandra::Statement] actual statement to be
+        #   executed
+        # @param options [Cassandra::Execution::Options] execution options to
+        #   be used
+        # @return [Cassandra::LoadBalancing::Plan] a rotated load balancing plan
+        # @see Cassandra::LoadBalancing::Policy#plan
+        def plan(keyspace, statement, options)
+          hosts = @hosts
+          total = hosts.size
+
+          return EMPTY_PLAN if total == 0
+
+          position  = @position % total
+          @position = position + 1
+
+          Plan.new(hosts, position)
+        end
+
+        # @private
+        def inspect
+          "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+          "hosts=#{@hosts.inspect}, " \
+          "position=#{@position.inspect}>"
+        end
+      end
+    end
+  end
+end