19.1.1 Flow of cache access and data operations

(1) Example of a source program in C

The following shows an example of a source program in C (to store a key and value):

#include <stdio.h>
#include <string.h>
 
#include <eads.h>
 
int main(int argc, char **argv) {
    int ret = 0;
    int error_code = 0;
    char CONFPATH[] = "./conf/eads_sample_client.properties";
    char CACHENAME[] = "cache1";
    char KEY[] = "key1";
    char VALUE[] = "value1";
    EAD_CACHE_MANAGER* cmp = NULL;
    EAD_CACHE *cp = NULL;
    ead_value_element value_element;
 
    value_element.value = (void *)VALUE;
    value_element.value_size = strlen(VALUE) + 1;
 
    /* Initialize EADS client */
    cmp = ead_init_client(CONFPATH, &error_code);
    printf("ead_init_client() done. (error_code = %d)\n", error_code);
    if (error_code != EAD_OK) {
        return 1;
    }
 
    /* Start access to the cache */
    cp = ead_start_cache(cmp, CACHENAME, &error_code);
    printf("ead_start_cache() done. (error_code = %d)\n", error_code);
    if (error_code != EAD_OK) {
        /* Need to terminate EADS client */
        goto ERR;
    }
 
    /* Store key and value */
    ead_put(cp, KEY, &value_element, &error_code);
    printf("ead_put() done. (error_code = %d)\n", error_code);
    if (error_code != EAD_OK) {
        /* Need to terminate EADS client */
        goto ERR;
    }
 
    /* Stop access to the cache */
    ead_stop_cache(cp, &error_code);
    cp = NULL;
    printf("ead_stop_cache() done. (error_code = %d)\n", error_code);
    if (error_code != EAD_OK) {
        /* Need to terminate EADS client */
        goto ERR;
    }
 
    /* Terminate EADS client */
    ead_terminate_client(cmp, &error_code);
    cmp = NULL;
    printf("ead_terminate_client() done. (error_code = %d)\n", error_code);
    if (error_code != EAD_OK) {
        /* Need to terminate EADS client */
        goto ERR;
    }
 
    return 0;
 
ERR:
    if(cp != NULL) {
        /* Stop access to the cache */
        ead_stop_cache(cp, &error_code);
        cp = NULL;
        printf("ead_stop_cache() done. (error_code = %d)\n", error_code);
    }
 
    if(cmp != NULL) {
        /* Terminate EADS client */
        ead_terminate_client(cmp, &error_code);
        cmp = NULL;
        printf("ead_terminate_client() done. (error_code = %d)\n", error_code);
    }
 
    return 1;
}

To Page Top

(2) Initializing the EADS client

To initialize an EADS client, use ead_init_client() or ead_init_client_n() and obtain a handle (pointer) to the cache manager for managing the cache.

Some settings are specified in the client properties, such as the connection-target EADS server.

If you want to use multiple cache managers with different settings, such as when connection is established with multiple clusters, edit the client properties and then execute ead_init_client() or ead_init_client_n() multiple times. To terminate the EADS client when you have executed ead_init_client() or ead_init_client_n() multiple times, execute ead_terminate_client() on each of the acquired handles to the cache manager.

To Page Top

(3) Starting access to the cache

After initialization of the EADS client is complete, start access to the cache.

To start access to the cache, use ead_start_cache() to obtain the handle (pointer) for controlling access to the cache. Using this handle will allow you to gain access to the cache.

To Page Top

(4) Storing keys and values

Use ead_put() to store a key and value in the cache.

In ead_put(), specify the handle to the cache obtained from ead_start_cache(). In addition, specify the key and value information (the value and its size) to be stored in the cache. The value information is provided as an ead_value_element structure.

To Page Top

(5) Retrieving values

Use ead_get() to retrieve values from the cache.

In ead_get(), specify the handle to the cache obtained from ead_start_cache(). In addition, specify the key associated with the value you want to retrieve.

If the value is successfully retrieved by ead_get(), the value information associated with the key is returned as an ead_value_element structure.

Note that the memory area that is returned as the return value is not automatically freed. For details about freeing this memory, see (10) Freeing a memory area returned as a return value.

The following is an example of source code for retrieving a value.

Example of source code (for retrieving a value)

{
    /* Retrieve a value */
    ead_value_element ret_value;
    char KEY[] = "key1";
    ret_value = ead_get(cp, KEY, &error_code);
    printf("ead_get() done. (error_code = %d)\n", error_code);
    if (error_code != EAD_OK) {
        /* Need to terminate EADS client */
        goto ERR;
    }
    /* Free the retrieved value when done using it */
    freeValue(&ret_value);
}

To Page Top

(6) Removing keys and values

Use ead_remove() to remove a specified key from the cache, as well as the value associated with that key.

In ead_remove(), specify the handle to the cache obtained from ead_start_cache(). In addition, specify the key associated with the value you want to remove.

To Page Top

(7) Executing user functions

To Page Top

(8) Stopping access to the cache

Use ead_stop_cache() to stop access to the cache.

In ead_stop_cache(), specify the handle to the cache obtained from ead_start_cache().

To Page Top

(9) Terminating the EADS client

Use ead_terminate_client() to terminate the EADS client.

Specify in ead_terminate_client() the handle to the cache manager that was acquired by ead_init_client() or ead_init_client_n().

To Page Top

(10) Freeing a memory area returned as a return value

The memory area that is returned as the return value of ead_get() is not freed automatically. Instead, you must define in the application program a function such as the one below to free the memory.

/* Freeing a memory area returned as a return value */
void freeValue(ead_value_element *value) {
    if (value->value != NULL) {
        free(value->value);
        value->value = NULL;
    }
    value->value_size = 0;
}

The table below lists the functions for which memory area returned as a return value must be freed by the application program. If a return value to be released is not NULL, free the memory area for the functions listed in this table when the return value is no longer needed.

To Page Top