1 /* 2 * 3 * Copyright 2019 gRPC authors. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 */ 18 19 #ifndef GRPC_CORE_LIB_GPRPP_GLOBAL_CONFIG_H 20 #define GRPC_CORE_LIB_GPRPP_GLOBAL_CONFIG_H 21 22 #include <grpc/support/port_platform.h> 23 24 #include <stdint.h> 25 26 // -------------------------------------------------------------------- 27 // How to use global configuration variables: 28 // 29 // Defining config variables of a specified type: 30 // GPR_GLOBAL_CONFIG_DEFINE_*TYPE*(name, default_value, help); 31 // 32 // Supported TYPEs: BOOL, INT32, STRING 33 // 34 // It's recommended to use lowercase letters for 'name' like 35 // regular variables. The builtin configuration system uses 36 // environment variable and the name is converted to uppercase 37 // when looking up the value. For example, 38 // GPR_GLOBAL_CONFIG_DEFINE(grpc_latency) looks up the value with the 39 // name, "GRPC_LATENCY". 40 // 41 // The variable initially has the specified 'default_value' 42 // which must be an expression convertible to 'Type'. 43 // 'default_value' may be evaluated 0 or more times, 44 // and at an unspecified time; keep it 45 // simple and usually free of side-effects. 46 // 47 // GPR_GLOBAL_CONFIG_DEFINE_*TYPE* should not be called in a C++ header. 48 // It should be called at the top-level (outside any namespaces) 49 // in a .cc file. 50 // 51 // Getting the variables: 52 // GPR_GLOBAL_CONFIG_GET(name) 53 // 54 // If error happens during getting variables, error messages will 55 // be logged and default value will be returned. 56 // 57 // Setting the variables with new value: 58 // GPR_GLOBAL_CONFIG_SET(name, new_value) 59 // 60 // Declaring config variables for other modules to access: 61 // GPR_GLOBAL_CONFIG_DECLARE_*TYPE*(name) 62 // 63 // * Caveat for setting global configs at runtime 64 // 65 // Setting global configs at runtime multiple times is safe but it doesn't 66 // mean that it will have a valid effect on the module depending configs. 67 // In unit tests, it may be unpredictable to set different global configs 68 // between test cases because grpc init and shutdown can ignore changes. 69 // It's considered safe to set global configs before the first call to 70 // grpc_init(). 71 72 // -------------------------------------------------------------------- 73 // How to customize the global configuration system: 74 // 75 // How to read and write configuration value can be customized. 76 // Builtin system uses environment variables but it can be extended to 77 // support command-line flag, file, etc. 78 // 79 // To customize it, following macros should be redefined. 80 // 81 // GPR_GLOBAL_CONFIG_DEFINE_BOOL 82 // GPR_GLOBAL_CONFIG_DEFINE_INT32 83 // GPR_GLOBAL_CONFIG_DEFINE_STRING 84 // 85 // These macros should define functions for getting and setting variable. 86 // For example, GPR_GLOBAL_CONFIG_DEFINE_BOOL(test, ...) would define two 87 // functions. 88 // 89 // bool gpr_global_config_get_test(); 90 // void gpr_global_config_set_test(bool value); 91 92 #include "src/core/lib/gprpp/global_config_env.h" 93 94 #include "src/core/lib/gprpp/global_config_custom.h" 95 96 #endif /* GRPC_CORE_LIB_GPRPP_GLOBAL_CONFIG_H */ 97