Base definition of CCS objects and types. More...

#include <limits.h>
#include <math.h>
#include <string.h>

Include dependency graph for base.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	ccs_version_t
	A structure representing a version of the CCS API. More...

union	ccs_numeric_u
	A union that can contain either a ccs_int_t or a ccs_float_t. More...

union	ccs_value_u
	A union that represent a CCS datum value. More...

struct	ccs_datum_s
	A Structure containing a CCS datum. More...

Macros
#define	CCS_TRUE ((ccs_bool_t)(1))
	A macro providing the true value of a ccs_bool_t.

#define	CCS_FALSE ((ccs_bool_t)(0))
	A macro providing the false value of a ccs_bool_t.

#define	CCS_INT_MAX INT64_MAX
	A macro defining the maximum value of a ccs_int_t.

#define	CCS_INT_MIN INT64_MIN
	A macro defining the minimum value of a ccs_int_t.

#define	CCS_INFINITY INFINITY
	A macro defining the (positive) infinity value of a ccs_float_t.

#define	CCSF(v) ((ccs_numeric_t){.f = v})
	A macro casting a value to a CCS floating point numeric.

#define	CCSI(v) ((ccs_numeric_t){.i = v})
	A macro casting a value to a CCS integer numeric.

#define	CCS_NONE_VAL
	A macro defining the none datum value.

#define	CCS_INACTIVE_VAL
	A macro defining the inactive datum value.

#define	CCS_TRUE_VAL
	A macro defining the true boolean datum value.

#define	CCS_FALSE_VAL
	A macro defining the false boolean datum value.

Typedefs
typedef double	ccs_float_t
	A CCS floating point type.

typedef int64_t	ccs_int_t
	A CCS integer type.

typedef int32_t	ccs_bool_t
	A CCS boolean type.

typedef uint32_t	ccs_hash_t
	A CCS hashing value type.

typedef struct _ccs_rng_s *	ccs_rng_t
	An opaque type defining a CCS random generator.

typedef struct _ccs_distribution_s *	ccs_distribution_t
	An opaque type defining a CCS distribution.

typedef struct _ccs_parameter_s *	ccs_parameter_t
	An opaque type defining a CCS parameter.

typedef struct _ccs_expression_s *	ccs_expression_t
	An opaque type defining a CCS expression.

typedef struct _ccs_context_s *	ccs_context_t
	An opaque type defining a CCS context.

typedef struct _ccs_distribution_space_s *	ccs_distribution_space_t
	An opaque type defining a CCS distribution space.

typedef struct _ccs_search_space_s *	ccs_search_space_t
	An opaque type defining a CCS search space.

typedef struct _ccs_configuration_space_s *	ccs_configuration_space_t
	An opaque type defining a CCS configuration space.

typedef struct _ccs_binding_s *	ccs_binding_t
	An opaque type defining a CCS binding.

typedef struct _ccs_search_configuration_s *	ccs_search_configuration_t
	An opaque type defining a CCS search space configuration.

typedef struct _ccs_configuration_s *	ccs_configuration_t
	An opaque type defining a CCS configuration.

typedef struct _ccs_feature_space_s *	ccs_feature_space_t
	An opaque type defining a CCS feature space.

typedef struct _ccs_features_s *	ccs_features_t
	An opaque type defining a CCS features.

typedef struct _ccs_objective_space_s *	ccs_objective_space_t
	An opaque type defining a CCS objective space.

typedef struct _ccs_evaluation_s *	ccs_evaluation_t
	An opaque type defining a CCS evaluation.

typedef struct _ccs_tuner_s *	ccs_tuner_t
	An opaque type defining a CCS tuner.

typedef struct _ccs_map_s *	ccs_map_t
	An opaque type defining a CCS key-value store.

typedef struct _ccs_error_stack_s *	ccs_error_stack_t
	An opaque type defining a CCS error stack.

typedef struct _ccs_tree_s *	ccs_tree_t
	An opaque type defining a CCS tree.

typedef struct _ccs_tree_space_s *	ccs_tree_space_t
	An opaque type defining a CCS tree space.

typedef struct _ccs_tree_configuration_s *	ccs_tree_configuration_t
	An opaque type defining a CCS tree space configuration.

typedef enum ccs_result_e	ccs_result_t
	A commodity type to represent CCS errors and returned by most functions.

typedef int32_t	ccs_evaluation_result_t
	The result type used for evaluations.

typedef enum ccs_object_type_e	ccs_object_type_t
	A commodity type to represent CCS object types.

typedef enum ccs_data_type_e	ccs_data_type_t
	A commodity type to represent CCS data types.

typedef enum ccs_datum_flag_e	ccs_datum_flag_t
	A commodity type to represent CCS datum flags.

typedef uint32_t	ccs_datum_flags_t
	A type representing the combination of flags that can be attached to a CCS datum.

typedef enum ccs_numeric_type_e	ccs_numeric_type_t
	A commodity type to represent CCS numeric types.

typedef void *	ccs_object_t
	A type representing a generic CCS object.

typedef union ccs_numeric_u	ccs_numeric_t
	A commodity type to represent CCS numeric values.

typedef union ccs_value_u	ccs_value_t
	A commodity type to represent a CCS datum value.

typedef struct ccs_datum_s	ccs_datum_t
	A commodity type to represent a CCS datum.

typedef void(*	ccs_object_destroy_callback_t) (ccs_object_t object, void *user_data)
	The type of CCS object destruction callbacks.

typedef ccs_result_t(*	ccs_object_serialize_callback_t) (ccs_object_t object, size_t serialize_data_size, void serialize_data, size_t serialize_data_size_ret, void *callback_user_data)
	The type of CCS object serialization callbacks.

typedef enum ccs_serialize_format_e	ccs_serialize_format_t
	A commodity type to represent CCS serialization formats.

typedef enum ccs_serialize_operation_e	ccs_serialize_operation_t
	A commodity type to represent CCS serialization operations.

typedef enum ccs_deserialize_operation_e	ccs_deserialize_operation_t
	A commodity type to represent CCS deserialization operations.

typedef enum ccs_serialize_option_e	ccs_serialize_option_t
	A commodity type to represent CCS serialization options.

typedef ccs_result_t(*	ccs_object_deserialize_data_callback_t) (ccs_object_t object, size_t serialize_data_size, const char serialize_data, void callback_user_data)
	The type of CCS object data deserialization callbacks.

typedef ccs_result_t(*	ccs_object_deserialize_vector_callback_t) (ccs_object_type_t type, const char name, void callback_user_data, void vector_ret, void data_ret)
	The type of CCS user object vector deserialization callbacks.

typedef enum ccs_deserialize_option_e	ccs_deserialize_option_t
	A commodity type to represent CCS deserialization options.

Enumerations
enum	ccs_result_e { CCS_RESULT_MAX = 2 , CCS_RESULT_AGAIN = 1 , CCS_RESULT_SUCCESS = 0 , CCS_RESULT_ERROR_INVALID_OBJECT = -1 , CCS_RESULT_ERROR_INVALID_VALUE = -2 , CCS_RESULT_ERROR_INVALID_TYPE = -3 , CCS_RESULT_ERROR_INVALID_SCALE = -4 , CCS_RESULT_ERROR_INVALID_DISTRIBUTION = -5 , CCS_RESULT_ERROR_INVALID_EXPRESSION = -6 , CCS_RESULT_ERROR_INVALID_PARAMETER = -7 , CCS_RESULT_ERROR_INVALID_CONFIGURATION = -8 , CCS_RESULT_ERROR_INVALID_NAME = -9 , CCS_RESULT_ERROR_INVALID_CONDITION = -10 , CCS_RESULT_ERROR_INVALID_TUNER = -11 , CCS_RESULT_ERROR_INVALID_GRAPH = -12 , CCS_RESULT_ERROR_TYPE_NOT_COMPARABLE = -13 , CCS_RESULT_ERROR_INVALID_BOUNDS = -14 , CCS_RESULT_ERROR_OUT_OF_BOUNDS = -15 , CCS_RESULT_ERROR_SAMPLING_UNSUCCESSFUL = -16 , CCS_RESULT_ERROR_OUT_OF_MEMORY = -17 , CCS_RESULT_ERROR_UNSUPPORTED_OPERATION = -18 , CCS_RESULT_ERROR_INVALID_EVALUATION = -19 , CCS_RESULT_ERROR_INVALID_FEATURES = -20 , CCS_RESULT_ERROR_INVALID_FILE_PATH = -21 , CCS_RESULT_ERROR_NOT_ENOUGH_DATA = -22 , CCS_RESULT_ERROR_DUPLICATE_HANDLE = -23 , CCS_RESULT_ERROR_INVALID_HANDLE = -24 , CCS_RESULT_ERROR_SYSTEM = -25 , CCS_RESULT_ERROR_EXTERNAL = -26 , CCS_RESULT_ERROR_INVALID_TREE = -27 , CCS_RESULT_ERROR_INVALID_TREE_SPACE = -28 , CCS_RESULT_ERROR_INVALID_DISTRIBUTION_SPACE = -29 , CCS_RESULT_MIN = -30 , CCS_RESULT_FORCE_32BIT = INT32_MAX }
	The different possible return codes of a CCS function. More...

enum	ccs_object_type_e { CCS_OBJECT_TYPE_RNG , CCS_OBJECT_TYPE_DISTRIBUTION , CCS_OBJECT_TYPE_PARAMETER , CCS_OBJECT_TYPE_EXPRESSION , CCS_OBJECT_TYPE_CONFIGURATION_SPACE , CCS_OBJECT_TYPE_CONFIGURATION , CCS_OBJECT_TYPE_OBJECTIVE_SPACE , CCS_OBJECT_TYPE_EVALUATION , CCS_OBJECT_TYPE_TUNER , CCS_OBJECT_TYPE_FEATURE_SPACE , CCS_OBJECT_TYPE_FEATURES , CCS_OBJECT_TYPE_MAP , CCS_OBJECT_TYPE_ERROR_STACK , CCS_OBJECT_TYPE_TREE , CCS_OBJECT_TYPE_TREE_SPACE , CCS_OBJECT_TYPE_TREE_CONFIGURATION , CCS_OBJECT_TYPE_DISTRIBUTION_SPACE , CCS_OBJECT_TYPE_MAX , CCS_OBJECT_TYPE_FORCE_32BIT = INT32_MAX }
	CCS object types. More...

enum	ccs_data_type_e { CCS_DATA_TYPE_NONE , CCS_DATA_TYPE_INT , CCS_DATA_TYPE_FLOAT , CCS_DATA_TYPE_BOOL , CCS_DATA_TYPE_STRING , CCS_DATA_TYPE_INACTIVE , CCS_DATA_TYPE_OBJECT , CCS_DATA_TYPE_MAX , CCS_DATA_TYPE_FORCE_32BIT = INT32_MAX }
	CCS supported data types. More...

enum	ccs_datum_flag_e { CCS_DATUM_FLAG_DEFAULT = 0 , CCS_DATUM_FLAG_TRANSIENT = (1 << 0) , CCS_DATUM_FLAG_UNPOOLED = (1 << 1) , CCS_DATUM_FLAG_ID = (1 << 2) , CCS_DATUM_FLAG_FORCE_32BIT = INT32_MAX }
	Flags that can be attached to a CCS datum. More...

enum	ccs_numeric_type_e { CCS_NUMERIC_TYPE_INT = CCS_DATA_TYPE_INT , CCS_NUMERIC_TYPE_FLOAT = CCS_DATA_TYPE_FLOAT , CCS_NUMERIC_TYPE_MAX , CCS_NUMERIC_TYPE_FORCE_32BIT = INT32_MAX }
	The subset of CCS data types that represent numerical data. More...

enum	ccs_serialize_format_e { CCS_SERIALIZE_FORMAT_BINARY , CCS_SERIALIZE_FORMAT_MAX , CCS_SERIALIZE_FORMAT_FORCE_32BIT = INT32_MAX }
	The different serialization formats supported by CCS. More...

enum	ccs_serialize_operation_e { CCS_SERIALIZE_OPERATION_SIZE , CCS_SERIALIZE_OPERATION_MEMORY , CCS_SERIALIZE_OPERATION_FILE , CCS_SERIALIZE_OPERATION_FILE_DESCRIPTOR , CCS_SERIALIZE_OPERATION_MAX , CCS_SERIALIZE_OPERATION_FORCE_32BIT = INT32_MAX }
	The different serialization operations supported by CCS. More...

enum	ccs_deserialize_operation_e { CCS_DESERIALIZE_OPERATION_MEMORY , CCS_DESERIALIZE_OPERATION_FILE , CCS_DESERIALIZE_OPERATION_FILE_DESCRIPTOR , CCS_DESERIALIZE_OPERATION_MAX , CCS_DESERIALIZE_OPERATION_FORCE_32BIT = INT32_MAX }
	CCS deserialization operations. More...

enum	ccs_serialize_option_e { CCS_SERIALIZE_OPTION_END = 0 , CCS_SERIALIZE_OPTION_NON_BLOCKING , CCS_SERIALIZE_OPTION_CALLBACK , CCS_SERIALIZE_OPTION_MAX , CCS_SERIALIZE_OPTION_FORCE_32BIT = INT32_MAX }
	The different serialization options. More...

enum	ccs_deserialize_option_e { CCS_DESERIALIZE_OPTION_END = 0 , CCS_DESERIALIZE_OPTION_HANDLE_MAP , CCS_DESERIALIZE_OPTION_MAP_HANDLES , CCS_DESERIALIZE_OPTION_VECTOR_CALLBACK , CCS_DESERIALIZE_OPTION_NON_BLOCKING , CCS_DESERIALIZE_OPTION_DATA_CALLBACK , CCS_DESERIALIZE_OPTION_MAX , CCS_DESERIALIZE_OPTION_FORCE_32BIT = INT32_MAX }
	The different deserialization options. More...

Functions
static ccs_datum_t	ccs_bool (ccs_bool_t v)
	A helper function to construct a datum containing a boolean value.

static ccs_datum_t	ccs_float (ccs_float_t v)
	A helper function to construct a datum containing a floating point value.

static ccs_datum_t	ccs_int (ccs_int_t v)
	A helper function to construct a datum containing an integer value.

static ccs_datum_t	ccs_object (ccs_object_t v)
	A helper function to construct a datum containing a CCS object value.

static ccs_datum_t	ccs_string (const char *v)
	A helper function to construct a datum containing a string value.

static int	ccs_datum_cmp (const ccs_datum_t a, const ccs_datum_t b)
	A helper function providing a strict ordering of datum.

ccs_result_t	ccs_init (void)
	The library initialization function.

ccs_result_t	ccs_fini (void)
	The library deinitialization function.

ccs_result_t	ccs_get_result_name (ccs_result_t result, const char **name)
	Return the string corresponding to the provided CCS result.

ccs_version_t	ccs_get_version (void)
	Query the library API version.

const char *	ccs_get_version_string (void)
	Query the library version string.

ccs_result_t	ccs_retain_object (ccs_object_t object)
	Retain a CCS object, incrementing the internal reference counting.

ccs_result_t	ccs_release_object (ccs_object_t object)
	Release a CCS object, decrementing the internal reference counting.

ccs_result_t	ccs_object_get_type (ccs_object_t object, ccs_object_type_t *type_ret)
	Get a CCS object type.

ccs_result_t	ccs_object_get_refcount (ccs_object_t object, int32_t *refcount_ret)
	Get an object internal reference counting.

ccs_result_t	ccs_object_set_destroy_callback (ccs_object_t object, ccs_object_destroy_callback_t callback, void *user_data)
	Attach a destruction callback to a CCS object.

ccs_result_t	ccs_object_set_user_data (ccs_object_t object, void *user_data)
	Set the associated `user_data` pointer of a CCS object.

ccs_result_t	ccs_object_get_user_data (ccs_object_t object, void **user_data_ret)
	Get the associated `user_data` pointer of a CCS object.

ccs_result_t	ccs_object_set_serialize_callback (ccs_object_t object, ccs_object_serialize_callback_t callback, void *user_data)
	Set the object serialization callback.

ccs_result_t	ccs_object_serialize (ccs_object_t object, ccs_serialize_format_t format, ccs_serialize_operation_t operation,...)
	Perform a serialization operation on a CCS object.

ccs_result_t	ccs_object_deserialize (ccs_object_t *object_ret, ccs_serialize_format_t format, ccs_deserialize_operation_t operation,...)
	Perform a deserialization operation and return a new CCS object.

Variables
const ccs_version_t	ccs_version
	A variable containing the current version of the CCS library.

const ccs_datum_t	ccs_none
	A variable containing an empty datum.

const ccs_datum_t	ccs_inactive
	A variable containing an inactive datum.

const ccs_datum_t	ccs_true
	A variable containing a boolean true datum.

const ccs_datum_t	ccs_false
	A variable containing a boolean false datum.

Detailed Description

Base definition of CCS objects and types.

Remarks: A note on thread safety: many objects in CCS are either immutable or their inner state is protected, so many calls to the API are thread safe as long as the thread holds a valid reference to a CCS object. Some CCS objects (tree APIs) are not immutable and functions modifying their inner state are generally not thread safe. When a function on a complex object is marked thread safe, it means thread safe as long as no thread unsafe function is used concurrently on the same object. CCS has no global state, so not thread safe means a function cannot be used simultaneously with other functions modifying or reading the same object state.

Macro Definition Documentation

◆ CCS_FALSE_VAL

#define CCS_FALSE_VAL

Value:

    {                                                                      \
        {.i = CCS_FALSE}, CCS_DATA_TYPE_BOOL, CCS_DATUM_FLAG_DEFAULT   \
    }

A macro defining the false boolean datum value.

◆ CCS_INACTIVE_VAL

#define CCS_INACTIVE_VAL

Value:

    {                                                                      \
        {0}, CCS_DATA_TYPE_INACTIVE, CCS_DATUM_FLAG_DEFAULT            \
    }

A macro defining the inactive datum value.

◆ CCS_NONE_VAL

#define CCS_NONE_VAL

Value:

    {                                                                      \
        {0}, CCS_DATA_TYPE_NONE, CCS_DATUM_FLAG_DEFAULT                \
    }

A macro defining the none datum value.

◆ CCS_TRUE_VAL

#define CCS_TRUE_VAL

Value:

    {                                                                      \
        {.i = CCS_TRUE}, CCS_DATA_TYPE_BOOL, CCS_DATUM_FLAG_DEFAULT    \
    }

A macro defining the true boolean datum value.

Typedef Documentation

◆ ccs_object_deserialize_data_callback_t

typedef ccs_result_t(* ccs_object_deserialize_data_callback_t) (ccs_object_t object, size_t serialize_data_size, const char *serialize_data, void *callback_user_data)

The type of CCS object data deserialization callbacks.

This callback is used to deserialize object data information that were created by the serialization callback.

Parameters

[in,out]	object	a CCS object
[in]	serialize_data_size	the size of the memory pointed to by `serialize_data`
[in]	serialize_data	a pointer to a memory area of size `serialize_data_size`. Can be NULL when `serialize_data_size` is zero
[in]	callback_user_data	the pointer provided when the callback was attached.

Returns: CCS_RESULT_SUCCESS on success; an error code on error

Remarks: This function must be thread-safe for serialization to be thread safe.

◆ ccs_object_deserialize_vector_callback_t

typedef ccs_result_t(* ccs_object_deserialize_vector_callback_t) (ccs_object_type_t type, const char *name, void *callback_user_data, void **vector_ret, void **data_ret)

The type of CCS user object vector deserialization callbacks.

This callback is used to obtain the vector to use for a user defined object.

Parameters

[in]	type	the type of CCS object for which the vector is required
[in]	name	the name of the object as it was orignally provided at creation
[in]	callback_user_data	the pointer provided when the callback was attached.
[out]	vector_ret	a pointer that will hold the returned pointer to the vector structure
[out]	data_ret	a pointer that will optionally hold the user data value to use when initializing the user object. If the provided vector holds the relevant deserialization callback, this value will be ignored.

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_TYPE if the object type is not expected by the callback; CCS_RESULT_ERROR_INVALID_NAME if the object name is not recognized

Remarks: This function must be thread-safe for deserialization to be thread safe.

◆ ccs_object_serialize_callback_t

typedef ccs_result_t(* ccs_object_serialize_callback_t) (ccs_object_t object, size_t serialize_data_size, void *serialize_data, size_t *serialize_data_size_ret, void *callback_user_data)

The type of CCS object serialization callbacks.

This callback is used to serialize object information that CCS is not aware of, the most glaring example being the object associated user_data.

Parameters

[in]	object	a CCS object
[in]	serialize_data_size	the size of the memory pointed to by `serialize_data`, can be zero when querying the size
[out]	serialize_data	a pointer to a memory area of size `serialize_data_size`. Can be NULL when `serialize_data_size` is zero
[out]	serialize_data_size_ret	a pointer to the variable that will contain the required user size to serialize the object.
[in]	callback_user_data	the pointer provided when the callback was attached.

Returns: CCS_RESULT_SUCCESS on success; an error code on error

Remarks: This function must be thread-safe for serialization to be thread safe.

Enumeration Type Documentation

◆ ccs_data_type_e

enum ccs_data_type_e

CCS supported data types.

Enumerator
CCS_DATA_TYPE_NONE	An empty value.
CCS_DATA_TYPE_INT	A ccs_int_t.
CCS_DATA_TYPE_FLOAT	ccs_float_t
CCS_DATA_TYPE_BOOL	ccs_bool_t
CCS_DATA_TYPE_STRING	A pointer to a NULL terminated string.
CCS_DATA_TYPE_INACTIVE	An inactive value.
CCS_DATA_TYPE_OBJECT	A CCS object.
CCS_DATA_TYPE_MAX	Guard.
CCS_DATA_TYPE_FORCE_32BIT	Try forcing 32 bits value for bindings.

◆ ccs_datum_flag_e

enum ccs_datum_flag_e

Flags that can be attached to a CCS datum.

Enumerator
CCS_DATUM_FLAG_DEFAULT	Empty default flags.
CCS_DATUM_FLAG_TRANSIENT	The value given to CCS is a pointer and is not guaranteed to stay allocated.
CCS_DATUM_FLAG_UNPOOLED	The value returned by CCS is a pointer and is not associated to a CCS object and needs to be freed by the user (unused).
CCS_DATUM_FLAG_ID	The object handle is just an identifier.
CCS_DATUM_FLAG_FORCE_32BIT	Try forcing 32 bits value for bindings.

◆ ccs_deserialize_operation_e

enum ccs_deserialize_operation_e

CCS deserialization operations.

Enumerator
CCS_DESERIALIZE_OPERATION_MEMORY	Deserialize the object from a user provided memory buffer.
CCS_DESERIALIZE_OPERATION_FILE	Deserialize the object from a file at the given path.
CCS_DESERIALIZE_OPERATION_FILE_DESCRIPTOR	Deserialize the object from the given file descriptor.
CCS_DESERIALIZE_OPERATION_MAX	Guard.
CCS_DESERIALIZE_OPERATION_FORCE_32BIT	Try forcing 32 bits value for bindings.

◆ ccs_deserialize_option_e

enum ccs_deserialize_option_e

The different deserialization options.

Enumerator
CCS_DESERIALIZE_OPTION_END	Option list terminator.
CCS_DESERIALIZE_OPTION_HANDLE_MAP	The next parameter is a ccs_handle_map_t object that must contain the mappings required to deserialize an object (usually bindings or expressions).
CCS_DESERIALIZE_OPTION_MAP_HANDLES	Secifies that handles have to be mapped. If given, CCS_DESERIALIZE_OPTION_HANDLE_MAP must be set and the given map will be updated to contain the mapping between serialized object handles and deserialized object handles.
CCS_DESERIALIZE_OPTION_VECTOR_CALLBACK	The next parameter is a pointer to a callback of type ccs_object_deserialize_vector_callback_t and its user data, that will return the ccs object vector struct, for user defined objects.
CCS_DESERIALIZE_OPTION_NON_BLOCKING	The file descriptor operation is non-blocking. The next parameter is a pointer to a void * variable (initialized to NULL) that will hold the state of the serialization in order to restart. The function performing the operation will return CCS_RESULT_AGAIN if the operation has not completed. The state is managed internally.
CCS_DESERIALIZE_OPTION_DATA_CALLBACK	The next parameters are a deserialization callback and its user_data. This callback will be called for all objects that had their user_data serialized. If no such callback is provided the object's user_data value will not be set.
CCS_DESERIALIZE_OPTION_MAX	Guard.
CCS_DESERIALIZE_OPTION_FORCE_32BIT	Try forcing 32 bits value for bindings.

◆ ccs_numeric_type_e

enum ccs_numeric_type_e

The subset of CCS data types that represent numerical data.

Enumerator
CCS_NUMERIC_TYPE_INT	A ccs_int_t.
CCS_NUMERIC_TYPE_FLOAT	A ccs_float_t.
CCS_NUMERIC_TYPE_MAX	Guard.
CCS_NUMERIC_TYPE_FORCE_32BIT	Try forcing 32 bits value for bindings.

◆ ccs_object_type_e

enum ccs_object_type_e

CCS object types.

Enumerator
CCS_OBJECT_TYPE_RNG	A random number generator.
CCS_OBJECT_TYPE_DISTRIBUTION	A numerical distribution.
CCS_OBJECT_TYPE_PARAMETER	A parameter.
CCS_OBJECT_TYPE_EXPRESSION	An arithmetic expression.
CCS_OBJECT_TYPE_CONFIGURATION_SPACE	A configuration space.
CCS_OBJECT_TYPE_CONFIGURATION	A configuration.
CCS_OBJECT_TYPE_OBJECTIVE_SPACE	An objective space.
CCS_OBJECT_TYPE_EVALUATION	An evaluation of a configuration.
CCS_OBJECT_TYPE_TUNER	A tuner.
CCS_OBJECT_TYPE_FEATURE_SPACE	A feature space.
CCS_OBJECT_TYPE_FEATURES	A set of features.
CCS_OBJECT_TYPE_MAP	A key value store.
CCS_OBJECT_TYPE_ERROR_STACK	An error stack.
CCS_OBJECT_TYPE_TREE	A tree structure.
CCS_OBJECT_TYPE_TREE_SPACE	A tree space.
CCS_OBJECT_TYPE_TREE_CONFIGURATION	A configuration on a tree space.
CCS_OBJECT_TYPE_DISTRIBUTION_SPACE	A distribution space.
CCS_OBJECT_TYPE_MAX	Guard.
CCS_OBJECT_TYPE_FORCE_32BIT	Try forcing 32 bits value for bindings.

◆ ccs_result_e

enum ccs_result_e

The different possible return codes of a CCS function.

Error codes are returned negated.

Enumerator
CCS_RESULT_MAX	Guard.
CCS_RESULT_AGAIN	Try again.
CCS_RESULT_SUCCESS	Success.
CCS_RESULT_ERROR_INVALID_OBJECT	Not a CCS object or not initialized.
CCS_RESULT_ERROR_INVALID_VALUE	Parameter has an invalid value.
CCS_RESULT_ERROR_INVALID_TYPE	The data type is invalid.
CCS_RESULT_ERROR_INVALID_SCALE	The provided scale is invalid.
CCS_RESULT_ERROR_INVALID_DISTRIBUTION	The provided distribution is invalid.
CCS_RESULT_ERROR_INVALID_EXPRESSION	The provided expression is invalid.
CCS_RESULT_ERROR_INVALID_PARAMETER	The provided parameter is invalid.
CCS_RESULT_ERROR_INVALID_CONFIGURATION	The provided configuration is invalid.
CCS_RESULT_ERROR_INVALID_NAME	The parameter name is invalid.
CCS_RESULT_ERROR_INVALID_CONDITION	The condition is invalid (unused)
CCS_RESULT_ERROR_INVALID_TUNER	The provided tuner is invalid.
CCS_RESULT_ERROR_INVALID_GRAPH	The constraint graph would be invalid.
CCS_RESULT_ERROR_TYPE_NOT_COMPARABLE	The type is not comparable (unused)
CCS_RESULT_ERROR_INVALID_BOUNDS	The bounds are invalid (unused)
CCS_RESULT_ERROR_OUT_OF_BOUNDS	The index is out of bounds.
CCS_RESULT_ERROR_SAMPLING_UNSUCCESSFUL	Could not gather enough samples.
CCS_RESULT_ERROR_OUT_OF_MEMORY	An allocation failed due to lack of available memory.
CCS_RESULT_ERROR_UNSUPPORTED_OPERATION	The object does not support this operation.
CCS_RESULT_ERROR_INVALID_EVALUATION	The provided evaluation is invalid.
CCS_RESULT_ERROR_INVALID_FEATURES	The provided features is invalid.
CCS_RESULT_ERROR_INVALID_FILE_PATH	The provided file path is invalid.
CCS_RESULT_ERROR_NOT_ENOUGH_DATA	The provided buffer or file is too short.
CCS_RESULT_ERROR_DUPLICATE_HANDLE	The handle was a duplicate.
CCS_RESULT_ERROR_INVALID_HANDLE	The handle was not found.
CCS_RESULT_ERROR_SYSTEM	A system error occurred.
CCS_RESULT_ERROR_EXTERNAL	External error occurred (binding?)
CCS_RESULT_ERROR_INVALID_TREE	The provided tree is invalid.
CCS_RESULT_ERROR_INVALID_TREE_SPACE	The provided tree space is invalid.
CCS_RESULT_ERROR_INVALID_DISTRIBUTION_SPACE	The provided tree tuner is invalid.
CCS_RESULT_MIN	Guard.
CCS_RESULT_FORCE_32BIT	Try forcing 32 bits value for bindings.

◆ ccs_serialize_format_e

enum ccs_serialize_format_e

The different serialization formats supported by CCS.

Enumerator
CCS_SERIALIZE_FORMAT_BINARY	A binary format that should be compact and performant.
CCS_SERIALIZE_FORMAT_MAX	Guard.
CCS_SERIALIZE_FORMAT_FORCE_32BIT	Try forcing 32 bits value for bindings.

◆ ccs_serialize_operation_e

enum ccs_serialize_operation_e

The different serialization operations supported by CCS.

Enumerator
CCS_SERIALIZE_OPERATION_SIZE	Query the memory footprint of the serialized object.
CCS_SERIALIZE_OPERATION_MEMORY	Serialize the object in a user provided memory buffer.
CCS_SERIALIZE_OPERATION_FILE	Serialize the object in a file at the given path.
CCS_SERIALIZE_OPERATION_FILE_DESCRIPTOR	Serialize the ojbect in the given file descriptor.
CCS_SERIALIZE_OPERATION_MAX	Guard.
CCS_SERIALIZE_OPERATION_FORCE_32BIT	Try forcing 32 bits value for bindings.

◆ ccs_serialize_option_e

enum ccs_serialize_option_e

The different serialization options.

Enumerator
CCS_SERIALIZE_OPTION_END	Option list terminator.
CCS_SERIALIZE_OPTION_NON_BLOCKING	The file descriptor operation is non-blocking. The next parameter is a pointer to a void * variable (initialized to NULL) that will hold the state of the serialization in order to restart. The function performing the operation will return CCS_RESULT_AGAIN if the operation has not completed. The state is managed internally.
CCS_SERIALIZE_OPTION_CALLBACK	The next parameters are a serialization callback and it's user_data. This callback will be called for all objects that have user_data set and have not a serialization callback set via ccs_object_set_serialize_callback
CCS_SERIALIZE_OPTION_MAX	Guard.
CCS_SERIALIZE_OPTION_FORCE_32BIT	Try forcing 32 bits value for bindings.

Function Documentation

◆ ccs_bool()

static ccs_datum_t ccs_bool ( ccs_bool_t v )

inlinestatic

A helper function to construct a datum containing a boolean value.

Parameters

[in] v CCS_TRUE or CCS_FALSE

Returns: a CCS datum value

◆ ccs_datum_cmp()

static int ccs_datum_cmp	(	const ccs_datum_t	a,
		const ccs_datum_t	b
	)

inlinestatic

A helper function providing a strict ordering of datum.

Flags are not taken into account.

Parameters

[in]	a	the first datum
[in]	b	the second datum

Returns: -1, 0, or 1 if the first datum is found to be respectively lesser than, equal, or greater than the second datum

◆ ccs_fini()

ccs_result_t ccs_fini ( void )

extern

The library deinitialization function.

When done using the library, should be called once for each time ccs_init was called.

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_VALUE if the library reference count is found to be invalid

Remarks: This function is thread-safe

◆ ccs_float()

static ccs_datum_t ccs_float ( ccs_float_t v )

inlinestatic

A helper function to construct a datum containing a floating point value.

Parameters

[in] v a floating point value.

Returns: a CCS datum value

◆ ccs_get_result_name()

ccs_result_t ccs_get_result_name	(	ccs_result_t	result,
		const char **	name
	)

extern

Return the string corresponding to the provided CCS result.

Parameters

[in]	result	the CCS result
[out]	name	a pointer to a variable that will contain the string representation of the result name.

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_VALUE if name is NULL or if error is not a valid CCS result code

Remarks: This function is thread-safe

◆ ccs_get_version()

ccs_version_t ccs_get_version ( void )

extern

Query the library API version.

Returns: the library API version

Remarks: This function is thread-safe

◆ ccs_get_version_string()

const char * ccs_get_version_string ( void )

extern

Query the library version string.

Returns: the library version string

Remarks: This function is thread-safe

◆ ccs_init()

ccs_result_t ccs_init ( void )

extern

The library initialization function.

The library usage is ref counted, so this function can be called several times.

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_VALUE if the library reference count is found to be invalid

Remarks: This function is thread-safe

◆ ccs_int()

static ccs_datum_t ccs_int ( ccs_int_t v )

inlinestatic

A helper function to construct a datum containing an integer value.

Parameters

[in] v a signed integer.

Returns: a CCS datum value

◆ ccs_object()

static ccs_datum_t ccs_object ( ccs_object_t v )

inlinestatic

A helper function to construct a datum containing a CCS object value.

Parameters

[in] v a CCS object.

Returns: a CCS datum value

◆ ccs_object_deserialize()

ccs_result_t ccs_object_deserialize	(	ccs_object_t *	object_ret,
		ccs_serialize_format_t	format,
		ccs_deserialize_operation_t	operation,
			...
	)

extern

Perform a deserialization operation and return a new CCS object.

Parameters

[out]	object_ret	a pointer to the variable that will hold the newly created CCS object
[in]	format	the requested serialization format (currently only CCS_SERIALIZE_FORMAT_BINARY is supported)
[in]	operation	the requested deserialization operation
[in,out]	...	operation-specific parameters followed by a CCS_DESERIALIZE_OPTION_END terminated list of options.

The variadic parameters depend on the selected operation:

CCS_DESERIALIZE_OPERATION_MEMORY: a size_t buffer size followed by a const char* buffer containing the serialized data.
CCS_DESERIALIZE_OPERATION_FILE: a const char* file path to read from.
CCS_DESERIALIZE_OPERATION_FILE_DESCRIPTOR: an int file descriptor open for reading.

After the operation-specific parameters, pass a list of options terminated by CCS_DESERIALIZE_OPTION_END:

CCS_DESERIALIZE_OPTION_HANDLE_MAP: followed by a ccs_map_t that contains mappings from serialized object handles to live objects. Required when deserializing objects that reference other objects (e.g. configurations referencing a configuration space).
CCS_DESERIALIZE_OPTION_MAP_HANDLES: no additional parameter. Requires CCS_DESERIALIZE_OPTION_HANDLE_MAP to be set. The handle map will be updated with a mapping from the serialized handle to the newly created object, enabling subsequent deserializations to reference it.
CCS_DESERIALIZE_OPTION_VECTOR_CALLBACK: followed by a ccs_object_deserialize_vector_callback_t callback and a void* user_data. Required when deserializing user-defined objects (e.g. user-defined tuners) to provide the operation vector.
CCS_DESERIALIZE_OPTION_DATA_CALLBACK: followed by a ccs_object_deserialize_data_callback_t callback and a void* user_data. Called for objects whose user_data was serialized, allowing the caller to restore application-specific state.
CCS_DESERIALIZE_OPTION_NON_BLOCKING: (file descriptor operation only) followed by a void** state pointer (initialized to NULL). The function returns CCS_RESULT_AGAIN if the operation has not completed; call again with the same state pointer to continue.

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_VALUE if object_ret is NULL; or if parameters and option combination are unsupported; CCS_RESULT_ERROR_INVALID_FILE_PATH if the file path cannot be opened or memory-mapped; CCS_RESULT_ERROR_OUT_OF_MEMORY if required memory could not be allocated; CCS_RESULT_ERROR_NOT_ENOUGH_DATA if the provided buffer is too small for the requested operation; CCS_RESULT_ERROR_SYSTEM if a system call fails; CCS_RESULT_AGAIN if the non-blocking file descriptor operation is incomplete

Remarks: This function is thread-safe as long as object deserialization callbacks are thread safe.

◆ ccs_object_get_refcount()

ccs_result_t ccs_object_get_refcount	(	ccs_object_t	object,
		int32_t *	refcount_ret
	)

extern

Get an object internal reference counting.

Parameters

[in]	object	a CCS object
[out]	refcount_ret	a pointer to a int32_t variable that will contain the refcount

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if object is found to be invalid; CCS_RESULT_ERROR_INVALID_VALUE if refcount_ret is NULL

Remarks: This function is thread-safe. The reference count returned is for informational purpose only and must not be relied on.

◆ ccs_object_get_type()

ccs_result_t ccs_object_get_type	(	ccs_object_t	object,
		ccs_object_type_t *	type_ret
	)

extern

Get a CCS object type.

Parameters

[in]	object	a CCS object
[out]	type_ret	a pointer to a ccs_object_type_t variable that will contain the type

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if the object is found to be invalid; CCS_RESULT_ERROR_INVALID_VALUE if type_ret is NULL

Remarks: This function is thread-safe

◆ ccs_object_get_user_data()

ccs_result_t ccs_object_get_user_data	(	ccs_object_t	object,
		void **	user_data_ret
	)

extern

Get the associated user_data pointer of a CCS object.

Parameters

[in]	object	a CCS object
[out]	user_data_ret	a pointer to a `void *` variable that will contain the value of the `user_data`

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if object is found to be invalid; CCS_RESULT_ERROR_INVALID_VALUE if user_data_ret is NULL

Remarks: This function is thread-safe

◆ ccs_object_serialize()

ccs_result_t ccs_object_serialize	(	ccs_object_t	object,
		ccs_serialize_format_t	format,
		ccs_serialize_operation_t	operation,
			...
	)

extern

Perform a serialization operation on a CCS object.

Parameters

[in]	object	a CCS object
[in]	format	the requested serialization format (currently only CCS_SERIALIZE_FORMAT_BINARY is supported)
[in]	operation	the requested serialization operation
[in,out]	...	operation-specific parameters followed by a CCS_SERIALIZE_OPTION_END terminated list of options.

The variadic parameters depend on the selected operation:

CCS_SERIALIZE_OPERATION_SIZE: a size_t* that will receive the required buffer size.
CCS_SERIALIZE_OPERATION_MEMORY: a size_t buffer size followed by a char* buffer to write the serialized data into.
CCS_SERIALIZE_OPERATION_FILE: a const char* file path. The file is created (or truncated) with permissions 0664.
CCS_SERIALIZE_OPERATION_FILE_DESCRIPTOR: an int file descriptor open for writing.

After the operation-specific parameters, pass a list of options terminated by CCS_SERIALIZE_OPTION_END:

CCS_SERIALIZE_OPTION_CALLBACK: followed by a ccs_object_serialize_callback_t callback and a void* user_data. This callback is called for objects that have user_data set and do not have a per-object serialization callback registered via ccs_object_set_serialize_callback().
CCS_SERIALIZE_OPTION_NON_BLOCKING: (file descriptor operation only) followed by a void** state pointer (initialized to NULL). The function returns CCS_RESULT_AGAIN if the operation has not completed; call again with the same state pointer to continue.

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if object is found to be invalid; CCS_RESULT_ERROR_INVALID_VALUE if parameters and option combination are unsupported; CCS_RESULT_ERROR_INVALID_FILE_PATH if the file path cannot be opened or memory-mapped; CCS_RESULT_ERROR_OUT_OF_MEMORY if required memory could not be allocated; CCS_RESULT_ERROR_NOT_ENOUGH_DATA if the provided buffer is too small for the requested operation; CCS_RESULT_ERROR_SYSTEM if a system call fails (e.g. ftruncate, msync); CCS_RESULT_AGAIN if the non-blocking file descriptor operation is incomplete

Remarks: This function is thread-safe as long as object serialization callbacks are thread safe.

◆ ccs_object_set_destroy_callback()

ccs_result_t ccs_object_set_destroy_callback	(	ccs_object_t	object,
		ccs_object_destroy_callback_t	callback,
		void *	user_data
	)

extern

Attach a destruction callback to a CCS object.

Destruction callbacks are called in reverse order they were attached.

Parameters

[in,out]	object	a CCS object
[in]	callback	the destruction callback to attach
[in]	user_data	an optional pointer that will be passed to the callback

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if object is found to be invalid; CCS_RESULT_ERROR_INVALID_VALUE if callback is NULL

Remarks: This function is thread-safe

◆ ccs_object_set_serialize_callback()

ccs_result_t ccs_object_set_serialize_callback	(	ccs_object_t	object,
		ccs_object_serialize_callback_t	callback,
		void *	user_data
	)

extern

Set the object serialization callback.

Parameters

[in,out]	object	a CCS object
[in]	callback	the serialization callback to attach, eventually replacing the previous callback. Can be NULL in which case the previous callback is removed, if it exists
[in]	user_data	an optional pointer that will be passed to the callback

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if object is found to be invalid

Remarks: This function is thread-safe

◆ ccs_object_set_user_data()

ccs_result_t ccs_object_set_user_data	(	ccs_object_t	object,
		void *	user_data
	)

extern

Set the associated user_data pointer of a CCS object.

Parameters

[in]	object	a CCS object
[in]	user_data	a pointer to the user data to attach to this object

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if object is found to be invalid

Remarks: This function is thread-safe

◆ ccs_release_object()

ccs_result_t ccs_release_object ( ccs_object_t object )

extern

Release a CCS object, decrementing the internal reference counting.

When the internsal reference count reaches zero, the destruction callbacks are called and the object is freed

Parameters

[in,out] object a CCS object

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if the object is found to be invalid; an error code given by the object destructor

Remarks: This function is thread-safe

◆ ccs_retain_object()

ccs_result_t ccs_retain_object ( ccs_object_t object )

extern

Retain a CCS object, incrementing the internal reference counting.

Parameters

[in,out] object a CCS object

Returns: CCS_RESULT_SUCCESS on success; CCS_RESULT_ERROR_INVALID_OBJECT if the object is found to be invalid

Remarks: This function is thread-safe

◆ ccs_string()

static ccs_datum_t ccs_string ( const char * v )

inlinestatic

A helper function to construct a datum containing a string value.

Parameters

[in] v a pointer to a NULL terminated string.

Returns: a CCS datum value

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ CCS_FALSE_VAL

◆ CCS_INACTIVE_VAL

◆ CCS_NONE_VAL

◆ CCS_TRUE_VAL

Typedef Documentation

◆ ccs_object_deserialize_data_callback_t

◆ ccs_object_deserialize_vector_callback_t

◆ ccs_object_serialize_callback_t

Enumeration Type Documentation

◆ ccs_data_type_e

◆ ccs_datum_flag_e

◆ ccs_deserialize_operation_e

◆ ccs_deserialize_option_e

◆ ccs_numeric_type_e

◆ ccs_object_type_e

◆ ccs_result_e

◆ ccs_serialize_format_e

◆ ccs_serialize_operation_e

◆ ccs_serialize_option_e

Function Documentation

◆ ccs_bool()

◆ ccs_datum_cmp()

◆ ccs_fini()

◆ ccs_float()

◆ ccs_get_result_name()

◆ ccs_get_version()

◆ ccs_get_version_string()

◆ ccs_init()

◆ ccs_int()

◆ ccs_object()

◆ ccs_object_deserialize()

◆ ccs_object_get_refcount()

◆ ccs_object_get_type()

◆ ccs_object_get_user_data()

◆ ccs_object_serialize()

◆ ccs_object_set_destroy_callback()

◆ ccs_object_set_serialize_callback()

◆ ccs_object_set_user_data()

◆ ccs_release_object()

◆ ccs_retain_object()

◆ ccs_string()