Counters

Detailed Description

Manipulate the numeric content of a document.

Counter operations treat the document being accessed as a numeric value (the document should contain a parseable integer as its content). This value may then be incremented or decremented.

Functions
lcb_error_t	lcb_counter3 (lcb_t instance, const void *cookie, const lcb_CMDCOUNTER *cmd)
	Schedule single counter operation. More...

Function Documentation

lcb_error_t lcb_counter3	(	lcb_t	instance,
		const void *	cookie,
		const lcb_CMDCOUNTER *	cmd
	)

Schedule single counter operation.

Stability

Committed:

Parameters

instance	the instance
cookie	the pointer to associate with the request
cmd	the command to use

Returns

LCB_SUCCESS on success, other error on failure

Request

lcb_CMDCOUNTER cmd = { 0 };
LCB_CMD_SET_KEY(&cmd, "counter", strlen("counter"));
cmd.delta = 1; // Increment by one
cmd.initial = 42; // Default value is 42 if it does not exist
cmd.exptime = 300; // Expire in 5 minutes
lcb_counter3(instance, NULL, &cmd);
lcb_wait3(instance, LCB_WAIT_NOCHECK);

Response

lcb_install_callback3(instance, LCB_CALLBACKTYPE_COUNTER, counter_cb);
void counter_cb(lcb_t instance, int cbtype, const lcb_RESPBASE *rb)
{
    const lcb_RESPCOUNTER *resp = (const lcb_RESPCOUNTER *)rb;
    if (resp->rc == LCB_SUCCESS) {
        printf("Incremented counter for %.*s. Current value %llu\n",
               (int)resp->nkey, resp->key, resp->value);
    }
}

Callback Errors

In addition to generic errors, the following errors may be returned in the callback (via lcb_RESPBASE::rc):

• LCB_KEY_ENOENT if the counter doesn't exist (and lcb_CMDCOUNTER::create was not set)
• LCB_DELTA_BADVAL if the existing document's content could not be parsed as a number by the server.

---

Data Structure Documentation

struct lcb_CMDCOUNTER

Command for counter operations.

See also

lcb_counter3(), lcb_RESPCOUNTER.

Warning

You may only set the exptime member if the create member is set to a true value. Setting exptime otherwise will cause the operation to fail with LCB_OPTIONS_CONFLICT

The cas member should be set to 0 for this operation. As this operation itself is atomic, specifying a CAS is not necessary.

Data Fields
lcb_U32	cmdflags	Common flags for the command. These modify the command itself. Currently the lower 16 bits of this field are reserved, and the higher 16 bits are used for individual commands.
lcb_U32	exptime	Specify the expiration time. This is either an absolute Unix time stamp or a relative offset from now, in seconds. If the value of this number is greater than the value of thirty days in seconds, then it is a Unix timestamp. This field is used in mutation operations (lcb_store3()) to indicate the lifetime of the item. It is used in lcb_get3() with the lcb_CMDGET::lock option to indicate the lock expiration itself.
lcb_U64	cas	The known CAS of the item. This is passed to mutation to commands to ensure the item is only changed if the server-side CAS value matches the one specified here. For other operations (such as lcb_CMDENDURE) this is used to ensure that the item has been persisted/replicated to a number of servers with the value specified here.
lcb_KEYBUF	key	The key for the document itself. This should be set via LCB_CMD_SET_KEY()
lcb_KEYBUF	_hashkey	Stability Volatile:
lcb_int64_t	delta	Delta value. If this number is negative the item on the server is decremented. If this number is positive then the item on the server is incremented
lcb_U64	initial	If the item does not exist on the server (and create is true) then this will be the initial value for the item.
int	create	Boolean value. Create the item and set it to initial if it does not already exist

struct lcb_RESPCOUNTER

Response structure for counter operations.

See also

lcb_counter3()

Data Fields
void *	cookie	Application-defined pointer passed as the cookie parameter when scheduling the command.
const void *	key	Key for request.
lcb_SIZE	nkey	Size of key.
lcb_CAS	cas	CAS for response (if applicable)
lcb_error_t	rc	Status code.
lcb_U16	version	ABI version for response.
lcb_U16	rflags	Response specific flags. see lcb_RESPFLAGS
lcb_U64	value	Contains the current value after the operation was performed.