diskcached 1.1.0 → 1.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2d3ce84b679e0539fce33f13ae46242030555375
+  data.tar.gz: 8d122fd674accaae92f1cbb3fc5ed9d9f024a34a
+SHA512:
+  metadata.gz: 3e4f49916e1134d3187f21434663ac638da6ed24bca20764bd0d553eee0af2eed666b42e84fb21be17393d9ef2d10a6093d7f81b0c422082e694c4277f6b37ab
+  data.tar.gz: 377874d6837768046cc7a2909a73659c2dc47d9211e6de678c6345db3210d844ff6742b450b164a1cf8633b1c8a96fdf1b08b25539e92f8b084b32dffdd4cacd

data/Gemfile

@@ -1,11 +1,12 @@
-source :rubygems
+source 'https://rubygems.org'
 
 group :development, :test do
   gem 'rake'
 end
 
 group :development do
-  gem 'rdoc'
+  gem 'yard'
+  gem 'redcarpet'
 end
 
 group :benchmark do
@@ -18,5 +19,3 @@ group :test do
   gem 'rspec'
   gem 'simplecov', :require => false
 end
-
-

data/README.md

@@ -1,3 +1,137 @@
 # Diskcached
 
-See: http://rubyops.net/2012/07/06/diskcached_simple_disk_cacheing_for_ruby
+> Simple disk cache for things like Sinatra which is implemented much like Memcached in hopes that in some cases they're interchangeable.
+
+### [Documentation](http://rubyops.github.com/diskcached/doc/Diskcached.html) | [Coverage](http://rubyops.github.com/diskcached/coverage/index.html#_AllFiles) | [Benchmarks](https://github.com/rubyops/diskcached/wiki/Benchmark-Output)
+
+## Introduction
+
+I created Diskcached as a simple cacheing layer for things like html fragments and database calls. I thought about using [memcached](http://memcached.org/), but as the app I was working on was running on a single server, it seemed overkill. Additionally, I looked at using [rack-cache](http://rtomayko.github.com/rack-cache/), but I felt it was a bit more complex then I was looking for. So Diskcached was born (although it was origiionally released as "simple\_disk\_cache" -- for about 12 hours).
+
+* To the comment: "I'm not clear how memcached on a single server is overkill."
+>  1. In some cases -- e.g. Dreamhost shared hosting and Heroku (I believe) -- it is difficult, if not impossible to install memcached. This is for those situations.
+>  1. In all cases, disk space is cheaper than memory. For example, when I used [myhosting.com](http://myhosting.com), which charges $1 per 20G of disk storage and $1 per 512MB of memory. So in my case, I use Diskcached instead of memcached and my memory foot print is ~300MB. While at the moment, I could very easily handle running memcached without running out of memory, using disk based cacheing allows me to scale much further before having to upgrade my hosting package. Additionally, if you [check out my blogs performance metrics](https://github.com/jmervine/ditty/wiki/Performance), you'll see that Diskcached brought me from ~140ms render times, to ~1ms render times, allowing me to scale even further.
+
+* To the comment: "If you need memcache...then use it."
+>  * I totally agree!
+
+## Installation
+
+    :::shell
+    gem install diskcached
+
+Or with [Bundler](http://mervine.net/tag/bundler):
+
+    :::ruby
+    source :rubygems
+    gem 'diskcached'
+
+## Basic Usage
+
+### Block Style
+
+    :::ruby
+    require 'diskcached'
+    @diskcache = Diskcached.new
+
+    result = @diskcache.cache('expensive_code') do
+      # some expensive code
+    end
+
+    puts result
+
+The above will create the cache if it doesn't exist and cache the result of block and return it. If the cache exists and isn't expired, it will read from the cache and returnwhat's stored. This allows you to passively wrap code in a cache block and not worry about checking to see if it's valid or expired.
+
+Also worth noting, it will return `nil` if something goes wrong.
+
+### Memcached Style
+
+Using Diskcached like this should allow for a "drag and drop" replacement of Memcached, should you so decide.
+
+    :::ruby
+    require 'diskcached'
+    @diskcache = Diskcached.new
+
+    begin
+      result = @diskcache.get('expensive_code')
+    rescue # Diskcached::NotFound # prevents easy replacement, but is safer.
+      result = run_expensive_code
+      @diskcache.set('expensive_code', result)
+    end
+
+    puts result
+
+It's important to note that Diskcached is quite a bit simpler then Memcached and in some ways more forgiving. If Memcached compatability is really important, refer to Memcached docs as well as Diskcached docs when implementing your code.
+
+## Benchmarks
+
+### Comments
+
+Diskcached wasn't designed to be a faster solution, just a simpler
+one when compaired to Memcached. However, from these benchmarks,
+it holds up will and even should provide slightly faster reads.
+
+##### [Moved to 'Benchmark Output'](https://github.com/rubyops/diskcached/wiki/Benchmark-Output)
+
+## Sinatra Application 'httperf' results.
+
+On a development machine (Unicorn w/ 1 worker) I ran a series of [httperf](http://www.hpl.hp.com/research/linux/httperf/) tests to see how Diskcached ran in real world situations. You can [checkout the full output from multiple examples here](https://gist.github.com/3062334), but there's a taste...
+
+Using the endpoint [http://mervine.net/](http://mervine.net/) on my dev server and hitting it 100,000 times --
+
+### Code Example from Test
+
+    :::ruby
+     15   configure do
+            ...
+     44     $diskcache = Diskcached.new(File.join(settings.root, 'cache'))
+     45     $diskcache.flush # ensure caches are empty on startup
+     46   end
+          ...
+     58   before do
+            ...
+     61     @cache_key = cache_sha(request.path_info)
+     62   end
+          ...
+    231   get "/" do
+    232     begin
+    233       raise Diskcached::NotFound if authorized?
+    234       content = $diskcache.get(@cache_key)
+    235       logger.debug("reading index from cache") unless authorized?
+    236     rescue Diskcached::NotFound
+    237       logger.debug("storing index to cache") unless authorized?
+    238       content = haml(:index, :layout => choose_layout)
+    239       $diskcache.set(@cache_key, content) unless authorized?
+    240     end
+    241     content
+    242   end
+
+### Test Results
+
+    :::shell
+    httperf --client=0/1 --server=localhost --port=9001 --uri=/ --send-buffer=4096 --recv-buffer=16384 --num-conns=100000 --num-calls=1
+    httperf: warning: open file limit > FD_SETSIZE; limiting max. # of open files to FD_SETS
+
+    Maximum connect burst length: 1
+
+    Total: connections 100000 requests 100000 replies 100000 test-duration 744.646 s
+
+    Connection rate: 134.3 conn/s (7.4 ms/conn, <=1 concurrent connections)
+    Connection time [ms]: min 1.9 avg 7.4 max 398.8 median 4.5 stddev 10.5
+    Connection time [ms]: connect 0.1
+    Connection length [replies/conn]: 1.000
+
+    Request rate: 134.3 req/s (7.4 ms/req)
+    Request size [B]: 62.0
+
+    Reply rate [replies/s]: min 116.6 avg 134.3 max 147.2 stddev 6.1 (148 samples)
+    Reply time [ms]: response 6.9 transfer 0.5
+    Reply size [B]: header 216.0 content 105088.0 footer 0.0 (total 105304.0)
+    Reply status: 1xx=0 2xx=100000 3xx=0 4xx=0 5xx=0
+
+    CPU time [s]: user 287.88 system 115.60 (user 38.7% system 15.5% total 54.2%)
+    Net I/O: 13818.2 KB/s (113.2*10^6 bps)
+
+    Errors: total 0 client-timo 0 socket-timo 0 connrefused 0 connreset 0
+    Errors: fd-unavail 0 addrunavail 0 ftab-full 0 other 0
+

data/Rakefile

@@ -2,9 +2,27 @@
 
 require 'rubygems'
 require 'rspec/core/rake_task'
+require './lib/diskcached'
 RSpec::Core::RakeTask.new(:spec)
 task :default => :spec
 
+desc "generate and update gh-pages"
+task :pages do
+  system(" set -x; bundle exec rspec ") or abort
+  system(" set -x; bundle exec yardoc --protected ./lib/**/*.rb ") or abort
+  system(" set -x; rm -rf /tmp/doc /tmp/coverage ") or abort
+  system(" set -x; mv -v ./doc /tmp ") or abort
+  system(" set -x; mv -v ./coverage /tmp ") or abort
+  system(" set -x; git checkout gh-pages ") or abort
+  system(" set -x; rm -rf ./doc ./coverage ") or abort
+  system(" set -x; mv -v /tmp/doc . ") or abort
+  system(" set -x; mv -v /tmp/coverage . ") or abort
+  system(" set -x; git add . ") or abort 
+  system(" set -x; git commit --all -m 'updating doc and coverage' ") or abort
+  system(" set -x; git checkout master ") or abort
+  puts "don't forget to run: git push origin gh-pages"
+end
+
 
 task :benchmark do
   load './spec/benchmarks.rb'

data/lib/diskcached.rb

@@ -1,14 +1,14 @@
 # @author Joshua P. Mervine <joshua@mervine.net>
 class Diskcached
   # version for gem
-  VERSION = '1.1.0'
+  VERSION = '1.1.1'
 
   # disk location for cache store
   attr_reader :store
-  
+
   # cache timeout
   attr_reader :timeout
- 
+
   # time of last #garbage_collect
   attr_reader :gc_last
 
@@ -26,17 +26,25 @@ class Diskcached
   def initialize store="/tmp/cache", timeout=600, autogc=true
     @store   = store
     @timeout = timeout
-    if timeout.nil?
-      @gc_last, @gc_time = nil
-      @gc_auto = false
-    else
-      @gc_last = Time.now
-      @gc_auto = autogc
-      @gc_time = (timeout < 600 ? timeout : 600)
+
+    @gc_last, @gc_time = nil
+
+    # true or false, this will be ignored if @gc_last and @gc_time
+    # are nil
+    @gc_auto = autogc
+
+    unless timeout.nil?
+      send(:timeout=, timeout)
     end
+
     ensure_store_directory
   end
 
+  def timeout=(t)
+    @gc_last = Time.now
+    @gc_time = t
+  end
+
   # return true if cache with 'key' is expired
   def expired? key
     return false if timeout.nil?
@@ -52,14 +60,14 @@ class Diskcached
   # expire (delete) all caches in #store directory
   def flush
     Dir[ File.join( store, '*.cache' ) ].each do |file|
-      File.delete(file) 
+      File.delete(file)
     end
   end
 
   # flush expired caches if garbage collection
   # hasn't been run recently
-  def flush_expired 
-    if gc_last && gc_time && gc_last+gc_time <= Time.now 
+  def flush_expired
+    if gc_last && gc_time && gc_last+gc_time <= Time.now
       flush_expired!
     end
   end
@@ -67,9 +75,9 @@ class Diskcached
   # flash expired caches, ingoring when garbage
   # collection was last run
   def flush_expired!
-    Dir[ File.join( store, "*.cache" ) ].each do |f| 
+    Dir[ File.join( store, "*.cache" ) ].each do |f|
       if (File.mtime(f)+timeout) <= Time.now
-        File.delete(f) 
+        File.delete(f)
       end
     end
     @gc_last = Time.now
@@ -108,28 +116,29 @@ class Diskcached
   alias :replace :set    # for memcached compatability
 
   # get cache with 'key'
-  # - reads cache if it exists and isn't expired 
+  # - reads cache if it exists and isn't expired
   #   or raises Diskcache::NotFound
-  # - if 'key' is an Array returns only keys 
+  # - if 'key' is an Array returns only keys
   #   which exist and aren't expired, it raises
   #   Diskcache::NotFound if none are available
   def get key
-    begin
-      if key.is_a? Array
-        hash = {}
-        key.each do |k|
-          hash[k] = Marshal::load(read_cache_file(k)) unless expired?(k)
-        end
-        flush_expired if gc_auto
-        return hash unless hash.empty?
-      else
-        flush_expired if gc_auto
-        return Marshal::load(read_cache_file(key)) unless expired?(key)
+    if key.is_a? Array
+      ret = {}
+      key.each do |k|
+        ret[k] = Marshal::load(read_cache_file(k)) unless expired?(k)
       end
-      raise Diskcached::NotFound
-    rescue
-      raise Diskcached::NotFound
+
+      raise if ret.empty?
+      return ret
     end
+
+    raise if expired?(key)
+
+    return Marshal::load(read_cache_file(key))
+  rescue
+    raise Diskcached::NotFound
+  ensure
+    flush_expired if gc_auto
   end
 
   # returns path to cache file with 'key'
@@ -151,12 +160,12 @@ class Diskcached
   def read_cache_file key
     f = File.open( cache_file(key), "r" )
     f.flock(File::LOCK_SH)
-    out = f.read 
+    out = f.read
     f.close
     return out
   end
 
-  # returns mtime of cache file or nil if 
+  # returns mtime of cache file or nil if
   # file doesn't exist
   def read_cache_mtime key
     return nil unless File.exists?(cache_file(key))

metadata

@@ -1,62 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: diskcached
 version: !ruby/object:Gem::Version
-  version: 1.1.0
-  prerelease: 
+  version: 1.1.1
 platform: ruby
 authors:
 - Joshua Mervine
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-07-10 00:00:00.000000000 Z
+date: 2015-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rdoc
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: Simple disk cache for things like Sinatra which is implemented much like
@@ -75,26 +68,25 @@ files:
 - Rakefile
 homepage: http://diskcached.rubyops.net/
 licenses: []
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: 1.3.6
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 2.0.14
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Simple disk cache
 test_files: []