1 // Copyright 2022 gRPC authors. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef GRPC_SRC_CORE_LIB_EXPERIMENTS_CONFIG_H 16 #define GRPC_SRC_CORE_LIB_EXPERIMENTS_CONFIG_H 17 18 #include <grpc/support/port_platform.h> 19 20 #include <stddef.h> 21 #include <stdint.h> 22 23 #include "absl/functional/any_invocable.h" 24 #include "absl/strings/string_view.h" 25 26 // #define GRPC_EXPERIMENTS_ARE_FINAL 27 28 namespace grpc_core { 29 30 struct ExperimentMetadata { 31 const char* name; 32 const char* description; 33 const char* additional_constaints; 34 const uint8_t* required_experiments; 35 uint8_t num_required_experiments; 36 bool default_value; 37 bool allow_in_fuzzing_config; 38 }; 39 40 #ifndef GRPC_EXPERIMENTS_ARE_FINAL 41 // Return true if experiment \a experiment_id is enabled. 42 // Experiments are numbered by their order in the g_experiment_metadata array 43 // declared in experiments.h. 44 bool IsExperimentEnabled(size_t experiment_id); 45 46 // Given a test experiment id, returns true if the test experiment is enabled. 47 // Test experiments can be loaded using the LoadTestOnlyExperimentsFromMetadata 48 // method. 49 bool IsTestExperimentEnabled(size_t experiment_id); 50 51 // Slow check for if a named experiment is enabled. 52 // Parses the configuration and looks up the experiment in that, so it does not 53 // affect any global state, but it does require parsing the configuration every 54 // call! 55 bool IsExperimentEnabledInConfiguration(size_t experiment_id); 56 57 // Reload experiment state from config variables. 58 // Does not change ForceEnableExperiment state. 59 // Expects the caller to handle global thread safety - so really only 60 // appropriate for carefully written tests. 61 void TestOnlyReloadExperimentsFromConfigVariables(); 62 63 // Reload experiment state from passed metadata. 64 // Does not change ForceEnableExperiment state. 65 // Expects the caller to handle global thread safety - so really only 66 // appropriate for carefully written tests. 67 void LoadTestOnlyExperimentsFromMetadata( 68 const ExperimentMetadata* experiment_metadata, size_t num_experiments); 69 #endif 70 71 // Print out a list of all experiments that are built into this binary. 72 void PrintExperimentsList(); 73 74 // Force an experiment to be on or off. 75 // Must be called before experiments are configured (the first 76 // IsExperimentEnabled call). 77 // If the experiment does not exist, emits a warning but continues execution. 78 // If this is called twice for the same experiment, both calls must agree. 79 void ForceEnableExperiment(absl::string_view experiment_name, bool enable); 80 81 // Register a function to be called to validate the value an experiment can 82 // take subject to additional constraints. 83 // The function will take the ExperimentMetadata as its argument. It will return 84 // a bool value indicating the actual value the experiment should take. 85 void RegisterExperimentConstraintsValidator( 86 absl::AnyInvocable<bool(struct ExperimentMetadata)> check_constraints_cb); 87 88 } // namespace grpc_core 89 90 #endif // GRPC_SRC_CORE_LIB_EXPERIMENTS_CONFIG_H 91