Grouped table operations

Functions
kv_operations_t *	kv_create_operations ()
	Creates and initializes an operations structure to hold a sequence of update operations that execute in a single transaction. All of the operations in this structure must shard the same fully-defined shard key in order to operate transactionally. More...
kv_error_t	kv_operations_set_copy (kv_operations_t *operations)
	Configures a list of operations to copy user-supplied structures and buffers. More...
kv_error_t	kv_operations_set_donate (kv_operations_t *operations)
	Configures the operation list so that keys, rows and versions passed to create operations are donated to the list (owned by the list) and not copied. More...
kv_error_t	kv_create_table_put_op (kv_operations_t *operations, const char *table_name, const kv_row_t *row, kv_return_row_version_enum choice, kv_boolean_t abort_on_failure)
	Creates a put operation. More...
kv_error_t	kv_create_table_put_if_absent_op (kv_operations_t *operations, const char *table_name, const kv_row_t *row, kv_return_row_version_enum choice, kv_boolean_t abort_on_failure)
	Creates a putIfAbsent operation. More...
kv_error_t	kv_create_table_put_if_present_op (kv_operations_t *operations, const char *table_name, const kv_row_t *row, kv_return_row_version_enum choice, kv_boolean_t abort_on_failure)
	Creates a putIfPresent operation. More...
kv_error_t	kv_create_table_put_if_version_op (kv_operations_t *operations, const char *table_name, const kv_row_t *row, const kv_version_t *if_version, kv_return_row_version_enum choice, kv_boolean_t abort_on_failure)
	Creates a putIfVersion operation. More...
kv_error_t	kv_create_table_delete_op (kv_operations_t *operations, const char *table_name, const kv_row_t *key, kv_return_row_version_enum choice, kv_boolean_t abort_on_failure)
	Creates a delete operation. More...
kv_error_t	kv_create_table_delete_if_version_op (kv_operations_t *operations, const char *table_name, const kv_row_t *key, const kv_version_t *if_version, kv_return_row_version_enum choice, kv_boolean_t abort_on_failure)
	Creates a deleteIfVersion operation. More...
kv_int_t	kv_operations_size (const kv_operations_t *operations)
	Returns the number of operation in the operations sequence. More...
kv_operation_enum	kv_operation_get_type (const kv_operations_t *operations, kv_int_t index)
	Returns the type of specified table operation in the list. More...
kv_boolean_t	kv_operation_get_abort_on_failure (const kv_operations_t *operations, kv_int_t index)
	Returns whether a failure for the identified operation causes the entire sequence of operations to fail. More...
void	kv_release_operations (kv_operations_t **listp)
	Releases the resouce used by the operations structure. More...
kv_int_t	kv_operation_results_size (const kv_operation_results_t *results)
	Returns the number of results in the results of a group operation execution. More...
kv_result_t *	kv_table_operation_results_get (const kv_operation_results_t *results, kv_int_t index)
	Returns the results of the specified operation. More...
void	kv_release_operation_results (kv_operation_results_t **resultsp)
	Releases the resources used by the operation results structure. More...

Detailed Description

This chapter describes the functions used to manage the grouped table operations and operation execution results.

Function Documentation

kv_operations_t* kv_create_operations

(

)

Creates and initializes an operations structure to hold a sequence of update operations that execute in a single transaction. All of the operations in this structure must shard the same fully-defined shard key in order to operate transactionally.

Operations may not execute in the order specified. Optimal, and correct order of execution is controlled by the system.

Returns

the operations structure that must be freed using kv_release_operations().

kv_error_t kv_create_table_delete_if_version_op	(	kv_operations_t *	operations,
		const char *	table_name,
		const kv_row_t *	key,
		const kv_version_t *	if_version,
		kv_return_row_version_enum	choice,
		kv_boolean_t	abort_on_failure
	)

Creates a deleteIfVersion operation.

Parameters

[in]	operations	The operation sequence to which this operation is appended.
[in]	table_name	The name of the target table.
[in]	key	The primary key used to look up the row to be deleted.
[in]	if_version	The version to match.
[in]	choice	The return row choice, specifies whether to return the row value, version, both or neither.
[in]	abort_on_failure	Indicates whether the entire operation should abort if this operation fails.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_create_table_delete_op	(	kv_operations_t *	operations,
		const char *	table_name,
		const kv_row_t *	key,
		kv_return_row_version_enum	choice,
		kv_boolean_t	abort_on_failure
	)

Creates a delete operation.

Parameters

[in]	operations	The operation sequence to which this operation is appended.
[in]	table_name	The name of the target table.
[in]	key	The primary key used to look up the row to be deleted.
[in]	choice	The return row choice, specifies whether to return the row value, version, both or neither.
[in]	abort_on_failure	Indicates whether the entire operation should abort if this operation fails.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_create_table_put_if_absent_op	(	kv_operations_t *	operations,
		const char *	table_name,
		const kv_row_t *	row,
		kv_return_row_version_enum	choice,
		kv_boolean_t	abort_on_failure
	)

Creates a putIfAbsent operation.

Parameters

[in]	operations	The operation sequence to which this operation is appended.
[in]	table_name	The name of the target table.
[in]	row	The row to be written.
[in]	choice	The return row choice, specifies whether to return the row value, version, both or neither.
[in]	abort_on_failure	Indicates whether the entire operation should abort if this operation fails.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_create_table_put_if_present_op	(	kv_operations_t *	operations,
		const char *	table_name,
		const kv_row_t *	row,
		kv_return_row_version_enum	choice,
		kv_boolean_t	abort_on_failure
	)

Creates a putIfPresent operation.

Parameters

[in]	operations	The operation sequence to which this operation is appended.
[in]	table_name	The name of the target table.
[in]	row	The row to be written.
[in]	choice	The return row choice, specifies whether to return the row value, version, both or neither.
[in]	abort_on_failure	Indicates whether the entire operation should abort if this operation fails.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_create_table_put_if_version_op	(	kv_operations_t *	operations,
		const char *	table_name,
		const kv_row_t *	row,
		const kv_version_t *	if_version,
		kv_return_row_version_enum	choice,
		kv_boolean_t	abort_on_failure
	)

Creates a putIfVersion operation.

Parameters

[in]	operations	The operation sequence to which this operation is appended.
[in]	table_name	The name of the target table.
[in]	row	The row to be written.
[in]	if_version	The version to match.
[in]	choice	The return row choice, specifies whether to return the row value, version, both or neither.
[in]	abort_on_failure	Indicates whether the entire operation should abort if this operation fails.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_create_table_put_op	(	kv_operations_t *	operations,
		const char *	table_name,
		const kv_row_t *	row,
		kv_return_row_version_enum	choice,
		kv_boolean_t	abort_on_failure
	)

Creates a put operation.

Parameters

[in]	operations	The operation sequence to which this operation is appended.
[in]	table_name	The name of the target table.
[in]	row	The row to be written.
[in]	choice	The return row choice, specifies whether to return the row value, version, both or neither.
[in]	abort_on_failure	Indicates whether the entire operation should abort if this operation fails.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_boolean_t kv_operation_get_abort_on_failure	(	const kv_operations_t *	operations,
		kv_int_t	index
	)

Returns whether a failure for the identified operation causes the entire sequence of operations to fail.

Parameters

[in]	operations
[in]	index	An index into the operations list.

Returns

If the entire sequence will fail, then this function returns 1. If the index parameter is out of range, this function returns KV_NO_SUCH_OBJECT.

kv_operation_enum kv_operation_get_type	(	const kv_operations_t *	operations,
		kv_int_t	index
	)

Returns the type of specified table operation in the list.

Parameters

[in]	operations
[in]	index	An index into the operations list.

Returns

the type of the operation, or an error code (a negative number) on if the index is out of range.

kv_int_t kv_operation_results_size

(

const kv_operation_results_t *

results

)

Returns the number of results in the results of a group operation execution.

Parameters

[in]

results

The operation results structure

Returns

the number of results.

kv_error_t kv_operations_set_copy

(

kv_operations_t *

operations

)

Configures a list of operations to copy user-supplied structures and buffers.

Specifies whether to copy, or not user-supplied buffers, strings and structures. By default buffers, text strings, and structures provided to create operation are owned by the application for efficiency.

Parameters

[in]

operations

The operation list

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_operations_set_donate

(

kv_operations_t *

operations

)

Configures the operation list so that keys, rows and versions passed to create operations are donated to the list (owned by the list) and not copied.

In this case these objects are released when the operation list itself is released. By default these objects are owned by the caller. Using this mechanism can save time and memory and user code. This mechanism should not be used when passing objects that may be owned by another object, such as an iterator.

Parameters

[in]

operations

The operation list

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_int_t kv_operations_size

(

const kv_operations_t *

operations

)

Returns the number of operation in the operations sequence.

Parameters

[in]

operations

Returns

the number of operation.

void kv_release_operation_results

(

kv_operation_results_t **

resultsp

)

Releases the resources used by the operation results structure.

Parameters

[in]

resultsp

A pointer to the operations results handle to release.

void kv_release_operations

(

kv_operations_t **

listp

)

Releases the resouce used by the operations structure.

Parameters

[in]

listp

A pointer to the operations handle to release.

kv_result_t* kv_table_operation_results_get	(	const kv_operation_results_t *	results,
		kv_int_t	index
	)

Returns the results of the specified operation.

Parameters

results
index	An index into the results list.

Returns

the result handle is owned by operation results structure and released implicitly when it is released.