sds_misc - Man Page

SDS Miscelaneous

enum sds_result { SDS_SUCCESS = 0, SDS_UNKNOWN_ERROR = 1, SDS_NULL_POINTER = 2, SDS_TEST_FAILED = 3, SDS_DUPLICATE_KEY = 4, SDS_CHECKSUM_FAILURE = 5, SDS_INVALID_NODE_ID = 6, SDS_INVALID_KEY = 7, SDS_INVALID_VALUE_SIZE = 8, SDS_INVALID_POINTER = 9, SDS_INVALID_NODE = 10, SDS_INVALID_KEY_ORDER = 11, SDS_RETRY = 12, SDS_KEY_PRESENT = 13, SDS_KEY_NOT_PRESENT = 14, SDS_INCOMPATIBLE_INSTANCE = 15, SDS_LIST_EXHAUSTED = 16, SDS_INVALID_TXN = 17 }

Functions

void * sds_malloc (size_t size)
void * sds_calloc (size_t size)
void * sds_memalign (size_t size, size_t alignment)
void sds_free (void *ptr)
uint32_t sds_crc32c (uint32_t crc, const unsigned char *data, size_t length)
uint64_t sds_siphash13 (const void *src, size_t src_sz, const char key[16])
int64_t sds_uint64_t_compare (void *a, void *b)
void sds_uint64_t_free (void *key)
void * sds_uint64_t_dup (void *key)
int64_t sds_strcmp (void *a, void *b)
void * sds_strdup (void *key)

Detailed Description

Miscelaneous functions for SDS. This may be replaced by a PAL from ns-slapd soon.

Enumeration Type Documentation

enum sds_result

sds_result encapsulates the set of possible success or failures an operation may have during processing. You must always check this value from function calls.

Enumerator

SDS_SUCCESS: SDS_SUCCESS 0 represents that the operation had no errors in processing.
SDS_UNKNOWN_ERROR: SDS_UNKNOWN_ERROR 1 represents that an unexpected issue was encountered, you should raise a bug about this if you encounter it!
SDS_NULL_POINTER: SDS_NULL_POINTER 2 represents that a NULL pointer was provided to a function that expects a true pointer to valid data. It may also represent that the internals of a datastructure have been corrupted with an unexpected NULL pointer, and the operation can not proceed.
SDS_TEST_FAILED: SDS_TEST_FAILED 3 represents that a test case has failed. You may need to go back to the test case to see the originating error.
SDS_DUPLICATE_KEY: SDS_DUPLICATE_KEY 4 represents that the key value already exists in the datastructure. This is generally seen during insertion operations.
SDS_CHECKSUM_FAILURE: SDS_CHECKSUM_FAILURE 5 represents that the in memory data does not pass checksum validation. This may be due to the fault of the application or hardware errors.
SDS_INVALID_NODE_ID: SDS_INVALID_NODE_ID 6 represents that the internal data of a datastructure node contains invalid identifying information.
SDS_INVALID_KEY: SDS_INVALID_KEY 7 represents that a key is invalid in the state of this node. generally this is due to a bug in the datastructure code where keys are out of order, or incorrectly nulled.
SDS_INVALID_VALUE_SIZE: SDS_INVALID_VALUE_SIZE 8 represents that the size of the value provided does not hold true for certain assumptions. For example, a null pointer with a non zero size, or a pointer with a zero size.
SDS_INVALID_POINTER: SDS_INVALID_POINTER 9 represents that within the datastructure an invalid pointer structure has been created that may cause further dataloss or corruption. This could be due to error in the datastructure code, or memory issues.
SDS_INVALID_NODE: SDS_INVALID_NODE 10 represents that certain datastructure properties of this node have not been upheld. For example, branches should never contain data in a b+tree, or that the capacity of the node is incorrect and a split or merge should have occured.
SDS_INVALID_KEY_ORDER: SDS_INVALID_KEY_ORDER 11 indicates that the ordering of keys within a structure is incorrect, and may cause data loss.
SDS_RETRY: SDS_RETRY 12 represents that the previous operation should be attempted again. This is only for INTERNAL use. You will never see this returned.
SDS_KEY_PRESENT: SDS_KEY_PRESENT 13 is a SUCCESS condition, similar to SDS_SUCCESS. This differs from SDS_SUCCESS in that it shows that a key value exists within some datastructure, and you must explcitly check for this case (vs SDS_KEY_NOT_PRESENT).
SDS_KEY_NOT_PRESENT: SDS_KEY_NOT_PRESENT 14 is a SUCCESS condition, similar to SDS_SUCCESS. This differs from SDS_SUCCESS in that is show that a key value does not exist with some datastructure, but the operation was still a SUCCESS in completion. You must explicitly check for this case to ensure you know the true result of a function.
SDS_INCOMPATIBLE_INSTANCE: SDS_INCOMPATIBLE_INSTANCE 15 represents that during a set operation, you are attempting to manipulate datastructures with potentiall different key and value types. This would result in datacorruption or undefined behaviour so instead, we return a pre-emptive error.
SDS_LIST_EXHAUSTED: SDS_LIST_EXHAUSTED 16 represents that there are no more elements in this datastructure to be consumed during an iteration.
SDS_INVALID_TXN: SDS_INVALID_TXN 17 represents that a transaction identifier is invalid for the requested operation. IE using a read only transaction to attempt a write.

Function Documentation

void * sds_calloc (size_t size)

sds_calloc wraps the system calloc call with an OOM check. This call like calloc, guarantees the returned memory is zeroed before usage.

Parameters: size the amount of memory to allocate in bytes.
Return values: pointer to the allocated memory.

uint32_t sds_crc32c (uint32_t crc, const unsigned char * data, size_t length)

sds_crc32c uses the crc32c algorithm to create a verification checksum of data. This checksum is for data verification, not cryptographic purposes. It is used largely in debugging to find cases when bytes in structures are updated incorrectly, or to find memory bit flips during operation. If available, this will use the intel sse4 crc32c hardware acceleration.

Parameters: crc The running CRC value. Initially should be 0. If in doubt, use 0.
data Pointer to the data to checksum.
length number of bytes to validate.
Return values: rcrc The crc of this data. May be re-used in subsequent sds_crc32c calls for certain datatypes.

void sds_free (void * ptr)

sds_free wraps the system free call with a null check.

Parameters: ptr the memory to free.

void * sds_malloc (size_t size)

sds_malloc wraps the system memory allocator with an OOM check. During debugging this call guarantees that memory is zeroed before use.

Parameters: size the amount of memory to allocate in bytes.
Return values: pointer to the allocated memory.

void * sds_memalign (size_t size, size_t alignment)

sds_memalign wraps the posix_memalign function with an OOM and alignment check. During debugging this call guarantees that memory is zeroed before use.

Parameters: size the amount of memory to allocate in bytes.
alignment the size to align to in bytes. Must be a power of 2.
Return values: pointer to the allocated memory.

uint64_t sds_siphash13 (const void * src, size_t src_sz, const char key[16])

sds_siphash13 provides an implementation of the siphash algorithm for use in hash based datastructures. It is chosen due to is resilance against hash attacks, such that it makes it higly secure as a choice for a hashmap.

Parameters: src The data to hash
src_sz The size of the data to hash
key The security key to mix with the hash. This should be randomised once at startup and stored for use with further operations.
Return values: The uint64_t representing the hash of the data.

int64_t sds_strcmp (void * a, void * b)

sds_strcmp exists to wrap the system strcmp call with the correct types needed for libsds datastructures to operate correctly.

Parameters: a Pointer to the first string.
b Pointer to the second string.
Return values: Difference between the values. 0 indicates they are the same.