Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/hopsoft/coin

An absurdly simple DRb based in-memory cache
https://github.com/hopsoft/coin

cache drb ruby

Last synced: 2 months ago
JSON representation

An absurdly simple DRb based in-memory cache

Awesome Lists containing this project

README 

        
[![Lines of Code](http://img.shields.io/badge/lines_of_code-186-brightgreen.svg?style=flat)](http://blog.codinghorror.com/the-best-code-is-no-code-at-all/)

[![Maintainability](https://api.codeclimate.com/v1/badges/ef8ed3f1eca8c3e5509f/maintainability)](https://codeclimate.com/github/hopsoft/coin/maintainability)

[![Build Status](http://img.shields.io/travis/hopsoft/coin.svg?style=flat)](https://travis-ci.org/hopsoft/coin)

[![Coverage Status](https://img.shields.io/coveralls/hopsoft/coin.svg?style=flat)](https://coveralls.io/r/hopsoft/coin?branch=master)

[![Downloads](http://img.shields.io/gem/dt/coin.svg?style=flat)](http://rubygems.org/gems/coin)



# Coin



## Memcached? We don't need no stinking Memcached. 1



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)](http://pragprog.com/book/sidruby/the-druby-book)

to create a simple in memory caching server that addresses many of the same needs as Memcached

and other similar solutions.



## Quick Start



Installation



```bash

$ gem install coin

```



Basic Usage



```ruby

require "coin"

Coin.write :foo, true

Coin.read :foo # => true

```



## Next Steps



Examples of more advanced usage.



```ruby

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.



```ruby

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 # => #



# 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.



```ruby

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

```



Want interoperability with other languages? Check out

[CoinRack](https://github.com/hopsoft/coin_rack) 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



```bash

$ 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.



![Coin Diagram](https://raw.github.com/hopsoft/coin/gh-pages/assets/images/coin.png)



## Cultural References



1. "Badges? We don't need no stinking badges!" - from Mel Brooks' film [Blazing Saddles](http://en.wikipedia.org/wiki/Stinking_badges)