Go to main content

man pages section 3: Extended Library Functions, Volume 4

Exit Print View

Updated: Thursday, June 13, 2019
 
 

sstore_partition_alloc (3SSTORE)

Name

sstore_partition_alloc, sstore_partition_free, sstore_partition_inc_value, sstore_partition_set_value - allocate, free, or update an sstore_partition_t

Synopsis

cc [ flag... ] file... -lsstore [ library... ]
#include <libsstore.h>

typedef struct sstore_partition *sstore_partition_t;

sstore_partition_t sstore_partition_alloc(uint32_t num_parts);

void sstore_partition_free(sstore_partition_t p);

sstore_err_t sstore_partition_set_value(sstore_handle_t hdl,
    sstore_partition_t p, const char **keys, uint64_t val);

sstore_err_t sstore_partition_inc_value(sstore_handle_t hdl,
    sstore_partition_t p, const char **keys, uint64_t val);

Parameters

num_parts

Total number of partitions

hdl

Handle to libsstore

p

sstore_partition_t to be updated or freed

keys

Array of keys associated with each partition

val

Value to be incremented or set for the given keys

Description

sstore_partition_t is an opaque struct that represents a multi-key dictionary.

In order to provide partition data for a statistic, the partitions must be defined in the statistic metadata.

For example, if a stat named //:stat.requests has two partitions: type and client, then it should have the following key-value pair in its metadata:

"partitions": ["type", "user"]

For more information, see ssid-metadata man page.

If the user-application receives the following request:

{"GET", "bob"}

The user-application can pass ["GET", "bob"] as keys to sstore_partition_inc_value() function with value = 1 to attribute one request of type="GET" to user="bob". This task can be done as many times as necessary for each request, and once all the values are up-to-date, the user-application can pass the sstore_partition_t to sstore_data_update or sstore_data_bulk_update which will update the relevant statistic in sstored.

sstore_partition_alloc() function allocates an sstore_partition_t which can hold upto num_parts partition keys.

sstore_partition_free() function frees the given sstore_partition_t, and the keys and values associated with it.

sstore_partition_set_value() function adds a new entry for the given keys if it does not exist, and sets its value to val. The number of keys must be same as num_parts passed to the sstore_partition_alloc() function.

sstore_partition_inc_value() function adds a new entry for the given keys if it does not exist, and sets its value to val. If the keys already exist, then it increments its value by val. The number of keys must be same as num_parts passed to the sstore_partition_alloc() function.

Return Values

Upon successful completion, the sstore_partition_set_value() and sstore_partition_inc_value() functions return ESSTORE_OK. Else, they return an error code, which is cached in the given libsstore handle.

Errors

The sstore_partition_set_value() and sstore_partition_inc_value() functions will fail if:

ESSTORE_ARG_INVALID

Required arguments are missing

ESSTORE_HANDLE_INVALID

The handle is invalid

ESSTORE_NOMEM

No memory is available

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
Availability
pkg:/service/system/sstore
MT-Level
Safe

See Also

libsstore(3LIB), sstore_alloc(3SSTORE), sstore_data_attach(3SSTORE), sstore_err_action(3SSTORE), sstore_value_alloc(3SSTORE), ssid-metadata(7)