cachelot C api library and documentation

[cachelot]

cachelot C api library and documentation

[aka-rider]

Hi @recoilme. Unfortunately there is no online documentation yet.
You can look at the Doxygen-generated documentation, it's not that bad.

Alternatively you may look at the sources src/cachelot/cache.h. This is the one file, containing single API class Cache. There are all memcached-like methods: set, get, append, cas, etc.
And the file src/server/memcached/proto_ascii.cpp is an example of usage.

I would be glad to answer any further questions.

[recoilme]

Hi @aka-rider Sorry, i am dont know cpp( May you please provide simple example on c? Something like set("hello","word") get("hello")?

[aka-rider]

Unfortunately support of the C language is in the backlog for now.

Minimal example would look something like this:

using namespace cachelot;

// Create the Cache
cache::Cache cache_api = new cache::Cache(
    settings.cache.memory_limit, // maximum amount of memory to use
    settings.cache.page_size,    // smaller pages lead to more accurate evictions, but max item size is limited by page size (power of 2)
    settings.cache.initial_hash_table_size, // initial length of the hash table main array (power of 2)
    settings.cache.has_evictions);  // evict items when out of memory of just report an error


int StoreItem(cachelot::cache::Cache *cache_api, const char * key, unsigned keylen, const char * value, unsigned valuelen) {
    cachelot::bytes key(key, keylen);
    cachelot::bytes value(value, valuelen);
    uint16_t flags = 0; // user-defined flags to store along with the Item
    cache::seconds keep_alive_duration = cache::seconds(60);

    cache::ItemPtr new_item = cache_api.create_item(key, calc_hash(key), value.length(), flags, keep_alive_duration);
    new_item->assign_value(value);
    try {
        cache::Response response = cache_api.do_set(new_item);
        if (response == cache::STORED) {
            return 0; // OK
        } else {
            // Item was not stored in the cache
            cache_api.destroy_item(new_item);
            return 1;
        }
    } catch(...) {
        // something went wrong
        cache_api.destroy_item(new_item);
        return 1;
    }
}


int RetrieveItem(cachelot::cache::Cache *cache_api, const char * key, unsigned keylen) {
    cachelot::bytes key(key, keylen);
    try { 
        cache::ItemPtr i = cache_api.do_get(key, calc_hash(key));
        if (i) {
            return i.value.begin(); // pointer to the value
        }
    } catch(...) {
         // ignore exceptions
    }
    return nullptr;
}

Little explanation:

cache::bytes is just a const-pointer to the region in memory

struct bytes {
    const char * begin;
    const char * end;
}

calc_hash - is any hash function, returning int32_t (CRC32, Murmur, CityHash - what suits your needs best)
cachelot uses Fowler–Noll–Vo hash

[aka-rider]

Oops. @recoilme sorry.
slice is a type name in my private branch. In master it's called bytes

I will try to make a C API and library documentation ASAP

[recoilme]

@aka-rider thank you very much for your assistance! I will try soon and give you feedback

[aka-rider]

Hi @recoilme

You can check out C API.
https://github.com/cachelot/cachelot/blob/master/src/cachelot/c_api.h

Unfortunately, there is no documentation except Doxygen.
https://github.com/cachelot/cachelot/blob/master/src/test_c_api/test_c_api.c may be example of how to use API.