ec_cache_insert

March 26, 2020 Contributors

Name

ec_cache_insert — Insert a key/value pair into a cache

Synopsis

#include "ec_cache.h"

| ec_cache_elt * **ec_cache_insert** ( | cache, |   |
|   | key, |   |
|   | keylen, |   |
|   | value); |   |

ec_cache_t * <var class="pdparam">cache</var>;
const char * <var class="pdparam">key</var>;
int <var class="pdparam">keylen</var>;
void * <var class="pdparam">value</var>;

Description

Insert a key/value pair into a cache.

Parameters

cache

The address of the cache. The following typedef applies to the ec_cache_t data type:

typedef struct ec_cache_head ec_cache_t;.

key

Specifies a binary blob that is used to identify the entry in the cache. It will be copied into the “ec_cache_elt” structure. This may also be a simple NUL terminated string. The cache will make a copy of this, so the memory that you supply may be a transient buffer on the stack.

keylen

The length of the key, in bytes. The caching infrastructure makes no assumption about the NUL terminated-ness of the key, which is why you must supply the correct length of the memory using this parameter.

value

The address of the value to insert into the cache. This is an arbitrary pointer to the data that you want to cache. If an existing value with the same key is present in the cache, its reference count will be decremented and the new value you are inserting will take its place.

Return Values

Returns the address of the “ec_cache_elt” structure associated with the value.

Note

You are responsible for calling ec_cache_delref on this structure when you are done using value. This is to ensure that the cache doesn’t cause it to be deleted and to ensure that allocated memory is released.

#include "config.h"
#include "ec_cache.h"

...

  ec_cache_elt *elt;
  elt = ec_cache_insert(cache, "key", strlen("key"), value);

  /* you can use value here if you want */

  ec_cache_delref(cache, elt);
  /* after this point, you MUST NOT touch value if your destructor
   * frees its memory */

...

Threading

It is legal to call this function in any thread.

See Also

ec_cache_create, ec_cache_create2, ec_cache_delete, ec_cache_delref, ec_cache_destroy, ec_cache_find, “ec_cache_head”, and “ec_cache_elt”.