Coin

Memcached? We don't need no stinking Memcached. ¹

Well... you might depending upon your specific needs, but have a look at Coin before you reach for the sledgehammer.

Coin is an absurdly simple in memory object caching system written in Ruby.

Why Coin?

• No configuration required
• No added complexity to your stack
• Small footprint (under 200 lines)
• Simple API

Coin uses Distributed Ruby (DRb) to create a simple in memory caching server that addresses many of the same needs as Memcached and other similar solutions.

Quick Start

Installation

$ gem install coin

Basic Usage

require "coin"
Coin.write :foo, true
Coin.read :foo # => true

Next Steps

Examples of more advanced usage.

require "coin"

# read and/or assign a default value in a single atomic step
Coin.read(:bar) { true } # => true

# write data with an explicit expiration (in seconds)
# this example expires in 5 seconds (default is 300)
Coin.write :bar, true, 5
sleep 5
Coin.read :bar # => nil

# delete an entry
Coin.write :bar, true
Coin.delete :bar
Coin.read :bar # => nil

# read and delete in a single atomic step
Coin.write :bar, true
Coin.read_and_delete :bar # => true
Coin.read :bar # => nil

# read and update in a single atomic step
Coin.write :bar, true
Coin.read_and_update :bar do |value|
  !value
end
Coin.read :bar # => false

# determine how many items are in the cache
10.times do |i|
  Coin.write "key#{i}", true
end
Coin.length # => 10

# clear the cache
Coin.clear
Coin.length # => 0

Deep Cuts

Coin automatically starts a DRb server that hosts the Coin::Vault. You can take control of this behavior if needed.

require "coin"

# configure the port that the DRb server runs on (default is 8955)
Coin.port = 8080

# configure the URI that the DRb server runs on (defaults to druby://localhost:PORT)
Coin.uri = "druby://10.0.0.100:8080"

# access the DRb server exposing Coin::Vault
Coin.server # => #<Coin::Vault:0x007fe182852e18>

# determine if the server is running
Coin.server_running? # => true

# determine the pid of the server process
Coin.pid # => "63299"

# stop the server
Coin.stop_server # => true

# start the server
Coin.start_server # => true

# start the server forcing a restart if the server is already running
Coin.start_server true # => true

Coin also supports configuring a remote server. Allowing a single Coin server to service multiple machines.

Coin.remote_uri = "druby://192.168.0.12:8808"

Want interoperability with other languages? Check out CoinRack which provides a REST API on top of Coin.

Best Practices

All objects stored with Coin must be able to marshal.

Its generally a good idea to store only the most basic objects. For example:

• Boolean
• String
• Number

Its possible to store more complex objects such as:

• Array
• Hash

Just be sure to limit the keys & values to basic types.

Run the Tests

$ gem install coin
$ gem unpack coin
$ cd coin-VERSION
$ bundle
$ mt

Notes

Coin's default behavior launches a single DRb server that provides shared access across all processes on a single machine. You need to configure Coin.remote_uri if you want Coin to connect to a DRb server on another machine.

Cultural References

1. "Badges? We don't need no stinking badges!" - from Mel Brooks' film Blazing Saddles