about

CORNERSTORE is an easy-to-use, in-memory cache with items which can expire. It can safely be shared across threads.

is a friendly key-value store for perishable items. Like corner stores in real life, this one is fast and convenient. It is intended for read-heavy workloads. All key/value pairs can be given an optional expiry time.

A CornerStore instance is thread-safe. It divides its data across 128 shards.

usage

CORNERSTORE is a library. It does not have a command-line interface or listen to a socket, such as what you might expect from memcached or Redis.

Start by importing CornerStore then creating and instance with the new() method. For the convenience of, it can be useful to also bring some types from std::time in local scope, as well as the std::error::Error trait.

use cornerstore::CornerStore;
use std::error::Error;
use std::time::{Duration, Instant};

// ...

fn main() -> Result<(), Box<dyn Error + '_>> {
    let mut store = CornerStore::new();

    // ...

    Ok(())
}

Some examples of the API:

• Storing an item that does not expire:

  let key = b"greeting";
  let value = b"hello";
  let expiry = None;
  store.set(key, expected_value, expiry)?;
  

• Storing an item that expires in one minute:

  let key = b"greeting";
  let value = b"hello from the future";
  let expiry = Some(Instant::now() + Duration::new(60, 0))
  store.set(key, expected_value, expiry)?;
  

• Retrieving an item:

  let key   = b"greeting";
  if Some(value) = store.get(key)? {
      // warning - prints raw bytes
      println!("{:?}", value);
  };
  

• Retrieving an item without checking the expiry date:

  let key   = b"greeting";
  if Some(value) = store.get_unchecked(key)? {
      // warning - prints raw bytes
      println!("{:?}", value);
  };
  

• Remove any expired perishable items from the store:

  store.evict()?;
  

cargo features

• safe-input
  If you know that your store will not be subjected to DDoS attacks, you can increase its performance by enabling safe-input. safe-input uses the fxcrate for hashing, which is faster than Rust's default.

goals

To act as a library for many client language implementations.

help wanted

• Is it possible to avoid returning Result<Option<K, V>> when returning a value? Unwrapping twice is slightly icky.
• how to benchmark this thing? I've experimented a little bit with jonhoo's bustle crate, but it's hard to coerce [u8] streams to f64.

legal

Sorry about the legalese. It's unfortunate, but important.

authorship and copyright

Original components of CORNERSTORE have been written by Tim McNamara (@timClicks). Copyright these contributions have been assigned to Fiorenza Limited (NZBN 9429042165200).

CORNERSTORE source and binary distributions are released under the Apache 2 License. See the LICENCE file for your rights and obligations under this licence.

trade mark

CORNERSTORE is an unregistered trade mark of Fiorenza Limited (NZBN 9429042165200).

consumer projection

If you are using CORNERSTORE for your own use, you are entitled to mandatory rights under the Consumer Guarantees Act. Please bear in mind that you are getting software for free that you have randomly downloaded from the Internet.