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-2026 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 /* Output mode for dumping var enumerators.
0034  * Caution: Not 1:1 with pmix_mca_base_var_dump_type_t, appropriate
0035  * conversion is required, see PMIX_MCA_BASE_VAR_DUMP_TYPE_TO_ENUM_DUMP_TYPE() */
0036 typedef enum {
0037     /* Dump human-readable strings */
0038     PMIX_MCA_BASE_VAR_ENUM_DUMP_READABLE = 0,
0039     /* Dump human-readable strings, with color where supported */
0040     PMIX_MCA_BASE_VAR_ENUM_DUMP_READABLE_COLOR = 1
0041 } pmix_mca_base_var_enum_dump_type_t;
0042
0043 #define PMIX_MCA_BASE_VAR_DUMP_TYPE_TO_ENUM_DUMP_TYPE(var_dump_type) \
0044     (PMIX_MCA_BASE_VAR_DUMP_READABLE_COLOR == (var_dump_type) ? \
0045      PMIX_MCA_BASE_VAR_ENUM_DUMP_READABLE_COLOR : PMIX_MCA_BASE_VAR_ENUM_DUMP_READABLE)
0046
0047
0048 typedef struct pmix_mca_base_var_enum_t pmix_mca_base_var_enum_t;
0049
0050 /**
0051  * Get the number of values in the enumerator
0052  *
0053  * @param[in] self the enumerator
0054  * @param[out] count the number of values in the enumerator
0055  */
0056 typedef int (*pmix_mca_base_var_enum_get_count_fn_t)(pmix_mca_base_var_enum_t *self, int *count);
0057
0058 /**
0059  * Get the value and its string representation for an index 0..get_count()
0060  *
0061  * @param[in] self the enumerator
0062  * @param[in] index the index to get the value of
0063  * @param[out] value integer value
0064  * @param[out] string_value string value
0065  */
0066 typedef int (*pmix_mca_base_var_enum_get_value_fn_t)(pmix_mca_base_var_enum_t *self, int index,
0067                                                      int *value, const char **string_value);
0068
0069 /**
0070  * Look up the integer value of a string
0071  *
0072  * @param[in] self the enumerator
0073  * @param[in] string_value string to lookup
0074  * @param[out] value integer value for the string
0075  *
0076  * @retval PMIX_SUCCESS if found
0077  * @retval PMIX_ERR_VALUE_OUT_OF_BOUNDS if not
0078  */
0079 typedef int (*pmix_mca_base_var_enum_vfs_fn_t)(pmix_mca_base_var_enum_t *self,
0080                                                const char *string_value, int *value);
0081
0082 /**
0083  * Dump a textual representation of all the values in an enumerator
0084  *
0085  * @param[in] self the enumerator
0086  * @param[out] out the string representation
0087  *
0088  * @retval PMIX_SUCCESS on success
0089  * @retval pmix error on error
0090  */
0091 typedef int (*pmix_mca_base_var_enum_dump_fn_t)(pmix_mca_base_var_enum_t *self, char **out,
0092                                                 pmix_mca_base_var_enum_dump_type_t output_type);
0093
0094 /**
0095  * Get the string representation for an enumerator value
0096  *
0097  * @param[in] self the enumerator
0098  * @param[in] value integer value
0099  * @param[out] string_value string value for value
0100  *
0101  * @retval PMIX_SUCCESS on success
0102  * @retval PMIX_ERR_VALUE_OUT_OF_BOUNDS if not found
0103  *
0104  * @long This function returns the string value for a given integer value in the
0105  * {string_value} parameter. The {string_value} parameter may be NULL in which case
0106  * no string is returned. If a string is returned in {string_value} the caller
0107  * must free the string with free().
0108  */
0109 typedef int (*pmix_mca_base_var_enum_sfv_fn_t)(pmix_mca_base_var_enum_t *self, const int value,
0110                                                char **string_value);
0111
0112 /**
0113  * The default enumerator class takes in a list of integer-string pairs. If a
0114  * string is read from an environment variable or a file value the matching
0115  * integer value is used for the MCA variable.
0116  */
0117 struct pmix_mca_base_var_enum_value_t {
0118     int value;
0119     const char *string;
0120 };
0121
0122 typedef struct pmix_mca_base_var_enum_value_t pmix_mca_base_var_enum_value_t;
0123
0124 /**
0125  * enumerator base class
0126  */
0127 struct pmix_mca_base_var_enum_t {
0128     pmix_object_t super;
0129
0130     /** Is the enumerator statically allocated */
0131     bool enum_is_static;
0132
0133     /** Name of this enumerator. This value is duplicated from the argument provided to
0134         pmix_mca_base_var_enum_create() */
0135     char *enum_name;
0136
0137     /** Get the number of values this enumerator represents. Subclasses should override
0138         the default function. */
0139     pmix_mca_base_var_enum_get_count_fn_t get_count;
0140     /** Get the value and string representation for a particular index. Subclasses should
0141         override the default function */
0142     pmix_mca_base_var_enum_get_value_fn_t get_value;
0143     /** Given a string return corresponding integer value. If the string does not match a
0144      valid value return PMIX_ERR_VALUE_OUT_OF_BOUNDS */
0145     pmix_mca_base_var_enum_vfs_fn_t value_from_string;
0146     /** Given an integer return the corresponding string value. If the integer does not
0147         match a valid value return PMIX_ERR_VALUE_OUT_OF_BOUNDS */
0148     pmix_mca_base_var_enum_sfv_fn_t string_from_value;
0149     /** Dump a textual representation of the enumerator. The caller is responsible for
0150         freeing the string */
0151     pmix_mca_base_var_enum_dump_fn_t dump;
0152
0153     int enum_value_count;
0154     /** Copy of the enumerators values (used by the default functions). This array and
0155         and the strings it contains are freed by the destructor if not NULL. */
0156     pmix_mca_base_var_enum_value_t *enum_values;
0157 };
0158
0159 /**
0160  * The default flag enumerator class takes in a list of integer-string pairs. If a
0161  * string is read from an environment variable or a file value the matching
0162  * flag value is used for the MCA variable. The conflicting_flag is used to
0163  * indicate any flags that should conflict.
0164  */
0165 struct pmix_mca_base_var_enum_value_flag_t {
0166     /** flag value (must be power-of-two) */
0167     int flag;
0168     /** corresponding string name */
0169     const char *string;
0170     /** conflicting flag(s) if any */
0171     int conflicting_flag;
0172 };
0173
0174 typedef struct pmix_mca_base_var_enum_value_flag_t pmix_mca_base_var_enum_value_flag_t;
0175
0176 /**
0177  * flag enumerator base class
0178  */
0179 struct pmix_mca_base_var_enum_flag_t {
0180     /** use the existing enumerator interface */
0181     pmix_mca_base_var_enum_t super;
0182     /** flag value(s) */
0183     pmix_mca_base_var_enum_value_flag_t *enum_flags;
0184 };
0185
0186 typedef struct pmix_mca_base_var_enum_flag_t pmix_mca_base_var_enum_flag_t;
0187
0188 /**
0189  * Object declaration for pmix_mca_base_var_enum_t
0190  */
0191 PMIX_CLASS_DECLARATION(pmix_mca_base_var_enum_t);
0192
0193 /**
0194  * Create a new default enumerator
0195  *
0196  * @param[in] name Name for this enumerator
0197  * @param[in] values List of values terminated with a NULL .string
0198  * member.
0199  * @param[out] enumerator Newly created enumerator.
0200  *
0201  * @retval PMIX_SUCCESS On success
0202  * @retval pmix error code On error
0203  *
0204  * This function creates a value enumerator for integer variables. The
0205  * OUT enumerator value will be a newly OBJ_NEW'ed object that should
0206  * be released by the caller via OBJ_RELEASE.
0207  *
0208  * Note that the output enumerator can be OBJ_RELEASE'd after it has
0209  * been used in a cvar or pvar registration, because the variable
0210  * registration functions will OBJ_RETAIN the enumberator.
0211  *
0212  * Note that all the strings in the values[] array are strdup'ed into
0213  * internal storage, meaning that the caller can free all of the
0214  * strings passed in values[] after pmix_mca_base_var_enum_create()
0215  * returns.
0216  */
0217 int pmix_mca_base_var_enum_create(const char *name, const pmix_mca_base_var_enum_value_t values[],
0218                                   pmix_mca_base_var_enum_t **enumerator);
0219
0220 /**
0221  * Create a new default flag enumerator
0222  *
0223  * @param[in] name Name for this enumerator
0224  * @param[in] flags List of flags terminated with a NULL .string
0225  * member.
0226  * @param[out] enumerator Newly created enumerator.
0227  *
0228  * @retval PMIX_SUCCESS On success
0229  * @retval pmix error code On error
0230  *
0231  * This function creates a flag enumerator for integer variables. The
0232  * OUT enumerator value will be a newly OBJ_NEW'ed object that should
0233  * be released by the caller via OBJ_RELEASE.
0234  *
0235  * Note that the output enumerator can be OBJ_RELEASE'd after it has
0236  * been used in a cvar or pvar registration, because the variable
0237  * registration functions will OBJ_RETAIN the enumberator.
0238  *
0239  * Note that all the strings in the values[] array are strdup'ed into
0240  * internal storage, meaning that the caller can free all of the
0241  * strings passed in values[] after pmix_mca_base_var_enum_create()
0242  * returns.
0243  */
0244 int pmix_mca_base_var_enum_create_flag(const char *name,
0245                                        const pmix_mca_base_var_enum_value_flag_t flags[],
0246                                        pmix_mca_base_var_enum_flag_t **enumerator);
0247
0248 /* standard enumerators. it is invalid to call OBJ_RELEASE on any of these enumerators */
0249 /**
0250  * Boolean enumerator
0251  *
0252  * This enumerator maps:
0253  *   positive integer, true, yes, enabled, t -> 1
0254  *   0, false, no, disabled, f -> 0
0255  */
0256 extern pmix_mca_base_var_enum_t pmix_mca_base_var_enum_bool;
0257
0258 /**
0259  * Verbosity level enumerator
0260  */
0261 extern pmix_mca_base_var_enum_t pmix_mca_base_var_enum_verbose;
0262
0263 #endif /* !defined(MCA_BASE_VAR_ENUM_H) */