experiment/SecExperimentPriv.h

   1 //
   2 //  SecExperimentPriv.h
   3 //  Security
   4 //
   5
   6 #ifndef SecExperiment_h
   7 #define SecExperiment_h
   8
   9 #include <Security/SecProtocolObject.h>
  10 #include <xpc/xpc.h>
  11
  12 #ifndef SEC_EXP_OBJECT_IMPL
  13 SEC_OBJECT_DECL(sec_experiment);
  14 #endif // !SEC_EXP_OBJECT_IMPL
  15
  16 SEC_ASSUME_NONNULL_BEGIN
  17
  18 extern const char *kSecExperimentTLSProbe;
  19 extern const char *kSecExperimentDefaultsDomain;
  20
  21 /*!
  22  * @block sec_experiment_run_block_t
  23  *
  24  * @abstract A block to execute an experiment with a loggable identifier
  25  *     and configuration. `identifier` will be uniquely associated with
  26  *     `experiment_config` and should be used when measuring data.
  27  *
  28  * @param identifier
  29  *     Identifier for the experiment.
  30  *
  31  * @param experiment_config
  32  *     Configuration of this experiment.
  33  *
  34  * @return True if the experiment ran successfully, and false otherwise.
  35  */
  36 typedef bool (^sec_experiment_run_block_t)(const char *identifier, xpc_object_t experiment_config);
  37
  38 /*!
  39  * @block sec_experiment_skip_block_t
  40  *
  41  * @abstract A block to execute when an experiment run is skipped.
  42  *
  43  * @param identifier
  44  *     Identifier for the experiment.
  45  */
  46 typedef void (^sec_experiment_skip_block_t)(const char *identifier);
  47
  48 /*!
  49  * @function sec_experiment_run
  50  *
  51  * @abstract
  52  *      Asynchronously run an experiment.
  53  *
  54  * @param experiment_name
  55  *      Name of the experiment to run.
  56  *
  57  * @param run_block
  58  *      A `sec_experiment_run_block_t` block upon which to execute the given experiment.
  59  *
  60  * @param skip_block
  61  *      An optional `sec_experiment_skip_block_t` block that is invoked when the chosen experiment is skipped.
  62  *
  63  * @return True if the experiment was started, and false otherwise.
  64  */
  65 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
  66 bool
  67 sec_experiment_run(const char *experiment_name,
  68                    sec_experiment_run_block_t run_block,
  69                    sec_experiment_skip_block_t _Nullable skip_block);
  70
  71 #define SEC_EXPERIMENT_HAS_ASYNC_WITH_SAMPLING_DISABLED 1
  72
  73 /*!
  74  * @function sec_experiment_run_with_sampling_disabled
  75  *
  76  * @abstract
  77  *      Synchronously run an experiment and optionally disable sampling. Passing `true` to the `sampling_disabled` parameter
  78  *      will cause the experiment to always run. Clients typically SHOULD NOT do this unless running as part of test tools and utilities.
  79  *
  80  * @param experiment_name
  81  *      Name of the experiment to run.
  82  *
  83  * @param run_block
  84  *      A `sec_experiment_run_block_t` block upon which to execute the given experiment.
  85  *
  86  * @param skip_block
  87  *      An optional `sec_experiment_skip_block_t` block that is invoked when the chosen experiment is skipped.
  88  *
  89  * @param sampling_disabled
  90  *      A boolean indicating if sampling should be disabled for the given asynchronous experiment run.
  91  */
  92 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
  93 bool
  94 sec_experiment_run_with_sampling_disabled(const char *experiment_name,
  95                                           sec_experiment_run_block_t run_block,
  96                                           sec_experiment_skip_block_t _Nullable skip_block,
  97                                           bool sampling_disabled);
  98
  99 /*!
 100  * @function sec_experiment_run_async
 101  *
 102  * @abstract
 103  *      Asynchronously run an experiment.
 104  *
 105  * @param experiment_name
 106  *      Name of the experiment to run.
 107  *
 108  * @param queue
 109  *      Queue on which to run the experiment.
 110  *
 111  * @param run_block
 112  *      A `sec_experiment_run_block_t` block upon which to execute the given experiment.
 113  *
 114  * @param skip_block
 115  *      An optional `sec_experiment_skip_block_t` block that is invoked when the chosen experiment is skipped.
 116  */
 117 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 118 bool
 119 sec_experiment_run_async(const char *experiment_name,
 120                          dispatch_queue_t queue,
 121                          sec_experiment_run_block_t run_block,
 122                          sec_experiment_skip_block_t _Nullable skip_block);
 123
 124 /*!
 125  * @function sec_experiment_run_async
 126  *
 127  * @abstract
 128  *      Asynchronously run an experiment and optionally disable sampling. Passing `true` to the `sampling_disabled` parameter
 129  *      will cause the experiment to always run. Clients typically SHOULD NOT do this unless running as part of test tools and utilities.
 130  *
 131  * @param experiment_name
 132  *      Name of the experiment to run.
 133  *
 134  * @param queue
 135  *      Queue on which to run the experiment.
 136  *
 137  * @param run_block
 138  *      A `sec_experiment_run_block_t` block upon which to execute the given experiment.
 139  *
 140  * @param skip_block
 141  *      An optional `sec_experiment_skip_block_t` block that is invoked when the chosen experiment is skipped.
 142  *
 143  * @param sampling_disabled
 144  *      A boolean indicating if sampling should be disabled for the given asynchronous experiment run.
 145  */
 146 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 147 bool
 148 sec_experiment_run_async_with_sampling_disabled(const char *experiment_name,
 149                                                 dispatch_queue_t queue,
 150                                                 sec_experiment_run_block_t run_block,
 151                                                 sec_experiment_skip_block_t _Nullable skip_block,
 152                                                 bool sampling_disabled);
 153
 154 /*!
 155  * @function sec_experiment_create
 156  *
 157  * @abstract
 158  *      Create an ARC-able `sec_experiment_t` instance
 159  *
 160  * @param experiment_name
 161  *      Name of the experiment.
 162  *
 163  * @return a `sec_experiment_t` instance.
 164  */
 165 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 166 SEC_RETURNS_RETAINED _Nullable sec_experiment_t
 167 sec_experiment_create(const char *experiment_name);
 168
 169 /*!
 170  * @function sec_experiment_set_sampling_disabled
 171  *
 172  * @abstract
 173  *      Set a flag to disable experiment sampling.
 174  *      This function should only be used for testing purposes.
 175  *
 176  * @param experiment
 177  *      A `sec_experiment_t` instance.
 178  *
 179  * @param sampling_disabled
 180  *      A flag indicating if sampling should be disabled.
 181  */
 182 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 183 void
 184 sec_experiment_set_sampling_disabled(sec_experiment_t experiment,
 185                                      bool sampling_disabled);
 186
 187 /*!
 188  * @function sec_experiment_copy_configuration
 189  *
 190  * @abstract
 191  *      Returns the configuration dictionary associated with the given experiment.
 192  *
 193  * @param experiment
 194  *      A valid `sec_experiment_t` instance.
 195  *
 196  * @return  xpc_object_t containing asset bundle, if client is not part of the experiment return NULL
 197  */
 198 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 199 SEC_RETURNS_RETAINED _Nullable xpc_object_t
 200 sec_experiment_copy_configuration(sec_experiment_t experiment);
 201
 202 SEC_ASSUME_NONNULL_END
 203
 204 #endif // SecExperiment_h