= stockpile-redis

code :: https://github.com/halostatue/stockpile-redis/
bugs :: https://github.com/halostatue/stockpile-redis/issues
continuous integration :: {<img src="https://travis-ci.org/halostatue/stockpile-redis.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/halostatue/stockpile-redis]

== Description

stockpile-redis is a connection manager for Redis to be used with
{Stockpile}[https://github.com/halostatue/stockpile].

== Features

stockpile-redis supports both normal Redis connections (<tt>Redis.new</tt>),
and Redis::Namespace connections (<tt>Redis::Namespace.new('namespace', redis:
Redis.new)</tt>).

stockpile-redis provides special-case handling for connections for Resque when
the name of the client is +:resque+.

Release 2.0 fixes an issue with initialization using OpenStruct for options.
Ruby 1.9 is no longer supported.

== Synopsis

  require 'stockpile/redis'

  wide = Stockpile.new(manager: Stockpile::Redis) # A Stockpile to Redis.
  wide.connection.set('hello', 'world') # => 'OK'
  wide.connection.get('hello') # => 'world'

  # Connections are independent from one another.
  wide.connection_for(:other) != wide.connection # => true

  # A 'narrow' Stockpile to Redis.
  narrow = Stockpile.new(manager: Stockpile::Redis, narrow: true)
  # Or set ENV['STOCKPILE_CONNECTION_WIDTH'] = 'narrow' and call Stockpile.new
  # normally.
  narrow.connection_for(:other) == narrow.connection # => true

  # Special Redis::Namespace handling for Resque clients.
  narrow.connection_for(:resque) != narrow.connection # => true
  narrow.connection_for(:resque).redis == narrow.connection # => true

  # Standard namespace handling.
  narrow.connection_for(:other, namespace: 'other') !=
    narrow.connection # => true
  narrow.connection_for(:other, namespace: 'other').redis !=
    narrow.connection # => true

  # Show a Stockpile with no adapter capabilities, but name the method
  # stockpile, not cache. This will still usefully manage connections.
  # The use of inject_redis! makes Stockpile::Redis the default connection
  # manager for the Cacher module Stockpile.
  module Cacher
    Stockpile.inject_redis!(self, method: :stockpile, adaptable: false)
  end
  Cacher.respond_to?(:stockpile) # => true
  Cacher.respond_to?(:stockpile_adapter) # => false
  Cacher.stockpile.connection.set('hello', 'world') # => 'OK'
  Cacher.stockpile.connection.get('hello') # => 'world'

  # Now a Stockpile with adapter capabilities.
  module Jobber
    module LastRunTime
      def last_run_time(key, value = nil)
        if value
          connection.hset(__method__, key, value.utc.iso8601)
        else
          value = connection.hget(__method__, key)
          Time.parse(value) if value
        end
      end
    end

    Stockpile.inject_redis!(self)
  end
  Jobber.respond_to?(:cache) # => true
  Jobber.respond_to?(:cache_adapter) # => true

  # Four ways:
  # 1. Adapt Jobber.cache to recognize #last_run_time.
  Jobber.cache_adapter(Jobber::LastRunTime)
  Jobber.cache.last_run_time('hello', t = Time.now) # => true
  Jobber.cache.last_run_time('hello') # => approximately t

  # 2. Adapt Jobber.cache and another module to recognize #last_run_time.
  module Foo; end
  Jobber.cache_adapter(Jobber::LastRunTime, Foo)
  Foo.last_run_time('hello', t = Time.now) # => true
  Foo.last_run_time('hello') # => approximately t

  # 3. Adapt Jobber.cache and Jobber to recognize #last_run_time.
  Jobber.cache_adapter(Jobber::LastRunTime, Jobber)
  Jobber.last_run_time('hello', t = Time.now) # => true
  Jobber.last_run_time('hello') # => approximately t

  # 4. Adapt Jobber.cache and Jobber::LastRunTime to recognize #last_run_time.
  Jobber.cache_adapter!(Jobber::LastRunTime)
  # or Jobber.cache_adapter(Jobber::LastRunTime, Jobber::LastRunTime)
  Jobber::LastRunTime.last_run_time('hello', t = Time.now) # => true
  Jobber::LastRunTime.last_run_time('hello') # => approximately t

== Install

Put stockpile-redis in your Gemfile:

  gem 'stockpile-redis', '~> 2.0'

Or manually install:

  % gem install stockpile-redis

and require Stockpile in your code:

  require 'stockpile/redis'

== stockpile-redis Semantic Versioning

stockpile-redis uses a {Semantic Versioning}[http://semver.org/] scheme with
one change:

* When PATCH is zero (+0+), it will be omitted from version references.

:include: Contributing.rdoc

:include: Licence.rdoc