API for the SIGMOD 2011 programming contest. More...

Macros
#define	SCDB_MAX_KEY_LENGTH 1024
	Maximum length for keys that must be supported.

#define	SCDB_MAX_VALUE_LENGTH 4096
	Maximum length for values that must be supported.

Typedefs
typedef struct scdb_index	scdb_index
	Opaque type used as a handle to the index (key/value map).

typedef struct scdb_iterator	scdb_iterator
	Opaque type used as a handle for an iteration over the index.

typedef enum scdb_status	scdb_status
	Status code return by SCDB function calls.

Enumerations
enum	scdb_status { SCDB_OK , SCDB_NOT_FOUND , SCDB_KEY_BUFFER_TOO_SMALL , SCDB_VALUE_BUFFER_TOO_SMALL , SCDB_COMPARE_FAILED , SCDB_ERROR }
	Status code return by SCDB function calls. More...

Functions
scdb_index *	scdb_open (size_t max_disk_bytes, const char *disk_path)
	Opens an existing index, or creates one if it does not exist.

void	scdb_close (scdb_index *index)
	Closes an open index.

scdb_status	scdb_read (scdb_index index, const char key, size_t key_length, char value_buffer, size_t value_buffer_length)
	Reads the value corresponding to the specified key (exact match).

scdb_status	scdb_write (scdb_index index, const char key, size_t key_length, const char *value_buffer, size_t value_length)
	Sets the specified key to map to the specified value.

scdb_status	scdb_delete (scdb_index index, const char key, size_t key_length)
	Removes the specified key and associated value from the index.

scdb_status	scdb_cas (scdb_index index, const char key, size_t key_length, const char current_value, size_t current_value_length, const char new_value, size_t new_value_length)
	Performs an atomic compare and swap.

scdb_iterator *	scdb_iterate (scdb_index index, const char key, size_t key_length)
	Create an iterator over the index, starting at the smallest key that is greater than or equal to the provided key.

void	scdb_iterator_close (scdb_iterator *iterator)
	Closes an open iterator.

scdb_status	scdb_next (scdb_iterator iterator, char key_buffer, size_t key_buffer_length, char value_buffer, size_t *value_buffer_length)
	Reads the current key/value pair from the iterator, then advances the iterator.

Detailed Description

API for the SIGMOD 2011 programming contest.

This interface provides a durable, order-preserving, main memory index (key/value map).

Enumeration Type Documentation

◆ scdb_status

enum scdb_status

Status code return by SCDB function calls.

Enumerator
SCDB_OK	Operation completed successfully.
SCDB_NOT_FOUND	The specified key was not found so the operation was not perfomed.
SCDB_KEY_BUFFER_TOO_SMALL	The buffer provided for the key is too small.
SCDB_VALUE_BUFFER_TOO_SMALL	The buffer provided for the value is too small.
SCDB_COMPARE_FAILED	For compare and swap, the current value did not match.
SCDB_ERROR	Some other error occurred.

Function Documentation

◆ scdb_cas()

scdb_status scdb_cas	(	scdb_index *	index,
		const char *	key,
		size_t	key_length,
		const char *	current_value,
		size_t	current_value_length,
		const char *	new_value,
		size_t	new_value_length )

Performs an atomic compare and swap.

If the current value for key matches the provided value, then update the key's value to new_value. The compare and swap occur atomically, each thread can assume that no other thread's updates are applied between the compare and swap operation. This primitive can be used to implement higher-level concurrency control, e.g. locks or validation for optimistic concurrency control.

Parameters

index	the index to modify.
key	pointer to the key bytes.
key_length	length of the key in bytes. Must be <= SCDB_MAX_KEY_LENGTH.
current_value	pointer to the bytes to be compared with the value stored in the index, cannot be NULL.
current_value_length	length of current_value in bytes. Must be <= SCDB_MAX_VALUE_LENGTH.
new_value	pointer to the value to be written if the comparison is successful, cannot be NULL.
new_value_length	length of the new value in bytes, must be >= 0.

Returns: SCDB_OK if the operation is successful, SCDB_NOT_FOUND if the key does not exist, SCDB_COMPARE_FAILED if the stored value does not match current_value, SCDB_ERROR if some other error occurs.

◆ scdb_close()

void scdb_close ( scdb_index * index )

Closes an open index.

This should free all resources associated with index. After this is called, the pointer cannot be used by any thread.

Parameters

index the index to be closed.

◆ scdb_delete()

scdb_status scdb_delete	(	scdb_index *	index,
		const char *	key,
		size_t	key_length )

Removes the specified key and associated value from the index.

After this returns, the delete must be committed and durable.

Parameters

index	the index to modify.
key	pointer to the key bytes.
key_length	length of the key in bytes. Must be <= SCDB_MAX_KEY_LENGTH.

Returns: SCDB_OK if the operation is successful, SCDB_NOT_FOUND if the key does not exist, SCDB_ERROR if some other error occurs.

◆ scdb_iterate()

scdb_iterator * scdb_iterate	(	scdb_index *	index,
		const char *	key,
		size_t	key_length )

Create an iterator over the index, starting at the smallest key that is greater than or equal to the provided key.

The keys are sorted in lexicographical byte order, with bytes treated as 8-bit unsigned integers. For example, the following order is correct: { 0x7f }, { 0x7f, 0x00 }, { 0x80 }. To start at the beginning of the index, pass in a NULL or zero-length key.

Parameters

index	the index to iterate over.
key	pointer to the key bytes.
key_length	length of the key in bytes. Must be <= SCDB_MAX_KEY_LENGTH.

Returns: pointer to an iterator to be used to read values from the index, or NULL if some error occurred.

◆ scdb_iterator_close()

void scdb_iterator_close ( scdb_iterator * iterator )

Closes an open iterator.

The provided iterator pointer cannot be used after calling this.

Parameters

iterator pointer to the iterator to close.

◆ scdb_next()

scdb_status scdb_next	(	scdb_iterator *	iterator,
		char *	key_buffer,
		size_t *	key_buffer_length,
		char *	value_buffer,
		size_t *	value_buffer_length )

Reads the current key/value pair from the iterator, then advances the iterator.

The iterator does not need to be repeatable or isolated with respect to other transactions. The only restriction is that keys must be returned in strictly increasing order, and it must only return committed values.

If there is an error, the iterator is not advanced. If the buffers are too small, the length fields will indicate the length of the data to be returned.

Parameters

	iterator	the iterator to read from.
	key_buffer	pointer to memory where the key will be copied.
[in,out]	key_buffer_length	pointer to the length of value buffer. This will be set to the length of the key in the index.
	value_buffer	pointer to memory where the value will be copied.
[in,out]	value_buffer_length	pointer to the length of value buffer. This will be set to the length of the value in the index.

Returns: SCDB_OK if the operation is successful, SCDB_NOT_FOUND if there are no more keys in the iteration, SCDB_KEY_BUFFER_TOO_SMALL if the key is longer than the provided buffer, SCDB_VALUE_BUFFER_TOO_SMALL if the value is longer than the provided buffer, SCDB_ERROR if some other error occurs.

◆ scdb_open()

scdb_index * scdb_open	(	size_t	max_disk_bytes,
		const char *	disk_path )

Opens an existing index, or creates one if it does not exist.

Any number of files can be used to persist the index, provided that the total amount of space used does not exceed max_disk_bytes. This index must be thread-safe, meaning that it can be passed between multiple threads.

Parameters

max_disk_bytes	the maximum amount of disk space available for durability.
disk_path	the prefix that must be used for storing the non-volatile data.

Returns: pointer to the index that will be passed into all future API calls.

◆ scdb_read()

scdb_status scdb_read	(	scdb_index *	index,
		const char *	key,
		size_t	key_length,
		char *	value_buffer,
		size_t *	value_buffer_length )

Reads the value corresponding to the specified key (exact match).

If the provided buffer is too small, this will return SCDB_VALUE_BUFFER_TOO_SMALL and not copy any bytes into value_buffer. However, value_buffer_length is always set to the full length of the value stored in the index. The value returned must reflect the most recent successfully completed (committed) value, even if that update was performed by another thread.

Parameters

	index	the index to modify.
	key	pointer to the key bytes.
	key_length	length of the key in bytes. Must be <= SCDB_MAX_KEY_LENGTH.
	value_buffer	pointer to memory where the value will be copied, cannot be NULL.
[in,out]	value_buffer_length	pointer to the length of value buffer. This will be set to the length of the value in the index.

Returns: SCDB_OK if the operation is successful, SCDB_NOT_FOUND if the key does not exist, SCDB_VALUE_BUFFER_TOO_SMALL if the value is longer than value_buffer, SCDB_ERROR if some other error occurs.

◆ scdb_write()

scdb_status scdb_write	(	scdb_index *	index,
		const char *	key,
		size_t	key_length,
		const char *	value_buffer,
		size_t	value_length )

Sets the specified key to map to the specified value.

This inserts a new key-value pair or updates the existing key. After this returns, the update must be committed and durable.

Parameters

index	the index to modify.
key	pointer to the key bytes.
key_length	length of the key in bytes. Must be <= SCDB_MAX_KEY_LENGTH.
value_buffer	pointer to the value bytes, cannot be NULL.
value_length	length of the value in bytes. Must be <= SCDB_MAX_VALUE_LENGTH.

Returns: SCDB_OK if the operation is successful, SCDB_ERROR if some other error occurs.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ scdb_status

Function Documentation

◆ scdb_cas()

◆ scdb_close()

◆ scdb_delete()

◆ scdb_iterate()

◆ scdb_iterator_close()

◆ scdb_next()

◆ scdb_open()

◆ scdb_read()

◆ scdb_write()