dalli 3.1.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5450b3f6caa26344dbcf9718ee2e12c98d593df098d5aec6f41655783675e2b8
-  data.tar.gz: fdc8ff913351a2ed85fb34c0aa50506f5014e29c3671cbf312eaf7255b526742
+  metadata.gz: 89dd04ff2b4fd6812f2fae613cc984c7d34029a2637ebf5c11d5398361fa7993
+  data.tar.gz: caf5ad6315ddb803ba61418d189c99ce7849f1acced49cf6e32e78e5ca35817f
 SHA512:
-  metadata.gz: 226719cde318de90be8fb77160b926ddbc75002ab0632494c7de0d1917bc88a8fde01b0e827765db3baa5f439c42f840a298c546d56473109e65003509d452ff
-  data.tar.gz: 6b9ca93a048ae7a5074bd128432ceb1f19497e16c773a4a246ba1da13ecb1d7e9024c41f9e112ecea2244205afded043d893c8368fcf5c137b14f134b9f1548e
+  metadata.gz: e425b9704308ce7f3737c7e07dcd2699448ba173fd8fa3ac1e9d3d8867890ce1029dd69f98fb4856bab6c8d81685d34be1c41a192039fccb631c2d4b4749b85a
+  data.tar.gz: 0afdb9aa3fde689a6b84b72aa44aa228e23994f747cce60f8a3471f250a7fa60fdbb3481e4ab4f2665de80be4799b3294f308bb86efa815867e121cd7dc223c9

data/History.md

@@ -1,6 +1,16 @@
 Dalli Changelog
 =====================
 
+Unreleased
+==========
+
+3.1.1
+==========
+
+- Add quiet support for incr, decr, append, depend, and flush (petergoldstein)
+- Additional refactoring to allow reuse of connection behavior (petergoldstein)
+- Fix issue in flush such that it wasn't passing the delay argument to memcached (petergoldstein)
+
 3.1.0
 ==========
 

data/lib/dalli/client.rb

@@ -49,7 +49,7 @@ module Dalli
     def initialize(servers = nil, options = {})
       @servers = ::Dalli::ServersArgNormalizer.normalize_servers(servers)
       @options = normalize_options(options)
-      @key_manager = ::Dalli::KeyManager.new(options)
+      @key_manager = ::Dalli::KeyManager.new(@options)
       @ring = nil
     end
 
@@ -58,24 +58,39 @@ module Dalli
     #
 
     ##
-    # Turn on quiet aka noreply support.
-    # All relevant operations within this block will be effectively
-    # pipelined as Dalli will use 'quiet' operations where possible.
-    # Currently supports the set, add, replace and delete operations.
-    def multi
-      old = Thread.current[::Dalli::MULTI_KEY]
-      Thread.current[::Dalli::MULTI_KEY] = true
-      yield
-    ensure
-      @ring&.pipeline_consume_and_ignore_responses
-      Thread.current[::Dalli::MULTI_KEY] = old
+    # Get the value associated with the key.
+    # If a value is not found, then +nil+ is returned.
+    def get(key, req_options = nil)
+      perform(:get, key, req_options)
     end
 
     ##
-    # Get the value associated with the key.
+    # Gat (get and touch) fetch an item and simultaneously update its expiration time.
+    #
     # If a value is not found, then +nil+ is returned.
-    def get(key, options = nil)
-      perform(:get, key, options)
+    def gat(key, ttl = nil)
+      perform(:gat, key, ttl_or_default(ttl))
+    end
+
+    ##
+    # Touch updates expiration time for a given key.
+    #
+    # Returns true if key exists, otherwise nil.
+    def touch(key, ttl = nil)
+      resp = perform(:touch, key, ttl_or_default(ttl))
+      resp.nil? ? nil : true
+    end
+
+    ##
+    # Get the value and CAS ID associated with the key.  If a block is provided,
+    # value and CAS will be passed to the block.
+    def get_cas(key)
+      (value, cas) = perform(:cas, key)
+      #  TODO: This is odd.  Confirm this is working as expected.
+      value = nil if !value || value == 'Not found'
+      return [value, cas] unless block_given?
+
+      yield value, cas
     end
 
     ##
@@ -97,7 +112,21 @@ module Dalli
       end
     end
 
-    CACHE_NILS = { cache_nils: true }.freeze
+    ##
+    # Fetch multiple keys efficiently, including available metadata such as CAS.
+    # If a block is given, yields key/data pairs one a time.  Data is an array:
+    # [value, cas_id]
+    # If no block is given, returns a hash of
+    #   { 'key' => [value, cas_id] }
+    def get_multi_cas(*keys)
+      if block_given?
+        pipelined_getter.process(keys) { |*args| yield(*args) }
+      else
+        {}.tap do |hash|
+          pipelined_getter.process(keys) { |k, data| hash[k] = data }
+        end
+      end
+    end
 
     # Fetch the value associated with the key.
     # If a value is found, then it is returned.
@@ -110,19 +139,11 @@ module Dalli
     def fetch(key, ttl = nil, req_options = nil)
       req_options = req_options.nil? ? CACHE_NILS : req_options.merge(CACHE_NILS) if cache_nils
       val = get(key, req_options)
-      if not_found?(val) && block_given?
-        val = yield
-        add(key, val, ttl_or_default(ttl), req_options)
-      end
-      val
-    end
+      return val unless block_given? && not_found?(val)
 
-    def not_found?(val)
-      cache_nils ? val == ::Dalli::NOT_FOUND : val.nil?
-    end
-
-    def cache_nils
-      @options[:cache_nils]
+      new_val = yield
+      add(key, new_val, ttl_or_default(ttl), req_options)
+      new_val
     end
 
     ##
@@ -136,8 +157,8 @@ module Dalli
     # - nil if the key did not exist.
     # - false if the value was changed by someone else.
     # - true if the value was successfully updated.
-    def cas(key, ttl = nil, options = nil, &block)
-      cas_core(key, false, ttl, options, &block)
+    def cas(key, ttl = nil, req_options = nil, &block)
+      cas_core(key, false, ttl, req_options, &block)
     end
 
     ##
@@ -147,30 +168,78 @@ module Dalli
     # Returns:
     # - false if the value was changed by someone else.
     # - true if the value was successfully updated.
-    def cas!(key, ttl = nil, options = nil, &block)
-      cas_core(key, true, ttl, options, &block)
+    def cas!(key, ttl = nil, req_options = nil, &block)
+      cas_core(key, true, ttl, req_options, &block)
+    end
+
+    ##
+    # Turn on quiet aka noreply support for a number of
+    # memcached operations.
+    #
+    # All relevant operations within this block will be effectively
+    # pipelined as Dalli will use 'quiet' versions.  The invoked methods
+    # will all return nil, rather than their usual response.  Method
+    # latency will be substantially lower, as the caller will not be
+    # blocking on responses.
+    #
+    # Currently supports storage (set, add, replace, append, prepend),
+    # arithmetic (incr, decr), flush and delete operations.  Use of
+    # unsupported operations inside a block will raise an error.
+    #
+    # Any error replies will be discarded at the end of the block, and
+    # Dalli client methods invoked inside the block will not
+    # have return values
+    def quiet
+      old = Thread.current[::Dalli::QUIET]
+      Thread.current[::Dalli::QUIET] = true
+      yield
+    ensure
+      @ring&.pipeline_consume_and_ignore_responses
+      Thread.current[::Dalli::QUIET] = old
     end
+    alias multi quiet
 
-    def set(key, value, ttl = nil, options = nil)
-      perform(:set, key, value, ttl_or_default(ttl), 0, options)
+    def set(key, value, ttl = nil, req_options = nil)
+      set_cas(key, value, 0, ttl, req_options)
+    end
+
+    ##
+    # Set the key-value pair, verifying existing CAS.
+    # Returns the resulting CAS value if succeeded, and falsy otherwise.
+    def set_cas(key, value, cas, ttl = nil, req_options = nil)
+      perform(:set, key, value, ttl_or_default(ttl), cas, req_options)
     end
 
     ##
     # Conditionally add a key/value pair, if the key does not already exist
     # on the server.  Returns truthy if the operation succeeded.
-    def add(key, value, ttl = nil, options = nil)
-      perform(:add, key, value, ttl_or_default(ttl), options)
+    def add(key, value, ttl = nil, req_options = nil)
+      perform(:add, key, value, ttl_or_default(ttl), req_options)
     end
 
     ##
     # Conditionally add a key/value pair, only if the key already exists
     # on the server.  Returns truthy if the operation succeeded.
-    def replace(key, value, ttl = nil, options = nil)
-      perform(:replace, key, value, ttl_or_default(ttl), 0, options)
+    def replace(key, value, ttl = nil, req_options = nil)
+      replace_cas(key, value, 0, ttl, req_options)
+    end
+
+    ##
+    # Conditionally add a key/value pair, verifying existing CAS, only if the
+    # key already exists on the server.  Returns the new CAS value if the
+    # operation succeeded, or falsy otherwise.
+    def replace_cas(key, value, cas, ttl = nil, req_options = nil)
+      perform(:replace, key, value, ttl_or_default(ttl), cas, req_options)
+    end
+
+    # Delete a key/value pair, verifying existing CAS.
+    # Returns true if succeeded, and falsy otherwise.
+    def delete_cas(key, cas = 0)
+      perform(:delete, key, cas)
     end
 
     def delete(key)
-      perform(:delete, key, 0)
+      delete_cas(key, 0)
     end
 
     ##
@@ -187,13 +256,6 @@ module Dalli
       perform(:prepend, key, value.to_s)
     end
 
-    def flush(delay = 0)
-      time = -delay
-      ring.servers.map { |s| s.request(:flush, time += delay) }
-    end
-
-    alias flush_all flush
-
     ##
     # Incr adds the given amount to the counter on the memcached server.
     # Amt must be a positive integer value.
@@ -205,8 +267,10 @@ module Dalli
     # Note that the ttl will only apply if the counter does not already
     # exist.  To increase an existing counter and update its TTL, use
     # #cas.
+    #
+    # If the value already exists, it must have been set with raw: true
     def incr(key, amt = 1, ttl = nil, default = nil)
-      raise ArgumentError, "Positive values only: #{amt}" if amt.negative?
+      check_positive!(amt)
 
       perform(:incr, key, amt.to_i, ttl_or_default(ttl), default)
     end
@@ -225,35 +289,31 @@ module Dalli
     # Note that the ttl will only apply if the counter does not already
     # exist.  To decrease an existing counter and update its TTL, use
     # #cas.
+    #
+    # If the value already exists, it must have been set with raw: true
     def decr(key, amt = 1, ttl = nil, default = nil)
-      raise ArgumentError, "Positive values only: #{amt}" if amt.negative?
+      check_positive!(amt)
 
       perform(:decr, key, amt.to_i, ttl_or_default(ttl), default)
     end
 
     ##
-    # Touch updates expiration time for a given key.
-    #
-    # Returns true if key exists, otherwise nil.
-    def touch(key, ttl = nil)
-      resp = perform(:touch, key, ttl_or_default(ttl))
-      resp.nil? ? nil : true
-    end
-
+    # Flush the memcached server, at 'delay' seconds in the future.
+    # Delay defaults to zero seconds, which means an immediate flush.
     ##
-    # Gat (get and touch) fetch an item and simultaneously update its expiration time.
-    #
-    # If a value is not found, then +nil+ is returned.
-    def gat(key, ttl = nil)
-      perform(:gat, key, ttl_or_default(ttl))
+    def flush(delay = 0)
+      ring.servers.map { |s| s.request(:flush, delay) }
     end
+    alias flush_all flush
+
+    ALLOWED_STAT_KEYS = %i[items slabs settings].freeze
 
     ##
     # Collect the stats for each server.
     # You can optionally pass a type including :items, :slabs or :settings to get specific stats
     # Returns a hash like { 'hostname:port' => { 'stat1' => 'value1', ... }, 'hostname2:port' => { ... } }
     def stats(type = nil)
-      type = nil unless [nil, :items, :slabs, :settings].include? type
+      type = nil unless ALLOWED_STAT_KEYS.include? type
       values = {}
       ring.servers.each do |server|
         values[server.name.to_s] = server.alive? ? server.request(:stats, type.to_s) : nil
@@ -269,12 +329,6 @@ module Dalli
       end
     end
 
-    ##
-    ## Make sure memcache servers are alive, or raise an Dalli::RingError
-    def alive!
-      ring.server_for_key('')
-    end
-
     ##
     ## Version of the memcache servers.
     def version
@@ -286,55 +340,9 @@ module Dalli
     end
 
     ##
-    # Get the value and CAS ID associated with the key.  If a block is provided,
-    # value and CAS will be passed to the block.
-    def get_cas(key)
-      (value, cas) = perform(:cas, key)
-      value = nil if !value || value == 'Not found'
-      if block_given?
-        yield value, cas
-      else
-        [value, cas]
-      end
-    end
-
-    ##
-    # Fetch multiple keys efficiently, including available metadata such as CAS.
-    # If a block is given, yields key/data pairs one a time.  Data is an array:
-    # [value, cas_id]
-    # If no block is given, returns a hash of
-    #   { 'key' => [value, cas_id] }
-    def get_multi_cas(*keys)
-      if block_given?
-        pipelined_getter.process(keys) { |*args| yield(*args) }
-      else
-        {}.tap do |hash|
-          pipelined_getter.process(keys) { |k, data| hash[k] = data }
-        end
-      end
-    end
-
-    ##
-    # Set the key-value pair, verifying existing CAS.
-    # Returns the resulting CAS value if succeeded, and falsy otherwise.
-    def set_cas(key, value, cas, ttl = nil, options = nil)
-      ttl ||= @options[:expires_in].to_i
-      perform(:set, key, value, ttl, cas, options)
-    end
-
-    ##
-    # Conditionally add a key/value pair, verifying existing CAS, only if the
-    # key already exists on the server.  Returns the new CAS value if the
-    # operation succeeded, or falsy otherwise.
-    def replace_cas(key, value, cas, ttl = nil, options = nil)
-      ttl ||= @options[:expires_in].to_i
-      perform(:replace, key, value, ttl, cas, options)
-    end
-
-    # Delete a key/value pair, verifying existing CAS.
-    # Returns true if succeeded, and falsy otherwise.
-    def delete_cas(key, cas = 0)
-      perform(:delete, key, cas)
+    ## Make sure memcache servers are alive, or raise an Dalli::RingError
+    def alive!
+      ring.server_for_key('')
     end
 
     ##
@@ -346,6 +354,16 @@ module Dalli
     end
     alias reset close
 
+    CACHE_NILS = { cache_nils: true }.freeze
+
+    def not_found?(val)
+      cache_nils ? val == ::Dalli::NOT_FOUND : val.nil?
+    end
+
+    def cache_nils
+      @options[:cache_nils]
+    end
+
     # Stub method so a bare Dalli client can pretend to be a connection pool.
     def with
       yield self
@@ -353,15 +371,23 @@ module Dalli
 
     private
 
-    def cas_core(key, always_set, ttl = nil, options = nil)
+    def check_positive!(amt)
+      raise ArgumentError, "Positive values only: #{amt}" if amt.negative?
+    end
+
+    def cas_core(key, always_set, ttl = nil, req_options = nil)
       (value, cas) = perform(:cas, key)
       value = nil if !value || value == 'Not found'
       return if value.nil? && !always_set
 
       newvalue = yield(value)
-      perform(:set, key, newvalue, ttl_or_default(ttl), cas, options)
+      perform(:set, key, newvalue, ttl_or_default(ttl), cas, req_options)
     end
 
+    ##
+    # Uses the argument TTL or the client-wide default.  Ensures
+    # that the value is an integer
+    ##
     def ttl_or_default(ttl)
       (ttl || @options[:expires_in]).to_i
     rescue NoMethodError
@@ -382,7 +408,16 @@ module Dalli
       @protocol_implementation ||= @options.fetch(:protocol_implementation, Dalli::Protocol::Binary)
     end
 
-    # Chokepoint method for instrumentation
+    ##
+    # Chokepoint method for memcached methods with a key argument.
+    # Validates the key, resolves the key to the appropriate server
+    # instance, and invokes the memcached method on the appropriate
+    # server.
+    #
+    # This method also forces retries on network errors - when
+    # a particular memcached instance becomes unreachable, or the
+    # operational times out.
+    ##
     def perform(*all_args)
       return yield if block_given?
 

data/lib/dalli/options.rb

@@ -31,19 +31,19 @@ module Dalli
       end
     end
 
-    def pipeline_response_start
+    def pipeline_response_setup
       @lock.synchronize do
         super
       end
     end
 
-    def process_outstanding_pipeline_requests
+    def pipeline_next_responses
       @lock.synchronize do
         super
       end
     end
 
-    def pipeline_response_abort
+    def pipeline_abort
       @lock.synchronize do
         super
       end

data/lib/dalli/pipelined_getter.rb

@@ -19,13 +19,7 @@ module Dalli
       @ring.lock do
         servers = setup_requests(keys)
         start_time = Time.now
-        loop do
-          # Remove any servers which are not connected
-          servers.delete_if { |s| !s.connected? }
-          break if servers.empty?
-
-          servers = fetch_responses(servers, start_time, @ring.socket_timeout, &block)
-        end
+        servers = fetch_responses(servers, start_time, @ring.socket_timeout, &block) until servers.empty?
       end
     rescue NetworkError => e
       Dalli.logger.debug { e.inspect }
@@ -44,6 +38,10 @@ module Dalli
     ##
     # Loop through the server-grouped sets of keys, writing
     # the corresponding getkq requests to the appropriate servers
+    #
+    # It's worth noting that we could potentially reduce bytes
+    # on the wire by switching from getkq to getq, and using
+    # the opaque value to match requests to responses.
     ##
     def make_getkq_requests(groups)
       groups.each do |server, keys_for_server|
@@ -80,7 +78,7 @@ module Dalli
     end
 
     def finish_query_for_server(server)
-      server.pipeline_response_start
+      server.pipeline_response_setup
     rescue Dalli::NetworkError
       raise
     rescue Dalli::DalliError => e
@@ -91,10 +89,14 @@ module Dalli
 
     # Swallows Dalli::NetworkError
     def abort_without_timeout(servers)
-      servers.each(&:pipeline_response_abort)
+      servers.each(&:pipeline_abort)
     end
 
     def fetch_responses(servers, start_time, timeout, &block)
+      # Remove any servers which are not connected
+      servers.delete_if { |s| !s.connected? }
+      return [] if servers.empty?
+
       time_left = remaining_time(start_time, timeout)
       readable_servers = servers_with_response(servers, time_left)
       if readable_servers.empty?
@@ -135,11 +137,11 @@ module Dalli
     # Processes responses from a server.  Returns true if there are no
     # additional responses from this server.
     def process_server(server)
-      server.process_outstanding_pipeline_requests.each_pair do |key, value_list|
+      server.pipeline_next_responses.each_pair do |key, value_list|
         yield @key_manager.key_without_namespace(key), value_list
       end
 
-      server.pipeline_response_completed?
+      server.pipeline_complete?
     end
 
     def servers_with_response(servers, timeout)

data/lib/dalli/protocol/binary/request_formatter.rb

@@ -31,11 +31,14 @@ module Dalli
           deleteq: 0x14,
           incrq: 0x15,
           decrq: 0x16,
+          flushq: 0x18,
+          appendq: 0x19,
+          prependq: 0x1A,
+          touch: 0x1C,
+          gat: 0x1D,
           auth_negotiation: 0x20,
           auth_request: 0x21,
-          auth_continue: 0x22,
-          touch: 0x1C,
-          gat: 0x1D
+          auth_continue: 0x22
         }.freeze
 
         REQ_HEADER_FORMAT = 'CCnCCnNNQ'
@@ -56,6 +59,8 @@ module Dalli
 
           append: KEY_AND_VALUE,
           prepend: KEY_AND_VALUE,
+          appendq: KEY_AND_VALUE,
+          prependq: KEY_AND_VALUE,
           auth_request: KEY_AND_VALUE,
           auth_continue: KEY_AND_VALUE,
 
@@ -68,8 +73,11 @@ module Dalli
 
           incr: INCR_DECR,
           decr: INCR_DECR,
+          incrq: INCR_DECR,
+          decrq: INCR_DECR,
 
           flush: TTL_ONLY,
+          flushq: TTL_ONLY,
 
           noop: NO_BODY,
           auth_negotiation: NO_BODY,

data/lib/dalli/protocol/binary/response_processor.rb

@@ -58,7 +58,7 @@ module Dalli
           read(ResponseHeader::SIZE) || raise(Dalli::NetworkError, 'No response')
         end
 
-        def raise_on_not_ok_status!(resp_header)
+        def raise_on_not_ok!(resp_header)
           return if resp_header.ok?
 
           raise Dalli::DalliError, "Response error #{resp_header.status}: #{RESPONSE_CODES[resp_header.status]}"
@@ -67,24 +67,45 @@ module Dalli
         def generic_response(unpack: false, cache_nils: false)
           resp_header, body = read_response
 
-          return cache_nils ? ::Dalli::NOT_FOUND : nil if resp_header.not_found?
           return false if resp_header.not_stored? # Not stored, normal status for add operation
+          return cache_nils ? ::Dalli::NOT_FOUND : nil if resp_header.not_found?
 
-          raise_on_not_ok_status!(resp_header)
+          raise_on_not_ok!(resp_header)
           return true unless body
 
           unpack_response_body(resp_header.extra_len, resp_header.key_len, body, unpack).last
         end
 
-        def data_cas_response
+        ##
+        # Response for a storage operation.  Returns the cas on success.  False
+        # if the value wasn't stored.  And raises an error on all other error
+        # codes from memcached.
+        ##
+        def storage_response
+          resp_header, = read_response
+          return false if resp_header.not_stored? # Not stored, normal status for add operation
+
+          raise_on_not_ok!(resp_header)
+          resp_header.cas
+        end
+
+        def no_body_response
+          resp_header, = read_response
+          return false if resp_header.not_stored? # Not stored, possible status for append/prepend
+
+          raise_on_not_ok!(resp_header)
+          true
+        end
+
+        def data_cas_response(unpack: true)
           resp_header, body = read_response
           return [nil, resp_header.cas] if resp_header.not_found?
           return [nil, false] if resp_header.not_stored?
 
-          raise_on_not_ok_status!(resp_header)
+          raise_on_not_ok!(resp_header)
           return [nil, resp_header.cas] unless body
 
-          [unpack_response_body(resp_header.extra_len, resp_header.key_len, body, true).last, resp_header.cas]
+          [unpack_response_body(resp_header.extra_len, resp_header.key_len, body, unpack).last, resp_header.cas]
         end
 
         def cas_response
@@ -146,31 +167,32 @@ module Dalli
         # complete response is found in the buffer, this will
         # be the response size.  Otherwise it is zero.
         #
-        # The remaining four values in the array are the status, key,
-        # value, and cas returned from the response.
+        # The remaining three values in the array are the ResponseHeader,
+        # key, and value.
         ##
         def getk_response_from_buffer(buf)
           # There's no header in the buffer, so don't advance
-          return [0, 0, nil, nil, nil] unless contains_header?(buf)
+          return [0, nil, nil, nil] unless contains_header?(buf)
 
           resp_header = response_header_from_buffer(buf)
           body_len = resp_header.body_len
 
-          # The response has no body - so we need to advance the
-          # buffer.  This is either the response to the terminating
+          # We have a complete response that has no body.
+          # This is either the response to the terminating
           # noop or, if the status is not zero, an intermediate
           # error response that needs to be discarded.
-          return [ResponseHeader::SIZE, resp_header.status, nil, nil, resp_header.cas] if body_len.zero?
+          return [ResponseHeader::SIZE, resp_header, nil, nil] if body_len.zero?
 
-          # The header is in the buffer, but the body is not
           resp_size = ResponseHeader::SIZE + body_len
-          return [0, resp_header.status, nil, nil, nil] unless buf.bytesize >= resp_size
+          # The header is in the buffer, but the body is not.  As we don't have
+          # a complete response, don't advance the buffer
+          return [0, nil, nil, nil] unless buf.bytesize >= resp_size
 
           # The full response is in our buffer, so parse it and return
           # the values
           body = buf.slice(ResponseHeader::SIZE, body_len)
           key, value = unpack_response_body(resp_header.extra_len, resp_header.key_len, body, true)
-          [resp_size, resp_header.status, key, value, resp_header.cas]
+          [resp_size, resp_header, key, value]
         end
       end
     end