configuration_space.h File Reference

A configuration space is a context (see context.h) defining a search space on a set of parameters. More...

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

Go to the source code of this file.

Functions
ccs_result_t	ccs_create_configuration_space (const char *name, size_t num_parameters, ccs_parameter_t *parameters, ccs_expression_t *conditions, size_t num_forbidden_clauses, ccs_expression_t *forbidden_clauses, ccs_feature_space_t feature_space, ccs_rng_t rng, ccs_configuration_space_t *configuration_space_ret)
	Create a new configuration space.
ccs_result_t	ccs_configuration_space_get_rng (ccs_configuration_space_t configuration_space, ccs_rng_t *rng_ret)
	Get the internal rng of the configuration space.
ccs_result_t	ccs_configuration_space_get_feature_space (ccs_configuration_space_t configuration_space, ccs_feature_space_t *feature_space_ret)
	Get the feature space of the configuration space.
ccs_result_t	ccs_configuration_space_get_condition (ccs_configuration_space_t configuration_space, size_t parameter_index, ccs_expression_t *expression_ret)
	Get the active condition of a parameter in a configuration space given it's index.
ccs_result_t	ccs_configuration_space_get_conditions (ccs_configuration_space_t configuration_space, size_t num_expressions, ccs_expression_t *expressions, size_t *num_expressions_ret)
	Get the active conditions of the parameters in a configuration space.
ccs_result_t	ccs_configuration_space_get_forbidden_clause (ccs_configuration_space_t configuration_space, size_t index, ccs_expression_t *expression_ret)
	Get the forbidden clause of rank index in a configuration space.
ccs_result_t	ccs_configuration_space_get_forbidden_clauses (ccs_configuration_space_t configuration_space, size_t num_expressions, ccs_expression_t *expressions, size_t *num_expressions_ret)
	Get the forbidden clauses in a configuration space.
ccs_result_t	ccs_configuration_space_get_default_configuration (ccs_configuration_space_t configuration_space, ccs_features_t features, ccs_configuration_t *configuration_ret)
	Get the default configuration of a configuration space.
ccs_result_t	ccs_configuration_space_sample (ccs_configuration_space_t configuration_space, ccs_distribution_space_t distribution_space, ccs_features_t features, ccs_rng_t rng, ccs_configuration_t *configuration_ret)
	Get a configuration sampled randomly from a configuration space.
ccs_result_t	ccs_configuration_space_samples (ccs_configuration_space_t configuration_space, ccs_distribution_space_t distribution_space, ccs_features_t features, ccs_rng_t rng, size_t num_configurations, ccs_configuration_t *configurations)
	Get a given number of configurations sampled randomly from a configuration space.

Detailed Description

A configuration space is a context (see context.h) defining a search space on a set of parameters.

Optionally configuration space can be attached a feature space (see feature_space.h). Configuration space also offer as constraints system to describe conditional parameter activation as well as forbidden parameter configurations.

Function Documentation

ccs_configuration_space_get_condition()

ccs_result_t ccs_configuration_space_get_condition ( ccs_configuration_space_t  configuration_space, size_t  parameter_index, ccs_expression_t *  expression_ret  )

extern

Get the active condition of a parameter in a configuration space given it's index.

Parameters

[in]	configuration_space
[in]	parameter_index	the index of the parameter to get the condition
[out]	expression_ret	a pointer to the variable that will contain the expression, or NULL if the parameter is not associated with a condition

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if configuration_space is not a valid CCS configuration space

CCS_RESULT_ERROR_OUT_OF_BOUNDS if index is greater than the number of parameters in configuration_space

CCS_RESULT_ERROR_INVALID_VALUE if expression_ret is NULL

Remarks

This function is thread-safe

ccs_configuration_space_get_conditions()

ccs_result_t ccs_configuration_space_get_conditions ( ccs_configuration_space_t  configuration_space, size_t  num_expressions, ccs_expression_t *  expressions, size_t *  num_expressions_ret  )

extern

Get the active conditions of the parameters in a configuration space.

Parameters

[in]	configuration_space
[in]	num_expressions	is the number of expressions that can be added to expressions. If expressions is not NULL, num_expressions must be greater than 0
[out]	expressions	an array of num_expressions that will contain the returned expression, or NULL. If the array is too big, extra values are set to NULL. If an parameter is not associated to an expression NULL will be returned for this parameter.
[out]	num_expressions_ret	a pointer to a variable that will contain the number of expression that are or would be returned. Can be NULL

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if configuration_space is not a valid CCS configuration space

CCS_RESULT_ERROR_INVALID_VALUE if expressions is NULL and num_expressions is greater than 0; or if expressions is NULL and num_expressions_ret is NULL; or if num_expressions is less than the number of parameters contained by configuration_space

Remarks

This function is thread-safe

ccs_configuration_space_get_default_configuration()

ccs_result_t ccs_configuration_space_get_default_configuration ( ccs_configuration_space_t  configuration_space, ccs_features_t  features, ccs_configuration_t *  configuration_ret  )

extern

Get the default configuration of a configuration space.

Parameters

[in]	configuration_space
[in]	features	an optional features to use. If NULL and a feature space was provided at configuration_space creation, the default features of the feature space will be used.
[out]	configuration_ret	a pointer to the variable that will contain the returned default configuration

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if configuration_space is not a valid CCS configuration space; or if features is not NULL and is not a valid CCS features

CCS_RESULT_ERROR_INVALID_FEATURES if features feature space is not the same as the feature space provided at configuration_space creation.

CCS_RESULT_ERROR_INVALID_VALUE if configuration_ret is NULL

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate the new configuration

Remarks

This function is thread-safe

ccs_configuration_space_get_feature_space()

ccs_result_t ccs_configuration_space_get_feature_space ( ccs_configuration_space_t  configuration_space, ccs_feature_space_t *  feature_space_ret  )

extern

Get the feature space of the configuration space.

Parameters

[in]	configuration_space
[out]	feature_space_ret	a pointer to the variable that will contain the feature space

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if configuration_space is not a valid CCS configuration space

CCS_RESULT_ERROR_INVALID_VALUE if feature_space_ret is NULL

Remarks

This function is thread-safe

ccs_configuration_space_get_forbidden_clause()

ccs_result_t ccs_configuration_space_get_forbidden_clause ( ccs_configuration_space_t  configuration_space, size_t  index, ccs_expression_t *  expression_ret  )

extern

Get the forbidden clause of rank index in a configuration space.

Parameters

[in]	configuration_space
[in]	index	the index of the forbidden clause to retrieve
[out]	expression_ret	a pointer to the variable that will contain the returned expression

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if configuration_space is not a valid CCS configuration space

CCS_RESULT_ERROR_INVALID_VALUE if expression_ret is NULL

CCS_RESULT_ERROR_OUT_OF_BOUNDS if index is greater than the number of forbidden clauses in the configuration space

Remarks

This function is thread-safe

ccs_configuration_space_get_forbidden_clauses()

ccs_result_t ccs_configuration_space_get_forbidden_clauses ( ccs_configuration_space_t  configuration_space, size_t  num_expressions, ccs_expression_t *  expressions, size_t *  num_expressions_ret  )

extern

Get the forbidden clauses in a configuration space.

Parameters

[in]	configuration_space
[in]	num_expressions	the number of expressions that can be added to expressions. If expressions is not NULL, num_expressions must be greater than 0
[out]	expressions	an array of num_expressions that will contain the returned expressions, or NULL. If the array is too big, extra values are set to NULL
[out]	num_expressions_ret	a pointer to a variable that will contain the number of expressions that are or would be returned. Can be NULL

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if configuration_space is not a valid CCS configuration space

CCS_RESULT_ERROR_INVALID_VALUE if expressions is NULL and num_expressions is greater than 0; or if expressions is NULL and num_expressions_ret is NULL; or if num_expressions is less than the number of expressions that would be returned

Remarks

This function is thread-safe

ccs_configuration_space_get_rng()

ccs_result_t ccs_configuration_space_get_rng ( ccs_configuration_space_t  configuration_space, ccs_rng_t *  rng_ret  )

extern

Get the internal rng of the configuration space.

Parameters

[in]	configuration_space
[out]	rng_ret	a pointer to the variable that will contain the rng

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if configuration_space is not a valid CCS configuration space

CCS_RESULT_ERROR_INVALID_VALUE if rng_ret is NULL

Remarks

This function is thread-safe

ccs_configuration_space_sample()

ccs_result_t ccs_configuration_space_sample ( ccs_configuration_space_t  configuration_space, ccs_distribution_space_t  distribution_space, ccs_features_t  features, ccs_rng_t  rng, ccs_configuration_t *  configuration_ret  )

extern

Get a configuration sampled randomly from a configuration space.

Parameters that were not specified distributions are sampled according to their default distribution. Parameter that are found to be inactive will have the ccs_inactive value. Returned configuration is valid.

Parameters

[in]	configuration_space
[in]	distribution_space	an optional distribution space to use
[in]	features	an optional features to use. If NULL and a feature space was provided at configuration_space creation, the default features of the feature space will be used.
[in]	rng	an optional rng to use
[out]	configuration_ret	a pointer to the variable that will contain the returned configuration

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if configuration_space is not a valid CCS configuration space; or if distribution_space is not a valid CCS distribution space; or if rng is not NULL and is not a valid CCS rng; or if features is not NULL and is not a valid CCS features

CCS_RESULT_ERROR_INVALID_FEATURES if features feature space is not the same as the feature space provided at configuration_space creation.

CCS_RESULT_ERROR_INVALID_VALUE if configuration_ret is NULL

CCS_RESULT_ERROR_SAMPLING_UNSUCCESSFUL if no valid configuration could be sampled

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate the new configuration

Remarks

This function is thread-safe

ccs_configuration_space_samples()

ccs_result_t ccs_configuration_space_samples ( ccs_configuration_space_t  configuration_space, ccs_distribution_space_t  distribution_space, ccs_features_t  features, ccs_rng_t  rng, size_t  num_configurations, ccs_configuration_t *  configurations  )

extern

Get a given number of configurations sampled randomly from a configuration space.

Parameters that were not specified distributions are sampled according to their default distribution. Parameter that are found to be inactive will have the ccs_inactive value. Returned configurations are valid.

Parameters

[in]	configuration_space
[in]	distribution_space	an optional distribution space to use
[in]	features	an optional features to use. Required if a feature space was provided at configuration_space creation.
[in]	rng	an optional rng to use
[in]	num_configurations	the number of requested configurations
[out]	configurations	an array of num_configurations that will contain the requested configurations

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if configuration_space is not a valid CCS configuration space; or if distribution_space is not a valid CCS distribution space; or if rng is not NULL and is not a valid CCS rng; or if features is not NULL and is not a valid CCS features

CCS_RESULT_ERROR_INVALID_FEATURES if features feature space is not the same as the feature space provided at configuration_space creation.

CCS_RESULT_ERROR_INVALID_VALUE if configurations is NULL and num_configurations is greater than 0

CCS_RESULT_ERROR_SAMPLING_UNSUCCESSFUL if no or not enough valid configurations could be sampled. Configurations that could be sampled will be returned contiguously, and the rest will be NULL

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was not enough memory to allocate new configurations. Configurations that could be allocated will be returned, and the rest will be NULL

Remarks

This function is thread-safe

ccs_create_configuration_space()

ccs_result_t ccs_create_configuration_space ( const char *  name, size_t  num_parameters, ccs_parameter_t *  parameters, ccs_expression_t *  conditions, size_t  num_forbidden_clauses, ccs_expression_t *  forbidden_clauses, ccs_feature_space_t  feature_space, ccs_rng_t  rng, ccs_configuration_space_t *  configuration_space_ret  )

extern

Create a new configuration space.

Parameters

[in]	name	pointer to a string that will be copied internally
[in]	num_parameters	the number of provided parameters
[in]	parameters	an array of num_parameters parameters to add to the configuration space
[in]	conditions	an optional array of num_parameters expressions setting the active condition of respective parameters. a NULL entry in the array means no condition is attached to the corresponding parameter.
[in]	num_forbidden_clauses	the number of provided forbidden clauses
[in]	forbidden_clauses	an array of num_forbidden_clauses expressions to add as forbidden clauses to the configuration space
[in]	feature_space	an optional CCS feature space object
[in]	rng	an optional CCS rng object
[out]	configuration_space_ret	a pointer to the variable that will hold the newly created configuration space

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if name is NULL; or if configuration_space_ret is NULL; or if parameters is NULL; or if num_parameters is NULL; or if forbidden_clauses is NULL and num_forbidden_clauses is greater than 0

CCS_RESULT_ERROR_INVALID_OBJECT if a parameter is not a valid CCS parameter; or if an expression is not a valid CCS expression; or if rng is not NULL and is not a valid CCS rng; or it feature_space is not NULL and is not a valid CCS feature space

CCS_RESULT_ERROR_INVALID_PARAMETER if a parameter's type is CCS_PARAMETER_TYPE_STRING; or if a parameter appears more than once in parameters; or if two or more parameters share the same name; or if a parameter is already part of another context; or if an expression references a parameter that is not in parameters or in feature_space

CCS_RESULT_ERROR_INVALID_CONFIGURATION if adding one of the provided forbidden clause would render the default configuration invalid

CCS_RESULT_ERROR_INVALID_GRAPH if the addition of the conditions would cause the dependency graph to become invalid (cyclic)

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was a lack of memory to allocate the new configuration space

Remarks

This function is thread-safe