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 // --------------------------------------------------------------------
  64 // How to customize the global configuration system:
  65 //
  66 // How to read and write configuration value can be customized.
  67 // Builtin system uses environment variables but it can be extended to
  68 // support command-line flag, file, etc.
  69 //
  70 // To customize it, following macros should be redefined.
  71 //
  72 //   GPR_GLOBAL_CONFIG_DEFINE_BOOL
  73 //   GPR_GLOBAL_CONFIG_DEFINE_INT32
  74 //   GPR_GLOBAL_CONFIG_DEFINE_STRING
  75 //
  76 // These macros should define functions for getting and setting variable.
  77 // For example, GPR_GLOBAL_CONFIG_DEFINE_BOOL(test, ...) would define two
  78 // functions.
  79 //
  80 //   bool gpr_global_config_get_test();
  81 //   void gpr_global_config_set_test(bool value);
  82
  83 #include "src/core/lib/gprpp/global_config_env.h"
  84
  85 #include "src/core/lib/gprpp/global_config_custom.h"
  86
  87 #endif /* GRPC_CORE_LIB_GPRPP_GLOBAL_CONFIG_H */