Struct rsoffkv::client::Client

pub struct Client { /* fields omitted */ }

Methods

impl Client

pub fn new(url: &str, prefix: &str) -> Result<Self, OffkvError>

Creates a new client given url, where the service is located, and prefix all keys should start with.

Arguments:

• url - Address, where the service is located. Must be of form <service_name>://<host>:<port> where <service_name> is one of {zk, consul, etcd}.
• prefix - An additional prefix, all used keys start with.

Example:

use rsoffkv::client::Client;
let zk_client = Client::new("zk://localhost:2181", "/test_prefix").unwrap();
let consul_client = Client::new("consul://localhost:8500", "/test_prefix").unwrap();
let etcd_client = Client::new("etcd://localhost:2379", "/test_prefix").unwrap();

pub fn create(
    &self,
    key: &str,
    value: &str,
    leased: bool
) -> Result<i64, OffkvError>

Creates new key. The parent key must exist.

Arguments:

• key - key to create
• value - initial value
• leased - if true the key will be removed on client's disconnect

Returns:

• inital version (i64)

Example:

let client = Client::new("consul://localhost:8500", "/test_prefix").unwrap();
let initial_version = client.create("/key", "value", false).unwrap();

let (version, value, _) = client.get("/key", false).unwrap();
assert_eq!(version, initial_version);
assert_eq!(value, String::from("value"));

pub fn erase(&self, key: &str, version: i64) -> Result<(), OffkvError>

Erases existing key.

Arguments:

• key - key to erase
• version - if not 0, erases the key and all its descendants iff its version equals to the given one, otherwise does it unconditionally

Returns:

• ()

Example:

use rsoffkv::result::OffkvError;
let client = Client::new("consul://localhost:8500", "/test_prefix").unwrap();
let initial_version = client.create("/key", "value", false).unwrap();

// does nothing since versions differ
client.erase("/key", initial_version + 1).unwrap();

// should erase the key
client.erase("/key", initial_version).unwrap();

// next try to erase should panic with `NoEntry`
if let OffkvError::NoEntry = client.erase("/key", 0).unwrap_err() {}
else { assert!(false) }

pub fn set(&self, key: &str, value: &str) -> Result<i64, OffkvError>

Assigns the value to the the key, creates it not exist (the parent key must exist).

Arguments:

• key - key to assign value to
• value - value to be assigned

Returns:

• new version of the key

Example:

let client = Client::new("consul://localhost:8500", "/test_prefix").unwrap();
let initial_version = client.set("/key", "value").unwrap();

{
    let (version, value, _) = client.get("/key", false).unwrap();
    assert_eq!(version, initial_version);
    assert_eq!(value, String::from("value"));
}

let new_version = client.set("/key", "new value").unwrap();

{
    let (version, value, _) = client.get("/key", false).unwrap();
    assert_eq!(version, new_version);
    assert_eq!(value, String::from("new value"));
}

pub fn cas(
    &self,
    key: &str,
    value: &str,
    version: i64
) -> Result<i64, OffkvError>

Compare and set operation: if version is not 0, assigns value to key iff its current version equals to the given one, otherwise creates the key (its parent must exist).

Arguments:

• key - the key CAS is to be performed on
• value - value to be assigned
• version - assumed current key's version

Returns:

• new version of the key or 0 on failure (given version not equal to current)

Example:

let client = Client::new("consul://localhost:8500", "/test_prefix").unwrap();
let initial_version = client.cas("/key", "value", 0).unwrap();

{
    let (version, value, _) = client.get("/key", false).unwrap();
    assert_eq!(version, initial_version);
    assert_eq!(value, String::from("value"));
}

// does nothing due to given version isn't equal to the current one
let new_version = client.cas("/key", "new value", initial_version + 10).unwrap();
assert_eq!(0, new_version);

{
    let (version, value, _) = client.get("/key", false).unwrap();
    assert_eq!(version, initial_version);
    assert_eq!(value, String::from("value"));
}

let new_version = client.cas("/key", "new value", initial_version).unwrap();

{
    let (version, value, _) = client.get("/key", false).unwrap();
    assert_eq!(version, new_version);
    assert_eq!(value, String::from("new value"));
}

pub fn get(
    &self,
    key: &str,
    watch: bool
) -> Result<(i64, String, Option<WatchHandle>), OffkvError>

Returns current version and assigned value.

Arguments:

• key - a certain key
• watch - if true, a WatchHandle is returned, it can wait for key deletion or its value change.

Returns:

• current version of the key
• current assigned value
• (optional) WatchHandle

Example:

let client = Client::new("consul://localhost:8500", "/test_prefix").unwrap();
client.create("/key", "value", false);

use std::{thread,time};

thread::spawn(|| {
    let another_client = Client::new("consul://localhost:8500", "/test_prefix").unwrap();

    let (_, value, watch_handle) = another_client.get("/key", true).unwrap();
    assert_eq!(value, String::from("value"));

    watch_handle.unwrap().wait();

    let (_, value, _) = another_client.get("/key", false).unwrap();
    assert_eq!(value, String::from("new value"));
});

thread::sleep(time::Duration::from_secs(5));
client.set("/key", "new value");

pub fn exists(
    &self,
    key: &str,
    watch: bool
) -> Result<(i64, Option<WatchHandle>), OffkvError>

Checks if the key exists.

Arguments:

• key - key to check for existence
• watch - if true, creates WatchHandle that can wait for changes in the key's existence state

Returns:

• current version if the key exists, 0 otherwise
• (optional) WatchHandle

Example:

let client = Client::new("consul://localhost:8500", "/test_prefix").unwrap();
client.create("/key", "value", false);

use std::{thread,time};

thread::spawn(|| {
    let another_client = Client::new("consul://localhost:8500", "/test_prefix").unwrap();

    let (version, watch_handle) = another_client.exists("/key", true).unwrap();
    assert_ne!(0, version);

    watch_handle.unwrap().wait();

    let (version, _) = another_client.exists("/key", false).unwrap();
    assert_eq!(0, version);
});

thread::sleep(time::Duration::from_secs(5));
client.erase("/key", 0);

pub fn get_children(
    &self,
    key: &str,
    watch: bool
) -> Result<(Vec<String>, Option<WatchHandle>), OffkvError>

Returns a list of direct children.

Arguments:

• key - key whose children are to be found
• watch - if true, creates WatchHandle that can wait for any changes among children of given key

Returns:

• Vec of direct children
• (optional) WatchHandle

Example:

let client = Client::new("consul://localhost:8500", "/test_prefix").unwrap();
client.create("/key", "value", false);
client.create("/key/child1", "value", false);
client.create("/key/child2", "value", false);
client.create("/key/child3", "value", false);
client.create("/key/child1/not_child", "value", false);

use std::collections::HashSet;
use std::{thread, time};

thread::spawn(|| {
    let another_client = Client::new("consul://localhost:8500", "/test_prefix").unwrap();

    let (children, watch_handle) = another_client.get_children("/key", true).unwrap();
    {
        let result: HashSet<_> = children.iter().cloned().collect();
        let real: HashSet<_> =
            ["/key/child1", "/key/child2", "/key/child3"]
                .iter()
                .map(|s| String::from(*s))
                .collect();

        assert_eq!(result, real);
    }

    watch_handle.unwrap().wait();

    let (children, _) = another_client.get_children("/key", false).unwrap();
    {
        let result: HashSet<_> = children.iter().cloned().collect();
        let real: HashSet<_> =
            ["/key/child1", "/key/child2"]
                .iter()
                .map(|s| String::from(*s))
                .collect();

        assert_eq!(result, real);
    }
});

thread::sleep(time::Duration::from_secs(5));
client.erase("/key/child3", 0);

pub fn commit(
    &self,
    transaction: Transaction
) -> Result<Vec<TxnOpResult>, OffkvError>

Commits transaction. Transaction consists of two parts: firstly list some TxnChecks -- checks that some keys have specified versions (or just exist); next list TxnOps -- operations.

Transaction, TxnCheck and TxnOp are available in rsoffkv::txn module

Arguments:

• transaction - transaction to commit

Rertuns:

• Vec of TxnOpResult - for each operation affecting versions (namely, TxnOp::Set and TxnOp::Create) returns a new key version

Example:

use rsoffkv::txn::{Transaction, TxnCheck, TxnOp};
let client = Client::new("consul://localhost:8500", "/test_prefix").unwrap();
let initial_version = client.set("/key", "value").unwrap();
client.commit(Transaction{
    checks: vec![
        TxnCheck{key: "/key", version: initial_version},
    ],
    ops: vec![
        TxnOp::Create{key: "/key/child", value: "value", leased: false},
        TxnOp::Set{key: "/key", value: "new value"},
    ],
}).unwrap();

assert_eq!(client.get("/key", false).unwrap().1, String::from("new value"));
assert_eq!(client.get("/key/child", false).unwrap().1, String::from("value"));

Trait Implementations

impl Drop for Client

fn drop(&mut self)

Executes the destructor for this type.