Modules
	KeyValue store management

	KeyValue store entries

	KeyValue store watcher

	KeyValue store status

Functions
NATS_EXTERN natsStatus	kvStore_Get (kvEntry *new_entry, kvStore kv, const char *key)
	Returns the latest entry for the key.

NATS_EXTERN natsStatus	kvStore_GetAsync (kvStore kv, const char key, kvGetCb cb, void *cbClosure)
	Asynchronously returns the latest entry for the key.

NATS_EXTERN natsStatus	kvStore_GetRevision (kvEntry *new_entry, kvStore kv, const char *key, uint64_t revision)
	Returns the entry at the specific revision for the key.

NATS_EXTERN natsStatus	kvStore_Put (uint64_t rev, kvStore kv, const char key, const void data, int len)
	Places the new value for the key into the store.

NATS_EXTERN natsStatus	kvStore_PutString (uint64_t rev, kvStore kv, const char key, const char data)
	Places the new value (as a string) for the key into the store.

NATS_EXTERN natsStatus	kvStore_Create (uint64_t rev, kvStore kv, const char key, const void data, int len)
	Places the value for the key into the store if and only if the key does not exist.

NATS_EXTERN natsStatus	kvStore_CreateString (uint64_t rev, kvStore kv, const char key, const char data)
	Places the value (as a string) for the key into the store if and only if the key does not exist.

NATS_EXTERN natsStatus	kvStore_CreateWithTTL (uint64_t rev, kvStore kv, const char key, const void data, int len, int64_t ttl)
	Create-if-absent with a per-key TTL.

NATS_EXTERN natsStatus	kvStore_CreateStringWithTTL (uint64_t rev, kvStore kv, const char key, const char data, int64_t ttl)
	String variant of kvStore_CreateWithTTL.

NATS_EXTERN natsStatus	kvStore_Update (uint64_t rev, kvStore kv, const char key, const void data, int len, uint64_t last)
	Updates the value for the key into the store if and only if the latest revision matches.

NATS_EXTERN natsStatus	kvStore_UpdateString (uint64_t rev, kvStore kv, const char key, const char data, uint64_t last)
	Updates the value (as a string) for the key into the store if and only if the latest revision matches.

NATS_EXTERN natsStatus	kvStore_UpdateWithTTL (uint64_t rev, kvStore kv, const char key, const void data, int len, uint64_t last, int64_t ttl)
	Updates a key with a per-key TTL if and only if the latest revision matches.

NATS_EXTERN natsStatus	kvStore_UpdateStringWithTTL (uint64_t rev, kvStore kv, const char key, const char data, uint64_t last, int64_t ttl)
	String variant of kvStore_UpdateWithTTL.

NATS_EXTERN natsStatus	kvStore_Delete (kvStore kv, const char key)
	Deletes a key by placing a delete marker and leaving all revisions.

NATS_EXTERN natsStatus	kvStore_Purge (kvStore kv, const char key, const kvPurgeOptions *opts)
	Deletes a key by placing a purge marker and removing all revisions.

NATS_EXTERN natsStatus	kvWatchOptions_Init (kvWatchOptions *opts)
	Initializes a KeyValue watcher options structure.

NATS_EXTERN natsStatus	kvPurgeOptions_Init (kvPurgeOptions *opts)
	Initializes a KeyValue purge options structure.

NATS_EXTERN natsStatus	kvStore_PurgeDeletes (kvStore kv, const kvPurgeOptions opts)
	Purge and removes delete markers.

NATS_EXTERN natsStatus	kvStore_Watch (kvWatcher *new_watcher, kvStore kv, const char keys, const kvWatchOptions opts)
	Returns a watcher for any updates to keys that match the `keys` argument.

NATS_EXTERN natsStatus	kvStore_WatchMulti (kvWatcher *new_watcher, kvStore kv, const char *keys, int numKeys, const kvWatchOptions opts)
	Returns a watcher for any updates to keys that match one of the `keys` argument.

NATS_EXTERN natsStatus	kvStore_WatchAll (kvWatcher *new_watcher, kvStore kv, const kvWatchOptions *opts)
	Returns a watcher for any updates to any keys of the KeyValue store bucket.

NATS_EXTERN natsStatus	kvStore_Keys (kvKeysList list, kvStore kv, const kvWatchOptions *opts)
	Returns all keys in the bucket.

NATS_EXTERN natsStatus	kvStore_KeysWithFilters (kvKeysList list, kvStore kv, const char *filters, int numFilters, const kvWatchOptions opts)
	Returns all keys in the bucket which matches the list of subject like filters.

NATS_EXTERN void	kvKeysList_Destroy (kvKeysList *list)
	Destroys this list of KeyValue store key strings.

NATS_EXTERN natsStatus	kvStore_History (kvEntryList list, kvStore kv, const char key, const kvWatchOptions opts)
	Returns all historical entries for the key.

NATS_EXTERN void	kvEntryList_Destroy (kvEntryList *list)
	Destroys this list of KeyValue store entries.

NATS_EXTERN const char *	kvStore_Bucket (const kvStore *kv)
	Returns the bucket name of this KeyValue store object.

NATS_EXTERN natsStatus	kvStore_Status (kvStatus *new_status, kvStore kv)
	Returns the status and configuration of a bucket.

Detailed Description

A KeyValue store is a materialized view of JetStream.

Function Documentation

◆ kvStore_Get()

NATS_EXTERN natsStatus kvStore_Get	(	kvEntry **	new_entry,
		kvStore *	kv,
		const char *	key
	)

Returns the latest entry for the key.

Note: The entry should be destroyed to release memory using kvEntry_Destroy.

Parameters

new_entry	the location where to store the pointer to the entry associated with the `key`.
kv	the pointer to the kvStore object.
key	the name of the key.

◆ kvStore_GetAsync()

NATS_EXTERN natsStatus kvStore_GetAsync	(	kvStore *	kv,
		const char *	key,
		kvGetCb	cb,
		void *	cbClosure
	)

Starts the retrieval of the latest entry for the given key and returns immediately, without waiting for the server's response. The provided callback is invoked when the entry (or the reason why it could not be retrieved) is available.

Note: The callback is invoked exactly once, and only if this call returns NATS_OK. See kvGetCb for the statuses it can receive, and for the threads it runs on (a library thread, possibly before this call returns).

To process the entry from an application thread instead, the callback can simply hand it over, for instance:

// One object per get, so that a failed get (NULL entry) can still be
// tied to its key.
typedef struct
{
    const char  *key;
    kvEntry     *entry;
    natsStatus  status;
 
} getResult;
 
static myWorkQueue q; // thread-safe FIFO of getResult
 
static void
getCompleted(kvStore *kv, kvEntry *e, natsStatus s, void *closure)
{
    getResult *r = (getResult*) closure;
 
    // The entry (NULL if s != NATS_OK) is now owned by the application,
    // which must eventually call kvEntry_Destroy.
    r->entry  = e;
    r->status = s;
    myWorkQueue_Push(&q, r);
}
 
// ...
r->key = "key";
s = kvStore_GetAsync(kv, r->key, getCompleted, (void*) r);

A complete program along these lines is in examples/kv-get-async.c.

See also: kvGetCb

Parameters

kv	the pointer to the kvStore object.
key	the name of the key.
cb	the callback function to invoke when the entry is retrieved.
cbClosure	a pointer to an user defined object (can be `NULL`).

◆ kvStore_GetRevision()

NATS_EXTERN natsStatus kvStore_GetRevision	(	kvEntry **	new_entry,
		kvStore *	kv,
		const char *	key,
		uint64_t	revision
	)

Returns the entry at the specific revision for the key, or NATS_NOT_FOUND if there is no entry for that key and revision.

Note: The entry should be destroyed to release memory using kvEntry_Destroy.

Parameters

new_entry	the location where to store the pointer to the entry associated with the `key`.
kv	the pointer to the kvStore object.
key	the name of the key.
revision	the revision of the entry (must be > 0).

◆ kvStore_Put()

NATS_EXTERN natsStatus kvStore_Put	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const void *	data,
		int	len
	)

Places the new value for the key into the store.

Parameters

rev	the location where to store the revision of this value, or `NULL` if the stream information is not needed.
kv	the pointer to the kvStore object.
key	the name of the key.
data	the pointer to the data in memory.
len	the number of bytes to copy from the data's memory location.

◆ kvStore_PutString()

NATS_EXTERN natsStatus kvStore_PutString	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const char *	data
	)

Places the new value, as a string, for the key into the store.

Note: This is equivalent of calling kvStore_Put with (int) strlen(data).

Warning: The NULL terminating character is not included in the number of bytes stored in the KeyValue store.

Parameters

rev	the location where to store the revision of this value, or `NULL` if the stream information is not needed.
kv	the pointer to the kvStore object.
key	the name of the key.
data	the pointer to the string to store.

◆ kvStore_Create()

NATS_EXTERN natsStatus kvStore_Create	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const void *	data,
		int	len
	)

Places the value for the key into the store if and only if the key does not exist.

Parameters

rev	the location where to store the revision of this value, or `NULL` if the stream information is not needed.
kv	the pointer to the kvStore object.
key	the name of the key.
data	the pointer to the data in memory.
len	the number of bytes to copy from the data's memory location.

◆ kvStore_CreateString()

NATS_EXTERN natsStatus kvStore_CreateString	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const char *	data
	)

Places the value (as a string) for the key into the store if and only if the key does not exist.

Note: This is equivalent of calling kvStore_Create with (int) strlen(data).

Warning: The NULL terminating character is not included in the number of bytes stored in the KeyValue store.

Parameters

rev	the location where to store the revision of this value, or `NULL` if the stream information is not needed.
kv	the pointer to the kvStore object.
key	the name of the key.
data	the pointer to the string.

◆ kvStore_CreateWithTTL()

NATS_EXTERN natsStatus kvStore_CreateWithTTL	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const void *	data,
		int	len,
		int64_t	ttl
	)

Like kvStore_Create, but the new value is published with a per-message TTL so the server expires this key after ttl milliseconds. Re-creating over an existing delete/purge/MaxAge marker succeeds and keeps the TTL (the marker-aware create path is reused). Requires the bucket to have been created with kvConfig.LimitMarkerTTL > 0 and nats-server v2.11+; otherwise the server rejects the TTL (JSMessageTTLDisabledErr). The server requires the TTL to be at least 1 second (1000 ms); a smaller value is rejected with JSMessageTTLInvalidErr.

Parameters

rev	the location where to store the revision of this value, or `NULL`.
kv	the pointer to the kvStore object.
key	the name of the key.
data	the pointer to the data in memory.
len	the number of bytes to copy from the data's memory location.
ttl	per-key time-to-live in milliseconds (`<= 0` means no TTL — same as kvStore_Create).

◆ kvStore_CreateStringWithTTL()

NATS_EXTERN natsStatus kvStore_CreateStringWithTTL	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const char *	data,
		int64_t	ttl
	)

Note: Equivalent of calling kvStore_CreateWithTTL with (int) strlen(data).

◆ kvStore_Update()

NATS_EXTERN natsStatus kvStore_Update	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const void *	data,
		int	len,
		uint64_t	last
	)

Updates the value for the key into the store if and only if the latest revision matches.

Parameters

rev	the location where to store the revision of this value, or `NULL` if the stream information is not needed.
kv	the pointer to the kvStore object.
key	the name of the key.
data	the pointer to the data in memory.
len	the number of bytes to copy from the data's memory location.
last	the expected latest revision prior to the update.

◆ kvStore_UpdateString()

NATS_EXTERN natsStatus kvStore_UpdateString	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const char *	data,
		uint64_t	last
	)

Updates the value (as a string) for the key into the store if and only if the latest revision matches.

Note: This is equivalent of calling kvStore_Update with (int) strlen(data).

Warning: The NULL terminating character is not included in the number of bytes stored in the KeyValue store.

Parameters

rev	the location where to store the revision of this value, or `NULL` if the stream information is not needed.
kv	the pointer to the kvStore object.
key	the name of the key.
data	the pointer to the string.
last	the expected latest revision prior to the update.

◆ kvStore_UpdateWithTTL()

NATS_EXTERN natsStatus kvStore_UpdateWithTTL	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const void *	data,
		int	len,
		uint64_t	last,
		int64_t	ttl
	)

Like kvStore_Update, but the new value is published with a per-message TTL so the server expires this key after ttl milliseconds. The TTL is set on the same CAS publish, so a plain update can adopt a TTL atomically. Requires the bucket to have been created with kvConfig.LimitMarkerTTL > 0 and nats-server v2.11+; otherwise the server rejects the TTL (JSMessageTTLDisabledErr). The server requires the TTL to be at least 1 second (1000 ms); a smaller value is rejected with JSMessageTTLInvalidErr.

Parameters

rev	the location where to store the revision of this value, or `NULL`.
kv	the pointer to the kvStore object.
key	the name of the key.
data	the pointer to the data in memory.
len	the number of bytes to copy from the data's memory location.
last	the expected latest revision prior to the update.
ttl	per-key time-to-live in milliseconds (`<= 0` means no TTL — same as kvStore_Update).

◆ kvStore_UpdateStringWithTTL()

NATS_EXTERN natsStatus kvStore_UpdateStringWithTTL	(	uint64_t *	rev,
		kvStore *	kv,
		const char *	key,
		const char *	data,
		uint64_t	last,
		int64_t	ttl
	)

Note: Equivalent of calling kvStore_UpdateWithTTL with (int) strlen(data).

◆ kvStore_Delete()

NATS_EXTERN natsStatus kvStore_Delete	(	kvStore *	kv,
		const char *	key
	)

Deletes a key by placing a delete marker and leaving all revisions.

Parameters

kv	the pointer to the kvStore object.
key	the name of the key.

◆ kvStore_Purge()

NATS_EXTERN natsStatus kvStore_Purge	(	kvStore *	kv,
		const char *	key,
		const kvPurgeOptions *	opts
	)

Deletes a key by placing a purge marker and removing all revisions.

Parameters

kv	the pointer to the kvStore object.
key	the name of the key.
opts	the pointer to the kvPurgeOptions, possibly `NULL`.

◆ kvWatchOptions_Init()

NATS_EXTERN natsStatus kvWatchOptions_Init ( kvWatchOptions * opts )

Use this before setting specific watcher options and passing it to kvStore_Watch.

Parameters

opts	the pointer to the kvWatchOptions to initialize.

◆ kvPurgeOptions_Init()

NATS_EXTERN natsStatus kvPurgeOptions_Init ( kvPurgeOptions * opts )

Use this before setting specific purge options and passing it to kvStore_Purge or kvStore_PurgeDeletes.

Parameters

opts	the pointer to the kvPurgeOptions to initialize.

◆ kvStore_PurgeDeletes()

NATS_EXTERN natsStatus kvStore_PurgeDeletes	(	kvStore *	kv,
		const kvPurgeOptions *	opts
	)

Removes data and delete markers, but may keep the markers that are considered more recent than a certain threshold (default is 30 minutes).

This is a maintenance option if there is a larger buildup of delete markers.

Note: Use kvPurgeOptions.Timeout to specify how long to wait (in milliseconds) in gathering all keys that have purge markers. This function will still purge some of the keys and return NATS_TIMEOUT to indicate that it may not have deleted them all.

See also: kvPurgeOptions_Init

Parameters

kv	the pointer to the kvStore object.
opts	the pointer to the kvPurgeOptions, possibly `NULL`.

◆ kvStore_Watch()

NATS_EXTERN natsStatus kvStore_Watch	(	kvWatcher **	new_watcher,
		kvStore *	kv,
		const char *	keys,
		const kvWatchOptions *	opts
	)

Returns a watcher for any updates to keys that match the keys argument, which could include wildcard.

A NULL entry will be posted when the watcher has received all initial values.

Call kvWatcher_Next to get the next kvEntry.

Note: The watcher should be destroyed to release memory using kvWatcher_Destroy.

Parameters

new_watcher	the location where to store the pointer to the new kvWatcher object.
kv	the pointer to the kvStore object.
keys	the keys (wildcard possible) to create the watcher for.
opts	the watcher options, possibly `NULL`.

◆ kvStore_WatchMulti()

NATS_EXTERN natsStatus kvStore_WatchMulti	(	kvWatcher **	new_watcher,
		kvStore *	kv,
		const char **	keys,
		int	numKeys,
		const kvWatchOptions *	opts
	)

Returns a watcher for any updates to keys that match the one of keys argument, which could include wildcards.

A NULL entry will be posted when the watcher has received all initial values.

Call kvWatcher_Next to get the next kvEntry.

Note: The watcher should be destroyed to release memory using kvWatcher_Destroy.

Parameters

new_watcher	the location where to store the pointer to the new kvWatcher object.
kv	the pointer to the kvStore object.
keys	the keys (wildcard possible) to create the watcher for.
numKeys	the number of keys in the `keys` array.
opts	the watcher options, possibly `NULL`.

◆ kvStore_WatchAll()

NATS_EXTERN natsStatus kvStore_WatchAll	(	kvWatcher **	new_watcher,
		kvStore *	kv,
		const kvWatchOptions *	opts
	)

Returns a watcher for any updates to any keys of the KeyValue store bucket.

A NULL entry will be posted when the watcher has received all initial values.

Call kvWatcher_Next to get the next kvEntry.

Note: The watcher should be destroyed to release memory using kvWatcher_Destroy.

Parameters

new_watcher	the location where to store the pointer to the new kvWatcher object.
kv	the pointer to the kvStore object.
opts	the watcher options, possibly `NULL`.

◆ kvStore_Keys()

NATS_EXTERN natsStatus kvStore_Keys	(	kvKeysList *	list,
		kvStore *	kv,
		const kvWatchOptions *	opts
	)

Returns all keys in the bucket.

Note: Use kvWatchOptions.Timeout to specify how long to wait (in milliseconds) to gather all keys for this bucket. If the deadline is reached, this function will return NATS_TIMEOUT and no keys.

Warning: The user should call kvKeysList_Destroy to release memory allocated for the entries list.

See also: kvWatchOptions_Init; kvKeysList_Destroy

Parameters

list	list the pointer to a kvKeysList that will be initialized and filled with resulting key strings.
kv	the pointer to the kvStore object.
opts	the history options, possibly `NULL`.

◆ kvStore_KeysWithFilters()

NATS_EXTERN natsStatus kvStore_KeysWithFilters	(	kvKeysList *	list,
		kvStore *	kv,
		const char **	filters,
		int	numFilters,
		const kvWatchOptions *	opts
	)

Get a list of the keys in a bucket filtered by a subject-like string, for instance "key" or "key.foo.*" or "key.>" Any deleted or purged keys will not be returned.

Note: Use kvWatchOptions.Timeout to specify how long to wait (in milliseconds) to gather all keys for this bucket. If the deadline is reached, this function will return NATS_TIMEOUT and no keys.

Warning: The user should call kvKeysList_Destroy to release memory allocated for the entries list.

See also: kvWatchOptions_Init; kvKeysList_Destroy; kvStore_WatchMulti

Parameters

list	the pointer to a kvKeysList that will be initialized and filled with resulting key strings.
kv	the pointer to the kvStore object.
filters	the list of subject filters. Cannot be `NULL`.
numFilters	number of filters. Cannot be 0.
opts	the history options, possibly `NULL`.

◆ kvKeysList_Destroy()

NATS_EXTERN void kvKeysList_Destroy ( kvKeysList * list )

This function iterates through the list of all key strings and free them. It then frees the array that was allocated to hold pointers to those keys.

Note: The kvKeysList object itself is not freed since it is expected that users will pass a pointer to a stack object. Should the user create its own object, it will be the user responsibility to free this object.

Parameters

list	the kvKeysList list of key strings to destroy.

◆ kvStore_History()

NATS_EXTERN natsStatus kvStore_History	(	kvEntryList *	list,
		kvStore *	kv,
		const char *	key,
		const kvWatchOptions *	opts
	)

Returns all historical entries for the key

Use the options to alter the behavior. For instance, if delete markers are not desired, option kvWatchOptions.IgnoreDeletes should be specified.

Note: Use kvWatchOptions.Timeout to specify how long to wait (in milliseconds) to gather all entries for this key. If the deadline is reached, this function will return NATS_TIMEOUT and no entries.

Warning: The user should call kvEntryList_Destroy to release memory allocated for the entries list.

See also: kvWatchOptions_Init; kvEntryList_Destroy

Parameters

list	the pointer to a kvEntryList that will be initialized and filled with resulting entries.
kv	the pointer to the kvStore object.
key	the key for which the history is requested.
opts	the history options, possibly `NULL`.

◆ kvEntryList_Destroy()

NATS_EXTERN void kvEntryList_Destroy ( kvEntryList * list )

This function iterates through the list of all entries and call kvEntry_Destroy. It then frees the array that was allocated to hold pointers to those entries.

Note: The kvEntryList object itself is not freed since it is expected that users will pass a pointer to a stack object. Should the user create its own object, it will be the user responsibility to free this object.

Parameters

list	the kvEntryList list of kvEntry objects to destroy.

◆ kvStore_Bucket()

NATS_EXTERN const char * kvStore_Bucket ( const kvStore * kv )

Returns the bucket name of this KeyValue store object, or NULL if kv itself is NULL.

Warning: Do not free the string returned by this function.

Parameters

kv	the pointer to the kvStore object.

◆ kvStore_Status()

NATS_EXTERN natsStatus kvStore_Status	(	kvStatus **	new_status,
		kvStore *	kv
	)

Returns the status and configuration of a bucket.

Note: The status should be destroyed to release memory using kvStatus_Destroy.

Parameters

new_status	the location where to store the status of this KeyValue store.
kv	the pointer to the kvStore object.

Modules

Functions

Detailed Description

Function Documentation

◆ kvStore_Get()

◆ kvStore_GetAsync()

◆ kvStore_GetRevision()

◆ kvStore_Put()

◆ kvStore_PutString()

◆ kvStore_Create()

◆ kvStore_CreateString()

◆ kvStore_CreateWithTTL()

◆ kvStore_CreateStringWithTTL()

◆ kvStore_Update()

◆ kvStore_UpdateString()

◆ kvStore_UpdateWithTTL()

◆ kvStore_UpdateStringWithTTL()

◆ kvStore_Delete()

◆ kvStore_Purge()

◆ kvWatchOptions_Init()

◆ kvPurgeOptions_Init()

◆ kvStore_PurgeDeletes()

◆ kvStore_Watch()

◆ kvStore_WatchMulti()

◆ kvStore_WatchAll()

◆ kvStore_Keys()

◆ kvStore_KeysWithFilters()

◆ kvKeysList_Destroy()

◆ kvStore_History()

◆ kvEntryList_Destroy()

◆ kvStore_Bucket()

◆ kvStore_Status()