parameter.h File Reference

Parameters, when grouped together, define a tuning context (see context.h). More...

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

Go to the source code of this file.

Typedefs
typedef enum ccs_parameter_type_e	ccs_parameter_type_t
	A commodity type to represent a parameter type.

Enumerations
enum	ccs_parameter_type_e {   CCS_PARAMETER_TYPE_NUMERICAL , CCS_PARAMETER_TYPE_CATEGORICAL , CCS_PARAMETER_TYPE_ORDINAL , CCS_PARAMETER_TYPE_DISCRETE ,   CCS_PARAMETER_TYPE_STRING , CCS_PARAMETER_TYPE_MAX , CCS_PARAMETER_TYPE_FORCE_32BIT = INT_MAX }
	CCS parameter types. More...

Functions
ccs_result_t	ccs_create_numerical_parameter (const char *name, ccs_numeric_type_t data_type, ccs_numeric_t lower, ccs_numeric_t upper, ccs_numeric_t quantization, ccs_numeric_t default_value, ccs_parameter_t *parameter_ret)
	Create a new numerical parameter of the specified data_type.
ccs_result_t	ccs_create_int_numerical_parameter (const char *name, ccs_int_t lower, ccs_int_t upper, ccs_int_t quantization, ccs_int_t default_value, ccs_parameter_t *parameter_ret)
	Create a new integer numerical parameter.
ccs_result_t	ccs_create_float_numerical_parameter (const char *name, ccs_float_t lower, ccs_float_t upper, ccs_float_t quantization, ccs_float_t default_value, ccs_parameter_t *parameter_ret)
	Create a new floating point numerical parameter.
ccs_result_t	ccs_numerical_parameter_get_properties (ccs_parameter_t parameter, ccs_numeric_type_t *data_type_ret, ccs_numeric_t *lower_ret, ccs_numeric_t *upper_ret, ccs_numeric_t *quantization_ret)
	Get the properties used to create a numerical parameter.
ccs_result_t	ccs_create_categorical_parameter (const char *name, size_t num_possible_values, ccs_datum_t *possible_values, size_t default_value_index, ccs_parameter_t *parameter_ret)
	Create a new categorical parameter.
ccs_result_t	ccs_categorical_parameter_get_values (ccs_parameter_t parameter, size_t num_possible_values, ccs_datum_t *possible_values, size_t *num_possible_values_ret)
	Get the possible values of a categorical parameter.
ccs_result_t	ccs_create_ordinal_parameter (const char *name, size_t num_possible_values, ccs_datum_t *possible_values, size_t default_value_index, ccs_parameter_t *parameter_ret)
	Create a new ordinal parameter.
ccs_result_t	ccs_ordinal_parameter_get_values (ccs_parameter_t parameter, size_t num_possible_values, ccs_datum_t *possible_values, size_t *num_possible_values_ret)
	Get the possible values of an ordinal parameter.
ccs_result_t	ccs_ordinal_parameter_compare_values (ccs_parameter_t parameter, ccs_datum_t value1, ccs_datum_t value2, ccs_int_t *comp_ret)
	Compare two values in the context of an ordinal parameter.
ccs_result_t	ccs_create_discrete_parameter (const char *name, size_t num_possible_values, ccs_datum_t *possible_values, size_t default_value_index, ccs_parameter_t *parameter_ret)
	Create a new discrete parameter.
ccs_result_t	ccs_discrete_parameter_get_values (ccs_parameter_t parameter, size_t num_possible_values, ccs_datum_t *possible_values, size_t *num_possible_values_ret)
	Get the possible values of an discrete parameter.
ccs_result_t	ccs_create_string_parameter (const char *name, ccs_parameter_t *parameter_ret)
	Create an new parameter representing an undetermined string, to be used within feature space.
ccs_result_t	ccs_parameter_copy (ccs_parameter_t parameter, ccs_parameter_t *parameter_ret)
	Create a copy of a parameter.
ccs_result_t	ccs_parameter_get_type (ccs_parameter_t parameter, ccs_parameter_type_t *type_ret)
	Get the type of a parameter.
ccs_result_t	ccs_parameter_get_default_value (ccs_parameter_t parameter, ccs_datum_t *value_ret)
	Get the default value of an parameter.
ccs_result_t	ccs_parameter_get_name (ccs_parameter_t parameter, const char **name_ret)
	Get the name of a parameter.
ccs_result_t	ccs_parameter_get_default_distribution (ccs_parameter_t parameter, ccs_distribution_t *distribution_ret)
	Get the default distribution of a parameter.
ccs_result_t	ccs_parameter_check_value (ccs_parameter_t parameter, ccs_datum_t value, ccs_bool_t *result_ret)
	Check if a value is acceptable for a parameter.
ccs_result_t	ccs_parameter_check_values (ccs_parameter_t parameter, size_t num_values, const ccs_datum_t *values, ccs_bool_t *results)
	Check if an array of values are acceptable for a parameter.
ccs_result_t	ccs_parameter_validate_value (ccs_parameter_t parameter, ccs_datum_t value, ccs_datum_t *value_ret, ccs_bool_t *result_ret)
	Check if a value is acceptable for a parameter and if it is return a marshalled value.
ccs_result_t	ccs_parameter_validate_values (ccs_parameter_t parameter, size_t num_values, const ccs_datum_t *values, ccs_datum_t *values_ret, ccs_bool_t *results)
	Check if an array of values are acceptable for a parameter and return marshalled values if they are valid.
ccs_result_t	ccs_parameter_convert_samples (ccs_parameter_t parameter, ccs_bool_t oversampling, size_t num_values, const ccs_numeric_t *values, ccs_datum_t *results)
	Convert numerical samples into samples from the parameter.
ccs_result_t	ccs_parameter_sample (ccs_parameter_t parameter, ccs_distribution_t distribution, ccs_rng_t rng, ccs_datum_t *value_ret)
	Get a sample from the parameter sampled by a given distribution.
ccs_result_t	ccs_parameter_samples (ccs_parameter_t parameter, ccs_distribution_t distribution, ccs_rng_t rng, size_t num_values, ccs_datum_t *values)
	Get samples from the parameter sampled by a given distribution.
ccs_result_t	ccs_parameter_sampling_interval (ccs_parameter_t parameter, ccs_interval_t *interval_ret)
	Get the valid sampling interval of the parameter.

Detailed Description

Parameters, when grouped together, define a tuning context (see context.h).

Most parameters can be sampled according to a distribution's dimension (see distribution.h). Hyperparamters are immutable, except from a reference counting and callback management point of view.

Enumeration Type Documentation

ccs_parameter_type_e

enum ccs_parameter_type_e

CCS parameter types.

Enumerator
CCS_PARAMETER_TYPE_NUMERICAL	A numerical parameter, over integers or floating point values.
CCS_PARAMETER_TYPE_CATEGORICAL	A categorical parameter. A set of values with no intrinsic ordering between its elements.
CCS_PARAMETER_TYPE_ORDINAL	An ordinal parameter. A set of values with an intrinsic ordering between its elements.
CCS_PARAMETER_TYPE_DISCRETE	A discrete parameter. A set of numerical values.
CCS_PARAMETER_TYPE_STRING	A string parameter. Cannot be sampled.
CCS_PARAMETER_TYPE_MAX	Guard.
CCS_PARAMETER_TYPE_FORCE_32BIT	Try forcing 32 bits value for bindings.

Function Documentation

ccs_categorical_parameter_get_values()

ccs_result_t ccs_categorical_parameter_get_values ( ccs_parameter_t  parameter, size_t  num_possible_values, ccs_datum_t *  possible_values, size_t *  num_possible_values_ret  )

extern

Get the possible values of a categorical parameter.

Parameters

[in]	parameter
[in]	num_possible_values	the size of the possible_values array
[out]	possible_values	an array of num_possible_values values that will contain the returned possible values. Can be NULL
[out]	num_possible_values_ret	a pointer to a variable that will contain the number of values that are or would be returned. Can be NULL

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS parameter

CCS_RESULT_ERROR_INVALID_PARAMETER if parameter is not a categorical parameter

CCS_RESULT_ERROR_INVALID_VALUE if possible_values is NULL and num_possible_values is greater than 0; or if possible_values is NULL and num_possible_values_ret is NULL; or if num_possible_values is less than the number of values that would be returned

Remarks

This function is thread-safe

ccs_create_categorical_parameter()

ccs_result_t ccs_create_categorical_parameter ( const char *  name, size_t  num_possible_values, ccs_datum_t *  possible_values, size_t  default_value_index, ccs_parameter_t *  parameter_ret  )

extern

Create a new categorical parameter.

Categorical parameters can be sampled using distributions over integers.

Parameters

[in]	name	name of the parameter
[in]	num_possible_values	the size of the possible_values array
[in]	possible_values	an array of num_possible_values values that represent the possible values that the parameter can take
[in]	default_value_index	the index of the default value in the possible_values array
[out]	parameter_ret	a pointer to the variable that will hold the newly created categorical parameter

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if name is NULL; or if parameter_ret is NULL

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

Remarks

This function is thread-safe

ccs_create_discrete_parameter()

ccs_result_t ccs_create_discrete_parameter ( const char *  name, size_t  num_possible_values, ccs_datum_t *  possible_values, size_t  default_value_index, ccs_parameter_t *  parameter_ret  )

extern

Create a new discrete parameter.

Discrete parameters can be sampled using distributions over integers. Their elements must be of type CCS_DATA_TYPE_INT or CCS_DATA_TYPE_FLOAT.

Parameters

[in]	name	name of the parameter
[in]	num_possible_values	the size of the possible_values array
[in]	possible_values	an array of num_possible_values values that represent the possible values that the parameter can take.
[in]	default_value_index	the index of the default value in the possible_values array
[out]	parameter_ret	a pointer to the variable that will hold the newly created discrete parameter

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if name is NULL; or if parameter_ret is NULL

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

Remarks

This function is thread-safe

ccs_create_float_numerical_parameter()

ccs_result_t ccs_create_float_numerical_parameter ( const char *  name, ccs_float_t  lower, ccs_float_t  upper, ccs_float_t  quantization, ccs_float_t  default_value, ccs_parameter_t *  parameter_ret  )

extern

Create a new floating point numerical parameter.

Parameters

[in]	name	name of the parameter
[in]	lower	lower bound (included)
[in]	upper	upper bound (excluded)
[in]	quantization	quantization of the values. 0 means no quantization
[in]	default_value	default value of the parameter
[out]	parameter_ret	a pointer to the variable that will hold the newly created numerical parameter

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if name is NULL; or if parameter_ret is NULL; or if quantization is less than 0; or if default value is not a valid value for the parameter

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was a lack of memory to allocate the new numerical parameter

Remarks

This function is thread-safe

ccs_create_int_numerical_parameter()

ccs_result_t ccs_create_int_numerical_parameter ( const char *  name, ccs_int_t  lower, ccs_int_t  upper, ccs_int_t  quantization, ccs_int_t  default_value, ccs_parameter_t *  parameter_ret  )

extern

Create a new integer numerical parameter.

Parameters

[in]	name	name of the parameter
[in]	lower	lower bound (included)
[in]	upper	upper bound (excluded)
[in]	quantization	quantization of the values. 0 means no quantization
[in]	default_value	default value of the parameter
[out]	parameter_ret	a pointer to the variable that will hold the newly created numerical parameter

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if name is NULL; or if parameter_ret is NULL; or if quantization is less than 0; or if default value is not a valid value for the parameter

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was a lack of memory to allocate the new numerical parameter

Remarks

This function is thread-safe

ccs_create_numerical_parameter()

ccs_result_t ccs_create_numerical_parameter ( const char *  name, ccs_numeric_type_t  data_type, ccs_numeric_t  lower, ccs_numeric_t  upper, ccs_numeric_t  quantization, ccs_numeric_t  default_value, ccs_parameter_t *  parameter_ret  )

extern

Create a new numerical parameter of the specified data_type.

Parameters

[in]	name	name of the parameter
[in]	data_type	type of numerical data
[in]	lower	lower bound (included)
[in]	upper	upper bound (excluded)
[in]	quantization	quantization of the values. 0 means no quantization
[in]	default_value	default value of the parameter
[out]	parameter_ret	a pointer to the variable that will hold the newly created numerical parameter

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if name is NULL; or if parameter_ret is NULL; or if quantization is less than 0; or if default value is not a valid value for the parameter

CCS_RESULT_ERROR_INVALID_TYPE if data_type is neither CCS_NUMERIC_TYPE_FLOAT or CCS_NUMERIC_TYPE_INT

CCS_RESULT_ERROR_OUT_OF_MEMORY if there was a lack of memory to allocate the new numerical parameter

Remarks

This function is thread-safe

ccs_create_ordinal_parameter()

ccs_result_t ccs_create_ordinal_parameter ( const char *  name, size_t  num_possible_values, ccs_datum_t *  possible_values, size_t  default_value_index, ccs_parameter_t *  parameter_ret  )

extern

Create a new ordinal parameter.

Ordinal parameters can be sampled using distributions over integers. Their elements have an intrinsic ordering which is the same as the orders of the provided values.

Parameters

[in]	name	name of the parameter
[in]	num_possible_values	the size of the possible_values array
[in]	possible_values	an array of num_possible_values values that represent the possible values that the parameter can take
[in]	default_value_index	the index of the default value in the possible_values array
[out]	parameter_ret	a pointer to the variable that will hold the newly created ordinal parameter

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if name is NULL; or if parameter_ret is NULL

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

Remarks

This function is thread-safe

ccs_create_string_parameter()

ccs_result_t ccs_create_string_parameter ( const char *  name, ccs_parameter_t *  parameter_ret  )

extern

Create an new parameter representing an undetermined string, to be used within feature space.

Cannot be sampled and thus doesn't have a default value. Checks will always return valid unless the value is not a string.

Parameters

[in]	name	name of the parameter
[out]	parameter_ret	a pointer to the variable that will hold the newly created string parameter

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if name is NULL; or if parameter_ret is NULL

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

Remarks

This function is thread-safe

ccs_discrete_parameter_get_values()

ccs_result_t ccs_discrete_parameter_get_values ( ccs_parameter_t  parameter, size_t  num_possible_values, ccs_datum_t *  possible_values, size_t *  num_possible_values_ret  )

extern

Get the possible values of an discrete parameter.

Parameters

[in]	parameter
[in]	num_possible_values	the size of the possible_values array
[out]	possible_values	an array of num_possible_values values that will contain the returned possible values. Can be NULL
[out]	num_possible_values_ret	a pointer to a variable that will contain the number of values that are or would be returned. Can be NULL

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS parameter

CCS_RESULT_ERROR_INVALID_PARAMETER if parameter is not a discrete parameter

CCS_RESULT_ERROR_INVALID_VALUE if possible_values is NULL and num_possible_values is greater than 0; or if possible_values is NULL and num_possible_values_ret is NULL; or if num_possible_values is less than the number of values that would be returned

Remarks

This function is thread-safe

ccs_numerical_parameter_get_properties()

ccs_result_t ccs_numerical_parameter_get_properties ( ccs_parameter_t  parameter, ccs_numeric_type_t *  data_type_ret, ccs_numeric_t *  lower_ret, ccs_numeric_t *  upper_ret, ccs_numeric_t *  quantization_ret  )

extern

Get the properties used to create a numerical parameter.

Parameters

[in]	parameter
[out]	data_type_ret	a pointer to the variable that will contain the data type of the numerical parameter
[out]	lower_ret	a pointer to the variable that will contain the lower bound of the numerical parameter
[out]	upper_ret	a pointer to the variable that will contain the upper bound of the numerical parameter
[out]	quantization_ret	a pointer that will contain the quantization of the numerical parameter

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS parameter

CCS_RESULT_ERROR_INVALID_PARAMETER if parameter is not a numerical parameter

CCS_RESULT_ERROR_INVALID_VALUE if data_type_ret is NULL and lower_ret is NULL and upper_ret is NULL and quantization_ret is NULL

Remarks

This function is thread-safe

ccs_ordinal_parameter_compare_values()

ccs_result_t ccs_ordinal_parameter_compare_values ( ccs_parameter_t  parameter, ccs_datum_t  value1, ccs_datum_t  value2, ccs_int_t *  comp_ret  )

extern

Compare two values in the context of an ordinal parameter.

Parameters

[in]	parameter
[in]	value1	the first value to compare
[in]	value2	the second value to compare
[out]	comp_ret	the result of the comparison, -1, 1, or 0 if value1 is found to be respectively lesser than, grater then or equal to value2

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS

CCS_RESULT_ERROR_INVALID_PARAMETER if parameter is not an ordinal parameter

CCS_RESULT_ERROR_INVALID_VALUE if comp_ret is NULL; or if value1 or value2 are not one of the parameter possible values

Remarks

This function is thread-safe

ccs_ordinal_parameter_get_values()

ccs_result_t ccs_ordinal_parameter_get_values ( ccs_parameter_t  parameter, size_t  num_possible_values, ccs_datum_t *  possible_values, size_t *  num_possible_values_ret  )

extern

Get the possible values of an ordinal parameter.

Parameters

[in]	parameter
[in]	num_possible_values	the size of the possible_values array
[out]	possible_values	an array of num_possible_values values that will contain the returned possible values. Can be NULL
[out]	num_possible_values_ret	a pointer to a variable that will contain the number of values that are or would be returned. Can be NULL

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS parameter

CCS_RESULT_ERROR_INVALID_PARAMETER if parameter is not an ordinal parameter

CCS_RESULT_ERROR_INVALID_VALUE if possible_values is NULL and num_possible_values is greater than 0; or if possible_values is NULL and num_possible_values_ret is NULL; or if num_possible_values is less than the number of values that would be returned

Remarks

This function is thread-safe

ccs_parameter_check_value()

ccs_result_t ccs_parameter_check_value ( ccs_parameter_t  parameter, ccs_datum_t  value, ccs_bool_t *  result_ret  )

extern

Check if a value is acceptable for a parameter.

Parameters

[in]	parameter
[in]	value	the value to check the validity of
[out]	result_ret	a pointer to the variable that will contain the result of the check

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS parameter

CCS_RESULT_ERROR_INVALID_VALUE if result_ret is NULL

Remarks

This function is thread-safe

ccs_parameter_check_values()

ccs_result_t ccs_parameter_check_values ( ccs_parameter_t  parameter, size_t  num_values, const ccs_datum_t *  values, ccs_bool_t *  results  )

extern

Check if an array of values are acceptable for a parameter.

Parameters

[in]	parameter
[in]	num_values	the size of the values array
[in]	values	an array of num_values values to check
[out]	results	an array of num_values cc_bool_t values that will contain the results the individual checks

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS parameter

CCS_RESULT_ERROR_INVALID_VALUE if values or results are NULL and num_values is greater than 0

Remarks

This function is thread-safe

ccs_parameter_convert_samples()

ccs_result_t ccs_parameter_convert_samples ( ccs_parameter_t  parameter, ccs_bool_t  oversampling, size_t  num_values, const ccs_numeric_t *  values, ccs_datum_t *  results  )

extern

Convert numerical samples into samples from the parameter.

Parameters

[in]	parameter
[in]	oversampling	if CCS_TRUE values can be outside of the parameter sampling interval (see ccs_parameter_sampling_interval), else they must be within the sampling interval
[in]	num_values	the size of the values array
[in]	values	an array of num_values values to convert
[out]	results	an array of num_values values that will contain the converted values. If oversampling is CCS_TRUE values outside of the sampling interval will be converted to ccs_inactive

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS parameter

CCS_RESULT_ERROR_INVALID_VALUE if values or results are NULL and num_values is greater than 0

CCS_RESULT_ERROR_UNSUPPORTED_OPERATION if the parameter is of type CCS_PARAMETER_TYPE_STRING

Remarks

This function is thread-safe

ccs_parameter_copy()

ccs_result_t ccs_parameter_copy ( ccs_parameter_t  parameter, ccs_parameter_t *  parameter_ret  )

extern

Create a copy of a parameter.

User data are not copied.

Parameters

[in]	parameter
[out]	parameter_ret	a pointer to the variable that will hold the newly created CCS parameter

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if parameter_ret is NULL

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

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS parameter

Remarks

This function is thread-safe

ccs_parameter_get_default_distribution()

ccs_result_t ccs_parameter_get_default_distribution ( ccs_parameter_t  parameter, ccs_distribution_t *  distribution_ret  )

extern

Get the default distribution of a parameter.

Parameters

[in]	parameter
[out]	distribution_ret	a pointer to the variable that will contained the returned distribution

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS parameter

CCS_RESULT_ERROR_INVALID_VALUE if distribution_ret is NULL

Remarks

This function is thread-safe

ccs_parameter_get_default_value()

ccs_result_t ccs_parameter_get_default_value ( ccs_parameter_t  parameter, ccs_datum_t *  value_ret  )

extern

Get the default value of an parameter.

Parameters

[in]	parameter
[out]	value_ret	pointer to the variable that will contain the default value of the parameter

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if value_ret is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS parameter

Remarks

This function is thread-safe

ccs_parameter_get_name()

ccs_result_t ccs_parameter_get_name ( ccs_parameter_t  parameter, const char **  name_ret  )

extern

Get the name of a parameter.

Parameters

[in]	parameter
[out]	name_ret	a pointer to the variable that will contain a pointer to the name of the parameter

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if name_ret is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if distribution is not a valid CCS parameter

Remarks

This function is thread-safe

ccs_parameter_get_type()

ccs_result_t ccs_parameter_get_type ( ccs_parameter_t  parameter, ccs_parameter_type_t *  type_ret  )

extern

Get the type of a parameter.

Parameters

[in]	parameter
[out]	type_ret	a pointer to the variable that will contain the type of the parameter

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_VALUE if type_ret is NULL

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS parameter

Remarks

This function is thread-safe

ccs_parameter_sample()

ccs_result_t ccs_parameter_sample ( ccs_parameter_t  parameter, ccs_distribution_t  distribution, ccs_rng_t  rng, ccs_datum_t *  value_ret  )

extern

Get a sample from the parameter sampled by a given distribution.

Parameters

[in]	parameter
[in]	distribution	the distribution to sample the parameter with
[in]	rng	the random number generator to use
[out]	value_ret	a pointer to the variable that will contain the sampled value

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS parameter; or if distribution is not a valid CCS distribution; or if rng is not a valid CCS random number generator

CCS_RESULT_ERROR_INVALID_VALUE if value_ret is NULL

CCS_RESULT_ERROR_SAMPLING_UNSUCCESSFUL if the sample could not be generated, because the probability of obtaining a valid sample is too low

CCS_RESULT_ERROR_UNSUPPORTED_OPERATION if the parameter is of type CCS_PARAMETER_TYPE_STRING

Remarks

This function is thread-safe if rng is only used by one thread at a time

ccs_parameter_samples()

ccs_result_t ccs_parameter_samples ( ccs_parameter_t  parameter, ccs_distribution_t  distribution, ccs_rng_t  rng, size_t  num_values, ccs_datum_t *  values  )

extern

Get samples from the parameter sampled by a given distribution.

Parameters

[in]	parameter
[in]	distribution	the distribution to sample the parameter with
[in]	rng	the random number generator to use
[in]	num_values	the number of queried values
[out]	values	an array of num_values values will contain the sampled values

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS parameter; or if distribution is not a valid CCS distribution; or if rng is not a valid CCS random number generator

CCS_RESULT_ERROR_INVALID_VALUE if values is NULL and num_values is greater than 0

CCS_RESULT_ERROR_SAMPLING_UNSUCCESSFUL if not enough samples could not be generated, because the probability of obtaining a valid sample is too low

CCS_RESULT_ERROR_UNSUPPORTED_OPERATION if the parameter is of type CCS_PARAMETER_TYPE_STRING

Remarks

This function is thread-safe if rng is only used by one thread at a time

ccs_parameter_sampling_interval()

ccs_result_t ccs_parameter_sampling_interval ( ccs_parameter_t  parameter, ccs_interval_t *  interval_ret  )

extern

Get the valid sampling interval of the parameter.

Parameters

[in]	parameter
[out]	interval_ret	a pointer to the variable that will contain the returned interval

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS parameter

CCS_RESULT_ERROR_INVALID_VALUE if interval_ret is NULL

Remarks

This function is thread-safe

ccs_parameter_validate_value()

ccs_result_t ccs_parameter_validate_value ( ccs_parameter_t  parameter, ccs_datum_t  value, ccs_datum_t *  value_ret, ccs_bool_t *  result_ret  )

extern

Check if a value is acceptable for a parameter and if it is return a marshalled value.

Parameters

[in]	parameter
[in]	value	the value to check the validity of
[out]	value_ret	a pointer to the variable that will contain the marshalled value or ccs_inactive if the value is not valid
[out]	result_ret	a pointer to the variable that will contain the result of the check

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS parameter

CCS_RESULT_ERROR_INVALID_VALUE if result_ret or value_ret is NULL

Remarks

This function is thread-safe

ccs_parameter_validate_values()

ccs_result_t ccs_parameter_validate_values ( ccs_parameter_t  parameter, size_t  num_values, const ccs_datum_t *  values, ccs_datum_t *  values_ret, ccs_bool_t *  results  )

extern

Check if an array of values are acceptable for a parameter and return marshalled values if they are valid.

Parameters

[in]	parameter
[in]	num_values	the size of the values array
[in]	values	an array of num_values values to check
[out]	values_ret	an array of num_values values that will contain the marshalled values, or ccs_inactive if values are invalid
[out]	results	an array of num_values cc_bool_t values that will contain the results the individual checks

Returns

CCS_RESULT_SUCCESS on success

CCS_RESULT_ERROR_INVALID_OBJECT if parameter is not a valid CCS parameter

CCS_RESULT_ERROR_INVALID_VALUE if values or results or values_ret are NULL and num_values is greater than 0

Remarks

This function is thread-safe