legacy-libs/grpc-cloned/deps/grpc/src/core/lib/gprpp/global_config.h

   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 */