1// 2// Copyright (C) 2014 The Android Open Source Project 3// 4// Licensed under the Apache License, Version 2.0 (the "License"); 5// you may not use this file except in compliance with the License. 6// You may obtain a copy of the License at 7// 8// http://www.apache.org/licenses/LICENSE-2.0 9// 10// Unless required by applicable law or agreed to in writing, software 11// distributed under the License is distributed on an "AS IS" BASIS, 12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13// See the License for the specific language governing permissions and 14// limitations under the License. 15// 16 17#ifndef UPDATE_ENGINE_UPDATE_MANAGER_EVALUATION_CONTEXT_H_ 18#define UPDATE_ENGINE_UPDATE_MANAGER_EVALUATION_CONTEXT_H_ 19 20#include <map> 21#include <memory> 22#include <string> 23 24#include <base/bind.h> 25#include <base/callback.h> 26#include <base/memory/ref_counted.h> 27#include <base/memory/weak_ptr.h> 28#include <base/time/time.h> 29#include <brillo/message_loops/message_loop.h> 30 31#include "update_engine/common/clock_interface.h" 32#include "update_engine/update_manager/boxed_value.h" 33#include "update_engine/update_manager/variable.h" 34 35namespace chromeos_update_manager { 36 37// The EvaluationContext class is the interface between a policy implementation 38// and the state. The EvaluationContext tracks the variables used by a policy 39// request and caches the returned values, owning those cached values. 40// The same EvaluationContext should be re-used for all the evaluations of the 41// same policy request (an AsyncPolicyRequest might involve several 42// re-evaluations). Each evaluation of the EvaluationContext is run at a given 43// point in time, which is used as a reference for the evaluation timeout and 44// the time based queries of the policy, such as 45// Is{Wallclock,Monotonic}TimeGreaterThan(). 46// 47// Example: 48// 49// scoped_refptr<EvaluationContext> ec = new EvaluationContext(...); 50// 51// ... 52// // The following call to ResetEvaluation() is optional. Use it to reset the 53// // evaluation time if the EvaluationContext isn't used right after its 54// // construction. 55// ec->ResetEvaluation(); 56// EvalStatus status = policy->SomeMethod(ec, state, &result, args...); 57// 58// ... 59// // Run a closure when any of the used async variables changes its value or 60// // the timeout for re-query the values happens again. 61// ec->RunOnValueChangeOrTimeout(closure); 62// // If the provided |closure| wants to re-evaluate the policy, it should 63// // call ec->ResetEvaluation() to start a new evaluation. 64// 65class EvaluationContext : public base::RefCounted<EvaluationContext>, 66 private BaseVariable::ObserverInterface { 67 public: 68 EvaluationContext( 69 chromeos_update_engine::ClockInterface* clock, 70 base::TimeDelta evaluation_timeout, 71 base::TimeDelta expiration_timeout, 72 std::unique_ptr<base::Callback<void(EvaluationContext*)>> unregister_cb); 73 EvaluationContext(chromeos_update_engine::ClockInterface* clock, 74 base::TimeDelta evaluation_timeout) 75 : EvaluationContext( 76 clock, evaluation_timeout, base::TimeDelta::Max(), 77 std::unique_ptr<base::Callback<void(EvaluationContext*)>>()) {} 78 ~EvaluationContext(); 79 80 // Returns a pointer to the value returned by the passed variable |var|. The 81 // EvaluationContext instance keeps the ownership of the returned object. The 82 // returned object is valid during the life of the evaluation, even if the 83 // passed Variable changes it. 84 // 85 // In case of error, a null value is returned. 86 template<typename T> 87 const T* GetValue(Variable<T>* var); 88 89 // Returns whether the evaluation time has surpassed |timestamp|, on either 90 // the ClockInterface::GetWallclockTime() or 91 // ClockInterface::GetMonotonicTime() scales, respectively. 92 bool IsWallclockTimeGreaterThan(base::Time timestamp); 93 bool IsMonotonicTimeGreaterThan(base::Time timestamp); 94 95 // Returns whether the evaluation context has expired. 96 bool is_expired() const { return is_expired_; } 97 98 // TODO(deymo): Move the following methods to an interface only visible by the 99 // UpdateManager class and not the policy implementations. 100 101 // Resets the EvaluationContext to its initial state removing all the 102 // non-const cached variables and re-setting the evaluation time. This should 103 // be called right before any new evaluation starts. 104 void ResetEvaluation(); 105 106 // Clears the expiration status of the EvaluationContext and resets its 107 // expiration timeout based on |expiration_timeout_|. This should be called if 108 // expiration occurred, prior to re-evaluating the policy. 109 void ResetExpiration(); 110 111 // Schedules the passed |callback| closure to be called when a cached 112 // variable changes its value, a polling interval passes, or the context 113 // expiration occurs. If none of these events can happen, for example if 114 // there's no cached variable, this method returns false. 115 // 116 // Right before the passed closure is called the EvaluationContext is 117 // reseted, removing all the non-const cached values. 118 bool RunOnValueChangeOrTimeout(base::Closure callback); 119 120 // Returns a textual representation of the evaluation context, 121 // including the variables and their values. This is intended only 122 // to help with debugging and the format may change in the future. 123 std::string DumpContext() const; 124 125 // Removes all the Observers callbacks and timeout events scheduled by 126 // RunOnValueChangeOrTimeout(). Also releases and returns the closure 127 // associated with these events. This method is idempotent. 128 std::unique_ptr<base::Closure> RemoveObserversAndTimeout(); 129 130 private: 131 friend class UmEvaluationContextTest; 132 133 // BaseVariable::ObserverInterface override. 134 void ValueChanged(BaseVariable* var) override; 135 136 // Called from the main loop when a scheduled timeout has passed. 137 void OnTimeout(); 138 139 // Removes the observers from the used Variables and cancels the timeout, 140 // then executes the scheduled callback. 141 void OnValueChangedOrTimeout(); 142 143 // If |monotonic_deadline| is not Time::Max(), returns the remaining time 144 // until it is reached, or zero if it has passed. Otherwise, returns 145 // TimeDelta::Max(). 146 base::TimeDelta RemainingTime(base::Time monotonic_deadline) const; 147 148 // Returns a monotonic clock timestamp at which |timeout| will have elapsed 149 // since the current time. 150 base::Time MonotonicDeadline(base::TimeDelta timeout); 151 152 // A map to hold the cached values for every variable. 153 typedef std::map<BaseVariable*, BoxedValue> ValueCacheMap; 154 155 // The cached values of the called Variables. 156 ValueCacheMap value_cache_; 157 158 // A callback used for triggering re-evaluation upon a value change or poll 159 // timeout, or notifying about the evaluation context expiration. It is up to 160 // the caller to determine whether or not expiration occurred via 161 // is_expired(). 162 std::unique_ptr<base::Closure> callback_; 163 164 // The TaskId returned by the message loop identifying the timeout callback. 165 // Used for canceling the timeout callback. 166 brillo::MessageLoop::TaskId timeout_event_ = 167 brillo::MessageLoop::kTaskIdNull; 168 169 // Whether a timeout event firing marks the expiration of the evaluation 170 // context. 171 bool timeout_marks_expiration_; 172 173 // Whether the evaluation context has indeed expired. 174 bool is_expired_ = false; 175 176 // Pointer to the mockable clock interface; 177 chromeos_update_engine::ClockInterface* const clock_; 178 179 // The timestamps when the evaluation of this EvaluationContext started, 180 // corresponding to ClockInterface::GetWallclockTime() and 181 // ClockInterface::GetMonotonicTime(), respectively. These values are reset 182 // every time ResetEvaluation() is called. 183 base::Time evaluation_start_wallclock_; 184 base::Time evaluation_start_monotonic_; 185 186 // The timestamps when a reevaluation should be triggered due to various 187 // expected value changes, corresponding to ClockInterface::GetWallclockTime() 188 // and ClockInterface::GetMonotonicTIme(), respectively. These timestamps are 189 // greater or equal to corresponding |evaluation_start_{wallclock,monotonic}_| 190 // counterparts since they are in the future; however, they may be smaller 191 // than the current corresponding times during the course of evaluation. 192 base::Time reevaluation_time_wallclock_; 193 base::Time reevaluation_time_monotonic_; 194 195 // The timeout of an evaluation. 196 const base::TimeDelta evaluation_timeout_; 197 198 // The timestamp in the ClockInterface::GetMonotonicTime() scale at which the 199 // current evaluation should finish. 200 base::Time evaluation_monotonic_deadline_; 201 202 // The expiration timeout of the evaluation context. 203 const base::TimeDelta expiration_timeout_; 204 205 // The monotonic clock deadline at which expiration occurs. 206 base::Time expiration_monotonic_deadline_; 207 208 // A callback for unregistering the context upon destruction. 209 std::unique_ptr<base::Callback<void(EvaluationContext*)>> unregister_cb_; 210 211 base::WeakPtrFactory<EvaluationContext> weak_ptr_factory_; 212 213 DISALLOW_COPY_AND_ASSIGN(EvaluationContext); 214}; 215 216} // namespace chromeos_update_manager 217 218// Include the implementation of the template methods. 219#include "update_engine/update_manager/evaluation_context-inl.h" 220 221#endif // UPDATE_ENGINE_UPDATE_MANAGER_EVALUATION_CONTEXT_H_ 222