mca/base/pmix_mca_base_var_enum.h

0001 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
0002 /*
0003  * Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
0004  *                         University Research and Technology
0005  *                         Corporation.  All rights reserved.
0006  * Copyright (c) 2004-2006 The University of Tennessee and The University
0007  *                         of Tennessee Research Foundation.  All rights
0008  *                         reserved.
0009  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
0010  *                         University of Stuttgart.  All rights reserved.
0011  * Copyright (c) 2004-2005 The Regents of the University of California.
0012  *                         All rights reserved.
0013  * Copyright (c) 2008-2011 Cisco Systems, Inc.  All rights reserved.
0014  * Copyright (c) 2012-2016 Los Alamos National Security, LLC. All rights
0015  *                         reserved.
0016  * Copyright (c) 2016-2020 Intel, Inc.  All rights reserved.
0017  * Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
0018  * $COPYRIGHT$
0019  *
0020  * Additional copyrights may follow
0021  *
0022  * $HEADER$
0023  */
0024
0025 #if !defined(PMIX_MCA_BASE_VAR_ENUM_H)
0026 #    define PMIX_MCA_BASE_VAR_ENUM_H
0027
0028 #    include "src/include/pmix_config.h"
0029
0030 #    include "pmix_common.h"
0031 #    include "src/class/pmix_object.h"
0032
0033 typedef struct pmix_mca_base_var_enum_t pmix_mca_base_var_enum_t;
0034
0035 /**
0036  * Get the number of values in the enumerator
0037  *
0038  * @param[in] self the enumerator
0039  * @param[out] count the number of values in the enumerator
0040  */
0041 typedef int (*pmix_mca_base_var_enum_get_count_fn_t)(pmix_mca_base_var_enum_t *self, int *count);
0042
0043 /**
0044  * Get the value and its string representation for an index 0..get_count()
0045  *
0046  * @param[in] self the enumerator
0047  * @param[in] index the index to get the value of
0048  * @param[out] value integer value
0049  * @param[out] string_value string value
0050  */
0051 typedef int (*pmix_mca_base_var_enum_get_value_fn_t)(pmix_mca_base_var_enum_t *self, int index,
0052                                                      int *value, const char **string_value);
0053
0054 /**
0055  * Look up the integer value of a string
0056  *
0057  * @param[in] self the enumerator
0058  * @param[in] string_value string to lookup
0059  * @param[out] value integer value for the string
0060  *
0061  * @retval PMIX_SUCCESS if found
0062  * @retval PMIX_ERR_VALUE_OUT_OF_BOUNDS if not
0063  */
0064 typedef int (*pmix_mca_base_var_enum_vfs_fn_t)(pmix_mca_base_var_enum_t *self,
0065                                                const char *string_value, int *value);
0066
0067 /**
0068  * Dump a textual representation of all the values in an enumerator
0069  *
0070  * @param[in] self the enumerator
0071  * @param[out] out the string representation
0072  *
0073  * @retval PMIX_SUCCESS on success
0074  * @retval pmix error on error
0075  */
0076 typedef int (*pmix_mca_base_var_enum_dump_fn_t)(pmix_mca_base_var_enum_t *self, char **out);
0077
0078 /**
0079  * Get the string representation for an enumerator value
0080  *
0081  * @param[in] self the enumerator
0082  * @param[in] value integer value
0083  * @param[out] string_value string value for value
0084  *
0085  * @retval PMIX_SUCCESS on success
0086  * @retval PMIX_ERR_VALUE_OUT_OF_BOUNDS if not found
0087  *
0088  * @long This function returns the string value for a given integer value in the
0089  * {string_value} parameter. The {string_value} parameter may be NULL in which case
0090  * no string is returned. If a string is returned in {string_value} the caller
0091  * must free the string with free().
0092  */
0093 typedef int (*pmix_mca_base_var_enum_sfv_fn_t)(pmix_mca_base_var_enum_t *self, const int value,
0094                                                char **string_value);
0095
0096 /**
0097  * The default enumerator class takes in a list of integer-string pairs. If a
0098  * string is read from an environment variable or a file value the matching
0099  * integer value is used for the MCA variable.
0100  */
0101 struct pmix_mca_base_var_enum_value_t {
0102     int value;
0103     const char *string;
0104 };
0105
0106 typedef struct pmix_mca_base_var_enum_value_t pmix_mca_base_var_enum_value_t;
0107
0108 /**
0109  * enumerator base class
0110  */
0111 struct pmix_mca_base_var_enum_t {
0112     pmix_object_t super;
0113
0114     /** Is the enumerator statically allocated */
0115     bool enum_is_static;
0116
0117     /** Name of this enumerator. This value is duplicated from the argument provided to
0118         pmix_mca_base_var_enum_create() */
0119     char *enum_name;
0120
0121     /** Get the number of values this enumerator represents. Subclasses should override
0122         the default function. */
0123     pmix_mca_base_var_enum_get_count_fn_t get_count;
0124     /** Get the value and string representation for a particular index. Subclasses should
0125         override the default function */
0126     pmix_mca_base_var_enum_get_value_fn_t get_value;
0127     /** Given a string return corresponding integer value. If the string does not match a
0128      valid value return PMIX_ERR_VALUE_OUT_OF_BOUNDS */
0129     pmix_mca_base_var_enum_vfs_fn_t value_from_string;
0130     /** Given an integer return the corresponding string value. If the integer does not
0131         match a valid value return PMIX_ERR_VALUE_OUT_OF_BOUNDS */
0132     pmix_mca_base_var_enum_sfv_fn_t string_from_value;
0133     /** Dump a textual representation of the enumerator. The caller is responsible for
0134         freeing the string */
0135     pmix_mca_base_var_enum_dump_fn_t dump;
0136
0137     int enum_value_count;
0138     /** Copy of the enumerators values (used by the default functions). This array and
0139         and the strings it contains are freed by the destructor if not NULL. */
0140     pmix_mca_base_var_enum_value_t *enum_values;
0141 };
0142
0143 /**
0144  * The default flag enumerator class takes in a list of integer-string pairs. If a
0145  * string is read from an environment variable or a file value the matching
0146  * flag value is used for the MCA variable. The conflicting_flag is used to
0147  * indicate any flags that should conflict.
0148  */
0149 struct pmix_mca_base_var_enum_value_flag_t {
0150     /** flag value (must be power-of-two) */
0151     int flag;
0152     /** corresponding string name */
0153     const char *string;
0154     /** conflicting flag(s) if any */
0155     int conflicting_flag;
0156 };
0157
0158 typedef struct pmix_mca_base_var_enum_value_flag_t pmix_mca_base_var_enum_value_flag_t;
0159
0160 /**
0161  * flag enumerator base class
0162  */
0163 struct pmix_mca_base_var_enum_flag_t {
0164     /** use the existing enumerator interface */
0165     pmix_mca_base_var_enum_t super;
0166     /** flag value(s) */
0167     pmix_mca_base_var_enum_value_flag_t *enum_flags;
0168 };
0169
0170 typedef struct pmix_mca_base_var_enum_flag_t pmix_mca_base_var_enum_flag_t;
0171
0172 /**
0173  * Object declaration for pmix_mca_base_var_enum_t
0174  */
0175 PMIX_CLASS_DECLARATION(pmix_mca_base_var_enum_t);
0176
0177 /**
0178  * Create a new default enumerator
0179  *
0180  * @param[in] name Name for this enumerator
0181  * @param[in] values List of values terminated with a NULL .string
0182  * member.
0183  * @param[out] enumerator Newly created enumerator.
0184  *
0185  * @retval PMIX_SUCCESS On success
0186  * @retval pmix error code On error
0187  *
0188  * This function creates a value enumerator for integer variables. The
0189  * OUT enumerator value will be a newly OBJ_NEW'ed object that should
0190  * be released by the caller via OBJ_RELEASE.
0191  *
0192  * Note that the output enumerator can be OBJ_RELEASE'd after it has
0193  * been used in a cvar or pvar registration, because the variable
0194  * registration functions will OBJ_RETAIN the enumberator.
0195  *
0196  * Note that all the strings in the values[] array are strdup'ed into
0197  * internal storage, meaning that the caller can free all of the
0198  * strings passed in values[] after pmix_mca_base_var_enum_create()
0199  * returns.
0200  */
0201 int pmix_mca_base_var_enum_create(const char *name, const pmix_mca_base_var_enum_value_t values[],
0202                                   pmix_mca_base_var_enum_t **enumerator);
0203
0204 /**
0205  * Create a new default flag enumerator
0206  *
0207  * @param[in] name Name for this enumerator
0208  * @param[in] flags List of flags terminated with a NULL .string
0209  * member.
0210  * @param[out] enumerator Newly created enumerator.
0211  *
0212  * @retval PMIX_SUCCESS On success
0213  * @retval pmix error code On error
0214  *
0215  * This function creates a flag enumerator for integer variables. The
0216  * OUT enumerator value will be a newly OBJ_NEW'ed object that should
0217  * be released by the caller via OBJ_RELEASE.
0218  *
0219  * Note that the output enumerator can be OBJ_RELEASE'd after it has
0220  * been used in a cvar or pvar registration, because the variable
0221  * registration functions will OBJ_RETAIN the enumberator.
0222  *
0223  * Note that all the strings in the values[] array are strdup'ed into
0224  * internal storage, meaning that the caller can free all of the
0225  * strings passed in values[] after pmix_mca_base_var_enum_create()
0226  * returns.
0227  */
0228 int pmix_mca_base_var_enum_create_flag(const char *name,
0229                                        const pmix_mca_base_var_enum_value_flag_t flags[],
0230                                        pmix_mca_base_var_enum_flag_t **enumerator);
0231
0232 /* standard enumerators. it is invalid to call OBJ_RELEASE on any of these enumerators */
0233 /**
0234  * Boolean enumerator
0235  *
0236  * This enumerator maps:
0237  *   positive integer, true, yes, enabled, t -> 1
0238  *   0, false, no, disabled, f -> 0
0239  */
0240 extern pmix_mca_base_var_enum_t pmix_mca_base_var_enum_bool;
0241
0242 /**
0243  * Verbosity level enumerator
0244  */
0245 extern pmix_mca_base_var_enum_t pmix_mca_base_var_enum_verbose;
0246
0247 #endif /* !defined(MCA_BASE_VAR_ENUM_H) */