teej-alchemy 1.0.1

data/License.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2008 TJ Murphy
+
+## MIT LICENSE ##
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,62 @@
+= Name
+
+Alchemy v. 1.0.1 - a simple, light-weight list caching server
+
+= Description
+
+Alchemy is fast, simple, and distributed list caching server intended to
+relieve load on relational
+databases.  It uses the same scalable, non-blocking architecture that
+Starling (http://github.com/defunkt/starling) is built on. It also speaks
+the Memcache protocol, so any language that has a memcached client can
+operate with Alchemy.
+
+= Installation
+
+This project is hosted at GitHub:
+
+http://github.com/teej/alchemy/tree/master
+
+Alchemy can be installed through GitHub gems:
+
+  gem sources -a http://gems.github.com
+  sudo gem install teej-alchemy
+
+= Quick Start Usage
+
+In a console window start the Alchemy server.  By default
+it runs verbosely in the foreground, listening on 127.0.0.1:22122
+and stores its files under /tmp/alchemy.  To run it as a daemon:
+
+  alchemy -d
+
+In a new console test the put and get of items in a list:
+
+  irb
+  >> require 'alchemy'
+  => true
+  >> alchemy = Alchemy.new('127.0.0.1:22122')
+  => #<Alchemy:0x203f384 ... >
+  >> alchemy.set("my_array", "chunky")
+  => nil
+  >> alchemy.set("my_array", "bacon")
+  => nil
+  >> alchemy.get("my_array")
+  => ["chunky", "bacon"]
+
+= Authors
+
+* TJ Murphy
+
+= Starling Contributors
+
+* Blaine Cook
+* Chris Wanstrath
+* AnotherBritt
+* Glenn Rempe
+* Abdul-Rahman Advany
+
+= Copyright
+
+Alchemy - a simple, light-weight list caching server.
+Copyright 2008 TJ Murphy

data/alchemy.gemspec

@@ -0,0 +1,30 @@
+Gem::Specification.new do |s|
+  s.name     = "alchemy"
+  s.version  = "1.0.1"
+  s.date     = "2008-10-17"
+  s.summary  = "A simple, light-weight list caching server"
+  s.email    = "teej.murphy@gmail.com"
+  s.homepage = "http://github.com/teej/alchemy"
+  s.description = "Alchemy is fast, simple, and distributed list caching server intended to relieve load on relational databases,"
+  s.has_rdoc = true
+  s.authors  = ["TJ Murphy"]
+  s.files    = ["License.txt", 
+		"README.rdoc",
+		"alchemy.gemspec",
+		"init.rb",
+		"bin/alchemy",
+		"lib/alchemy.rb",
+		"lib/alchemy/handler.rb",
+    "lib/alchemy/phylactery.rb",
+    "lib/alchemy/runner.rb",
+    "lib/alchemy/server.rb",
+    "lib/alchemy/alchemized_by.rb",
+    "lib/alchemy/uses_alchemy.rb"]
+  s.test_files = []
+  s.executables = ["alchemy"]
+  s.rdoc_options = ["--main", "README.rdoc"]
+  s.extra_rdoc_files = ["README.rdoc"]
+  s.add_dependency("json", ["> 1.0.0"])
+  s.add_dependency("memcached", [">= 0.11"])
+  s.add_dependency("eventmachine", [">= 0.12.2"])
+end

data/bin/alchemy

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'alchemy/runner'
+AlchemyServer::Runner.run

data/init.rb

@@ -0,0 +1,3 @@
+['uses_alchemy', 'alchemized_by'].each do |req|
+	require File.join(File.dirname(__FILE__), "lib/alchemy/#{req}")
+end

data/lib/alchemy/alchemized_by.rb

@@ -0,0 +1,25 @@
+module AlchemizedBy
+  
+  def alchemized_by(association_id, opts={})
+	
+  	opts[:with] ||= "#{association_id}_id"
+  	opts[:with] = opts[:with].to_a
+  	opts[:on] ||= :id
+	
+  	opts[:with].each do |method|
+		
+  		alchemy_namespace = "#{self.name.underscore.pluralize.downcase}_#{method}"
+  		alchemy_listname = "#{method}_list_name"
+		
+  		define_method(alchemy_listname) do
+  			"#{association_id.to_s.camelize}|#{send(method)}|#{alchemy_namespace}"
+  		end
+		
+  		define_method("alchemize_#{method}") do
+  			ALCHEMY.set(send(alchemy_listname), self.send(opts[:on]))
+  		end
+		
+  	end
+  end
+  
+end

data/lib/alchemy/handler.rb

@@ -0,0 +1,218 @@
+module AlchemyServer
+
+  ##
+  # This is an internal class that's used by Alchemy::Server to handle the
+  # Memcached protocol and act as an interface between the Server and the
+  # Recipes.
+  
+  class Handler < EventMachine::Connection
+
+    ACCEPTED_COMMANDS = ["set", "add", "replace", "append", "prepend", "get", "delete", "flush_all", "version", "verbosity", "quit", "stats"].freeze
+    
+    # ERRORs
+    ERR_UNKNOWN_COMMAND   = "ERROR\r\n".freeze
+    ERR_BAD_CLIENT_FORMAT = "CLIENT_ERROR bad command line format\r\n".freeze
+    ERR_SERVER_ISSUE      = "SERVER_ERROR %s\r\n"
+
+    # GET
+    GET_COMMAND         = /\Aget (.{1,250})\s*\r\n/m
+    GET_RESPONSE        = "VALUE %s %s %s\r\n%s\r\nEND\r\n".freeze
+    GET_RESPONSE_EMPTY  = "END\r\n".freeze
+
+    # SET
+    SET_COMMAND           = /\A(\w+) (.{1,250}) ([0-9]+) ([0-9]+) ([0-9]+)\r\n/m
+    SET_RESPONSE_SUCCESS  = "STORED\r\n".freeze
+    SET_RESPONSE_FAILURE  = "NOT STORED\r\n".freeze
+    SET_CLIENT_DATA_ERROR = "CLIENT_ERROR bad data chunk\r\nERROR\r\n".freeze
+    
+    # DELETE
+    DELETE_COMMAND            = /\Adelete (.{1,250})\s?([0-9]*)\r\n/m
+    DELETE_RESPONSE_SUCCESS   = "DELETED\r\n".freeze
+    DELETE_RESPONSE_FAILURE   = "NOT_FOUND\r\n".freeze
+    
+    # FLUSH
+    FLUSH_COMMAND   = /\Aflush_all\s?([0-9]*)\r\n/m
+    FLUSH_RESPONSE  = "OK\r\n".freeze
+    
+    # VERSION
+    VERSION_COMMAND   = /\Aversion\r\n/m
+    VERSION_RESPONSE  = "VERSION #{VERSION}\r\n".freeze
+    
+    # VERBOSITY
+    VERBOSITY_COMMAND   = /\Averbosity\r\n/m
+    VERBOSITY_RESPONSE  = "OK\r\n".freeze
+    
+    # QUIT
+    QUIT_COMMAND   = /\Aquit\r\n/m
+    
+    # STAT Response
+    STATS_COMMAND   = /\Astats\r\n/m
+    STATS_RESPONSE  = "STAT pid %d
+STAT uptime %d
+STAT time %d
+STAT version %s
+STAT rusage_user %0.6f
+STAT rusage_system %0.6f
+STAT curr_items %d
+STAT total_items %d
+STAT bytes %d
+STAT curr_connections %d
+STAT total_connections %d
+STAT cmd_get %d
+STAT cmd_set %d
+STAT get_hits %d
+STAT get_misses %d
+STAT bytes_read %d
+STAT bytes_written %d
+STAT limit_maxbytes %d
+%sEND\r\n".freeze
+    LIST_STATS_RESPONSE = "STAT list_%s_items %d
+STAT list_%s_total_items %d
+STAT list_%s_logsize %d
+STAT list_%s_expired_items %d\n".freeze
+
+    ##
+    # Creates a new handler for the MemCache protocol that communicates with a
+    # given client.
+
+    def initialize(options = {})
+      @opts = options
+    end
+
+    ##
+    # Process incoming commands from the attached client.
+
+    def post_init
+      @server = @opts[:server]
+      @expiry_stats = Hash.new(0)
+      @expected_length = nil
+      @server.stats[:total_connections] += 1
+      set_comm_inactivity_timeout @opts[:timeout]
+      @list_collection = @opts[:list]
+    end
+    
+    def receive_data(incoming)
+      data = incoming
+      
+      ## Reject request if command isn't recognized
+      if !ACCEPTED_COMMANDS.include?(data.split(" ").first)
+        response = respond ERR_UNKNOWN_COMMAND
+      elsif request_line = data.slice!(/.*?\r\n/m)
+        response = process(request_line, data)
+      else
+        response = respond ERR_BAD_CLIENT_FORMAT
+      end
+      
+      if response
+        send_data response
+      end
+    end
+
+    def process(request, data)
+      case request
+        when SET_COMMAND
+          set($1, $2, $3, $4, $5.to_i, data)
+        when GET_COMMAND
+          get($1)
+        when STATS_COMMAND
+          stats
+        when DELETE_COMMAND
+          delete($1)
+        when FLUSH_COMMAND
+          flush_all
+        when VERSION_COMMAND
+          respond VERSION_RESPONSE
+        when VERBOSITY_COMMAND
+          respond VERBOSITY_RESPONSE
+        when QUIT_COMMAND
+          close_connection
+          nil
+        else
+          logger.warn "Bad Format: #{data}."
+          respond ERR_BAD_CLIENT_FORMAT
+      end
+      rescue => e
+        logger.error "Error handling request: #{e}."
+        logger.debug e.backtrace.join("\n")
+        respond ERR_SERVER_ISSUE, e.to_s
+    end
+
+  private
+    def respond(str, *args)
+      response = sprintf(str, *args)
+      @server.stats[:bytes_written] += response.length
+      response
+    end
+    
+    def set(command, key, flags, expiry, expected_data_size, data)
+      data = data.to_s
+      respond SET_RESPONSE_FAILURE unless (data.size == expected_data_size + 2)
+      data = data[0...expected_data_size]
+      
+      if @list_collection.send(command.to_sym, key, data)
+        respond SET_RESPONSE_SUCCESS
+      else
+        respond SET_RESPONSE_FAILURE
+      end
+    end
+    
+    def get(key)
+      key = key.strip
+      if data = @list_collection.get(key)
+        respond GET_RESPONSE, key, 0, data.size, data
+      else
+        respond GET_RESPONSE_EMPTY
+      end
+    end
+      
+    def delete(key)
+      if @list_collection.delete(key)
+        respond DELETE_RESPONSE_SUCCESS
+      else
+        respond DELETE_RESPONSE_FAILURE
+      end
+    end
+    
+    def flush_all
+      @list_collection.flush_all
+      respond FLUSH_RESPONSE
+    end
+    
+    def stats
+      respond STATS_RESPONSE, 
+        Process.pid, # pid
+        Time.now - @server.stats(:start_time), # uptime
+        Time.now.to_i, # time
+        AlchemyServer::VERSION, # version
+        Process.times.utime, # rusage_user
+        Process.times.stime, # rusage_system
+        @list_collection.stats(:current_size), # curr_items
+        @list_collection.stats(:total_items), # total_items
+        @list_collection.stats(:current_bytes), # bytes
+        @server.stats(:connections), # curr_connections
+        @server.stats(:total_connections), # total_connections
+        @server.stats(:get_requests), # get count
+        @server.stats(:set_requests), # set count
+        @list_collection.stats(:get_hits),
+        @list_collection.stats(:get_misses),
+        @server.stats(:bytes_read), # total bytes read
+        @server.stats(:bytes_written), # total bytes written
+        0, # limit_maxbytes
+        list_stats
+    end
+  
+    def list_stats
+      @list_collection.lists.inject("") do |m,(k,v)|
+        m + sprintf(LIST_STATS_RESPONSE,
+                      k, v.length,
+                      k, v.total_items,
+                      k, v.logsize,
+                      k, @expiry_stats[k])
+      end
+    end
+
+    def logger
+      @server.logger
+    end
+  end
+end

data/lib/alchemy/phylactery.rb

@@ -0,0 +1,146 @@
+require 'thread'
+require 'json'
+
+module AlchemyServer
+  
+  class Phylactery
+    
+    def initialize
+      @shutdown_mutex = Mutex.new
+      @lists = {}
+      @list_init_mutexes = {}
+      @stats = Hash.new(0)
+    end
+    
+    def set(key, data)
+      list = lists(key)
+      return false unless list
+      
+      value = value_for_data(data)
+      list.push(value)
+      
+      return true
+    end
+    
+    
+    def add(key, data)
+      list = lists(key)
+      return false unless list
+      
+      value = value_for_data(data)
+      return false if list.include?(value)
+      list.push(value)
+      
+      return true
+    end
+    
+    ## Special.  Expects data to be a JSON array
+    def replace(key, data)
+      list = lists(key)
+      return false unless list
+      value = JSON.parse(data)
+      return false unless value.is_a? Array
+      list.replace(value)
+      
+      return true
+    end
+    
+    alias :append :set
+    
+    def prepend(key, data)
+      list = lists(key)
+      return false unless list
+      
+      value = value_for_data(data)
+      list.unshift(value)
+      
+      return true
+    end
+    
+    ## CAS command not supported
+    
+    def get(key)
+      list = lists(key).to_a
+      return false if list.empty?
+      return list.to_json
+    end
+    
+    def gets(keys)
+      all_lists = {}
+      keys.each { |key| all_lists[key] = lists(key).to_a }
+      return all_lists.to_json
+    end
+    
+    def delete(key)
+    	@lists.delete(key)
+    end
+    
+    def flush_all
+      @lists = {}
+      @list_init_mutexes = {}
+    end
+    
+    ##
+    # Returns all active lists. 
+
+    def lists(key=nil)
+      return nil if @shutdown_mutex.locked?
+
+      return @lists if key.nil?
+      # First try to return the list named 'key' if it's available.
+      return @lists[key] if @lists[key]
+      
+      @list_init_mutexes[key] ||= Mutex.new
+      
+      if @list_init_mutexes[key].locked?
+        return nil
+      else
+        @list_init_mutexes[key].lock
+        if @lists[key].nil?
+          @lists[key] = []
+        end
+        @list_init_mutexes[key].unlock
+      end
+
+      return @lists[key]
+    end
+
+    ##
+    # Returns statistic +stat_name+ for the Recipes.
+    #
+    # Valid statistics are:
+    #
+    #   [:get_misses]    Total number of get requests with empty responses
+    #   [:get_hits]      Total number of get requests that returned data
+    #   [:current_bytes] Current size in bytes of items in the lists
+    #   [:current_size]  Current number of items across all lists
+    #   [:total_items]   Total number of items stored in lists.
+
+    def stats(stat_name)
+      case stat_name
+      when nil; @stats
+      when :current_size; current_size
+      else; @stats[stat_name]
+      end
+    end
+
+    ##
+    # Safely close all lists.
+
+    def close
+      @shutdown_mutex.lock
+    end
+
+    private
+
+    def current_size #:nodoc:
+      @lists.inject(0) { |m, (k,v)| m + v.length }
+    end
+    
+    def value_for_data(data)
+      # if the data is an integer, save it as such.  otherwise, save as a string
+      (data.to_i.to_s == data) ? data.to_i : data
+    end
+    
+  end
+end

data/lib/alchemy/runner.rb

@@ -0,0 +1,256 @@
+require File.join(File.dirname(__FILE__), 'server')
+require 'optparse'
+puts "Running with Alchemy"
+
+
+module AlchemyServer
+  class Runner
+
+    attr_accessor :options
+    private :options, :options=
+
+    def self.run
+      new
+    end
+   
+    def initialize
+      parse_options
+
+      @process = ProcessHelper.new(options[:log_file], options[:pid_file], options[:user], options[:group])
+
+      pid = @process.running?
+      if pid
+        STDERR.puts "There is already a alchemy process running (pid #{pid}), exiting."
+        exit(1)
+      elsif pid.nil?
+        STDERR.puts "Cleaning up stale pidfile at #{options[:pid_file]}."
+      end
+
+      start
+    end
+
+    def parse_options
+      self.options = { :host => '127.0.0.1',
+                       :port => 22122,
+                       :path => File.join(%w( / var spool alchemy )),
+                       :log_level => 0,
+                       :daemonize => false,
+                       :pid_file => File.join(%w( / var run alchemy.pid )) }
+
+      OptionParser.new do |opts|
+        opts.summary_width = 25
+
+        opts.banner = "alchemy (#{AlchemyServer::VERSION})\n\n",
+                      "usage: alchemy [-v] [-q path] [-h host] [-p port]\n",
+                      "                [-d [-P pidfile]] [-u user] [-g group] [-l log]\n",
+                      "       alchemy --help\n",
+                      "       alchemy --version\n"
+
+        opts.separator ""
+        opts.separator "Configuration:"
+        opts.on("-q", "--list_path PATH",
+                :REQUIRED,
+                "Path to store alchemy list logs", "(default: #{options[:path]})") do |list_path|
+          options[:path] = list_path
+        end
+
+        opts.separator ""; opts.separator "Network:"
+
+        opts.on("-hHOST", "--host HOST", "Interface on which to listen (default: #{options[:host]})") do |host|
+          options[:host] = host
+        end
+
+        opts.on("-pHOST", "--port PORT", Integer, "TCP port on which to listen (default: #{options[:port]})") do |port|
+          options[:port] = port
+        end
+
+        opts.separator ""; opts.separator "Process:"
+
+        opts.on("-d", "Run as a daemon.") do
+          options[:daemonize] = true
+        end
+
+        opts.on("-PFILE", "--pid FILE", "save PID in FILE when using -d option.", "(default: #{options[:pid_file]})") do |pid_file|
+          options[:pid_file] = pid_file
+        end
+
+        opts.on("-u", "--user USER", Integer, "User to run as") do |user|
+          options[:user] = user
+        end
+
+        opts.on("-gGROUP", "--group GROUP", "Group to run as") do |group|
+          options[:group] = group
+        end
+
+        opts.separator ""; opts.separator "Logging:"
+
+        opts.on("-l", "--log [FILE]", "Path to print debugging information.") do |log_path|
+          options[:log] = log_path
+        end
+
+        opts.on("-v", "Increase logging verbosity.") do
+          options[:log_level] += 1
+        end
+
+        opts.separator ""; opts.separator "Miscellaneous:"
+
+        opts.on_tail("-?", "--help", "Display this usage information.") do
+          puts "#{opts}\n"
+          exit
+        end
+
+        opts.on_tail("-V", "--version", "Print version number and exit.") do
+          puts "alchemy #{AlchemyServer::VERSION}\n\n"
+          exit
+        end
+      end.parse!
+    end
+
+    def start
+      drop_privileges
+
+      @process.daemonize if options[:daemonize]
+
+      setup_signal_traps
+      @process.write_pid_file
+
+      STDOUT.puts "Starting at #{options[:host]}:#{options[:port]}."
+      @server = AlchemyServer::Base.new(options)
+      @server.run
+
+      @process.remove_pid_file
+    end
+
+    def drop_privileges
+      Process.euid = options[:user] if options[:user]
+      Process.egid = options[:group] if options[:group]
+    end
+
+    def shutdown
+      begin
+        STDOUT.puts "Shutting down."
+        @server.logger.info "Shutting down."
+        @server.stop
+      rescue Object => e
+        STDERR.puts "There was an error shutting down: #{e}"
+        exit(70)
+      end
+    end
+
+    def setup_signal_traps
+      Signal.trap("INT") { shutdown }
+      Signal.trap("TERM") { shutdown }
+    end
+  end
+
+  class ProcessHelper
+
+    def initialize(log_file = nil, pid_file = nil, user = nil, group = nil)
+      @log_file = log_file
+      @pid_file = pid_file
+      @user = user
+      @group = group
+    end
+
+    def safefork
+      begin
+        if pid = fork
+          return pid
+        end
+      rescue Errno::EWOULDBLOCK
+        sleep 5
+        retry
+      end
+    end
+
+    def daemonize
+      sess_id = detach_from_terminal
+      exit if pid = safefork
+
+      Dir.chdir("/")
+      File.umask 0000
+
+      close_io_handles
+      redirect_io
+
+      return sess_id
+    end
+
+    def detach_from_terminal
+      srand
+      safefork and exit
+
+      unless sess_id = Process.setsid
+        raise "Couldn't detache from controlling terminal."
+      end
+
+      trap 'SIGHUP', 'IGNORE'
+
+      sess_id
+    end
+
+    def close_io_handles
+      ObjectSpace.each_object(IO) do |io|
+        unless [STDIN, STDOUT, STDERR].include?(io)
+          begin
+            io.close unless io.closed?
+          rescue Exception
+          end
+        end
+      end
+    end
+    
+    def redirect_io
+      begin; STDIN.reopen('/dev/null'); rescue Exception; end
+
+      if @log_file
+        begin
+          STDOUT.reopen(@log_file, "a")
+          STDOUT.sync = true
+        rescue Exception
+          begin; STDOUT.reopen('/dev/null'); rescue Exception; end 
+        end
+      else
+        begin; STDOUT.reopen('/dev/null'); rescue Exception; end
+      end
+
+      begin; STDERR.reopen(STDOUT); rescue Exception; end
+      STDERR.sync = true
+    end
+
+    def rescue_exception
+      begin
+        yield
+      rescue Exception
+      end
+    end
+
+    def write_pid_file
+      return unless @pid_file
+      File.open(@pid_file, "w") { |f| f.write(Process.pid) }
+      File.chmod(0644, @pid_file)
+    end
+
+    def remove_pid_file
+      return unless @pid_file
+      File.unlink(@pid_file) if File.exists?(@pid_file)
+    end
+
+    def running?
+      return false unless @pid_file
+
+      pid = File.read(@pid_file).chomp.to_i rescue nil
+      pid = nil if pid == 0
+      return false unless pid
+
+      begin
+        Process.kill(0, pid)
+        return pid
+      rescue Errno::ESRCH
+        return nil
+      rescue Errno::EPERM
+        return pid
+      end
+    end
+  end
+end

data/lib/alchemy/server.rb

@@ -0,0 +1,99 @@
+require 'socket'
+require 'logger'
+require 'rubygems'
+require 'eventmachine'
+
+here = File.dirname(__FILE__)
+
+require File.join(here, 'phylactery')
+require File.join(here, 'handler')
+
+module AlchemyServer
+
+  VERSION = "1.0.1"
+
+  class Base
+    attr_reader :logger
+
+    DEFAULT_HOST    = '127.0.0.1'
+    DEFAULT_PORT    = 22122
+    DEFAULT_PATH    = "/tmp/alchemy/"
+    DEFAULT_TIMEOUT = 60
+
+    ##
+    # Initialize a new Alchemy server and immediately start processing
+    # requests.
+    #
+    # +opts+ is an optional hash, whose valid options are:
+    #
+    #   [:host]     Host on which to listen (default is 127.0.0.1).
+    #   [:port]     Port on which to listen (default is 22122).
+    #   [:path]     Path to Alchemy list logs. Default is /tmp/alchemy/
+    #   [:timeout]  Time in seconds to wait before closing connections.
+    #   [:logger]   A Logger object, an IO handle, or a path to the log.
+    #   [:loglevel] Logger verbosity. Default is Logger::ERROR.
+    #
+    # Other options are ignored.
+    
+    def self.start(opts = {})
+      server = self.new(opts)
+      server.run
+    end
+
+    ##
+    # Initialize a new Alchemy server, but do not accept connections or
+    # process requests.
+    #
+    # +opts+ is as for +start+
+    
+    def initialize(opts = {})
+      @opts = { 
+        :host    => DEFAULT_HOST,
+        :port    => DEFAULT_PORT,
+        :path    => DEFAULT_PATH,
+        :timeout => DEFAULT_TIMEOUT,
+        :server  => self
+      }.merge(opts)
+
+      @stats = Hash.new(0)
+    end
+
+    ##
+    # Start listening and processing requests.
+
+    def run
+      @stats[:start_time] = Time.now
+
+      @logger = case @opts[:logger]
+      when IO, String; Logger.new(@opts[:logger])
+      when Logger; @opts[:logger]
+      else; Logger.new(STDERR)
+      end
+
+      @opts[:list] = Phylactery.new
+      @logger.level = @opts[:log_level] || Logger::ERROR
+
+      EventMachine.run do
+        EventMachine.epoll
+        EventMachine.set_descriptor_table_size(4096)
+        EventMachine.start_server(@opts[:host], @opts[:port], Handler, @opts)
+      end
+    end
+
+    ##
+    # Stop accepting new connections and shutdown gracefully.
+
+    def stop
+      @opts[:list].close
+      EventMachine.stop_event_loop
+    end
+
+    def stats(stat = nil) #:nodoc:
+      case stat
+      when nil; @stats
+      when :connections; 1
+      else; @stats[stat]
+      end
+    end
+  end
+end

data/lib/alchemy/uses_alchemy.rb

@@ -0,0 +1,31 @@
+module UsesAlchemy
+	
+	def uses_alchemy(association_id, opts={})
+		opts[:on]	||= "#{self.name.downcase}_id"
+		opts[:name]	||= association_id
+		opts[:store] ||= :id
+		
+		klass = association_id.to_s.singularize.camelize.constantize
+		opts[:proc] ||= Proc.new { |list| list.map{ |aid| klass.find(aid) } }
+		
+		alchemy_namespace = "#{association_id}_#{opts[:on]}"
+		alchemy_listname ="#{alchemy_namespace}_list_name"
+		
+		define_method(alchemy_listname) do
+			"#{self.class}|#{id}|#{alchemy_namespace}"
+		end
+		
+		define_method(opts[:name]) do |*reload|
+			list = ALCHEMY.get(send(alchemy_listname)) if !reload.first
+			
+			if reload.first || list.nil?
+			  refreshed_list = klass.find(:all, :select=>"#{opts[:store]}, #{opts[:on]}", :conditions=>["#{opts[:on]} = ?", self.id])
+			  refreshed_list = refreshed_list.map(&opts[:store])
+			  ALCHEMY.replace(send(alchemy_listname), refreshed_list.to_json)
+			  list = refreshed_list
+			end
+			opts[:proc].call(list)
+		end
+	end
+	
+end

data/lib/alchemy.rb

@@ -0,0 +1,54 @@
+require 'memcached'
+require 'json'
+
+class Alchemy < Memcached
+  ## SETTERS
+  def set(key, value, timeout=0)
+    check_return_code(
+      Lib.memcached_set(@struct, key, value.to_s, timeout, FLAGS)
+    )
+  end
+  
+  def add(key, value, timeout=0)
+    check_return_code(
+      Lib.memcached_add(@struct, key, value.to_s, timeout, FLAGS)
+    )
+  end
+  
+  def replace(key, value, timeout=0)
+    check_return_code(
+      Lib.memcached_replace(@struct, key, value.to_a.to_json, timeout, FLAGS)
+    )
+  end
+  
+  ## GETTER
+  def get(keys)#, marshal=true)
+    if keys.is_a? Array
+      # Multi get
+      keys.map! { |key| key }
+      hash = {}
+      
+      ret = Lib.memcached_mget(@struct, keys);
+      check_return_code(ret)
+      
+      keys.size.times do 
+        value, key, flags, ret = Lib.memcached_fetch_rvalue(@struct)
+        break if ret == Lib::MEMCACHED_END
+        check_return_code(ret)
+        hash[key] = JSON.parse(value)
+      end
+      hash
+    else
+      # Single get
+      value, flags, ret = Lib.memcached_get_rvalue(@struct, keys)
+      #check_return_code(ret)
+      unless value.empty?
+        value = JSON.parse(value)
+      else
+        value = nil
+      end
+      value
+    end    
+  end
+  
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification 
+name: teej-alchemy
+version: !ruby/object:Gem::Version 
+  version: 1.0.1
+platform: ruby
+authors: 
+- TJ Murphy
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-10-17 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: memcached
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0.11"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: eventmachine
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.12.2
+    version: 
+description: Alchemy is fast, simple, and distributed list caching server intended to relieve load on relational databases,
+email: teej.murphy@gmail.com
+executables: 
+- alchemy
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- License.txt
+- README.rdoc
+- alchemy.gemspec
+- init.rb
+- bin/alchemy
+- lib/alchemy.rb
+- lib/alchemy/handler.rb
+- lib/alchemy/phylactery.rb
+- lib/alchemy/runner.rb
+- lib/alchemy/server.rb
+- lib/alchemy/alchemized_by.rb
+- lib/alchemy/uses_alchemy.rb
+has_rdoc: true
+homepage: http://github.com/teej/alchemy
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A simple, light-weight list caching server
+test_files: []
+