kv_create_key()

#include <kvstore.h>

kv_error_t 
kv_create_key(kv_store_t *store,
              kv_key_t **key,
              const char **major,
              const char **minor) 

Creates a key in the key/value store. To release the resources used by this structure, use kv_release_key().

This function differs from kv_create_key_copy() in that it does not copy the contents of the strings passed to the function. Therefore, these strings should not be released or modified until the kv_key_t structure created by this function is released.

A key represents a path to a value in a hierarchical namespace. It consists of a sequence of string path component names, and each component name is used to navigate the next level down in the hierarchical namespace. The complete sequence of string components is called the full key path.

The sequence of string components in a full key path is divided into two groups or sub-sequences: The major key path is the initial or beginning sequence, and the minor key path is the remaining or ending sequence. The Full Path is the concatenation of the Major and Minor Paths, in that order. The Major Path must have at least one component, while the Minor path may be empty (have zero components).

Each path component must be a non-null String. Empty (zero length) Strings are allowed, except that the first component of the major path must be a non-empty String.

Given a key, finding the location of a key/value pair is a two step process:

1. The major path is used to locate the node on which the key/value pair can be found.

2. The full path is then used to locate the key/value pair within that node.

Therefore all key/value pairs with the same major path are clustered on the same node.

Keys which share a common major path are physically clustered by the KVStore and can be accessed efficiently via special multiple-operation APIs, e.g. kv_multi_get(). The APIs are efficient in two ways:

1. They permit the application to perform multiple-operations in single network round trip.

2. The individual operations (within a multiple-operation) are efficient since the common-prefix keys and their associated values are themselves physically clustered.

Multiple-operation APIs also support ACID transaction semantics. All the operations within a multiple-operation are executed within the scope of a single transaction.

Parameters

• store

  The store parameter is the handle to the store in which the key is used. The store handle is obtained using kv_open_store().

• key

  The key parameter references memory into which a pointer to the allocated key is copied.

• major

  The major parameter is an array of strings, each element of which represents a major path component.

  Note that the string used here is not copied. You must not release or modify this memory until the structure in which it is used is released.

• minor

  The minor parameter is an array of strings, each element of which represents a minor path component.

  Note that the string used here is not copied. You must not release or modify this memory until the structure in which it is used is released.

See Also

• Key/Value Pair Management Functions