Code Coverage |
||||||||||
Lines |
Functions and Methods |
Classes and Traits |
||||||||
| Total | |
44.97% |
76 / 169 |
|
33.33% |
6 / 18 |
CRAP | |
0.00% |
0 / 1 |
| MultiWriteBagOStuff | |
44.97% |
76 / 169 |
|
33.33% |
6 / 18 |
382.45 | |
0.00% |
0 / 1 |
| __construct | |
76.47% |
13 / 17 |
|
0.00% |
0 / 1 |
7.64 | |||
| get | |
0.00% |
0 / 32 |
|
0.00% |
0 / 1 |
56 | |||
| set | |
100.00% |
7 / 7 |
|
100.00% |
1 / 1 |
1 | |||
| delete | |
100.00% |
7 / 7 |
|
100.00% |
1 / 1 |
1 | |||
| add | |
94.44% |
17 / 18 |
|
0.00% |
0 / 1 |
3.00 | |||
| merge | |
100.00% |
7 / 7 |
|
100.00% |
1 / 1 |
1 | |||
| changeTTL | |
0.00% |
0 / 7 |
|
0.00% |
0 / 1 |
2 | |||
| lock | |
0.00% |
0 / 7 |
|
0.00% |
0 / 1 |
2 | |||
| unlock | |
0.00% |
0 / 7 |
|
0.00% |
0 / 1 |
2 | |||
| deleteObjectsExpiringBefore | |
0.00% |
0 / 5 |
|
0.00% |
0 / 1 |
12 | |||
| getMulti | |
0.00% |
0 / 6 |
|
0.00% |
0 / 1 |
12 | |||
| setMulti | |
0.00% |
0 / 7 |
|
0.00% |
0 / 1 |
2 | |||
| deleteMulti | |
0.00% |
0 / 7 |
|
0.00% |
0 / 1 |
2 | |||
| changeTTLMulti | |
0.00% |
0 / 7 |
|
0.00% |
0 / 1 |
2 | |||
| incrWithInit | |
100.00% |
7 / 7 |
|
100.00% |
1 / 1 |
1 | |||
| setMockTime | |
0.00% |
0 / 3 |
|
0.00% |
0 / 1 |
6 | |||
| callKeyMethodOnTierCache | |
100.00% |
1 / 1 |
|
100.00% |
1 / 1 |
1 | |||
| callKeyWriteMethodOnTierCaches | |
100.00% |
17 / 17 |
|
100.00% |
1 / 1 |
9 | |||
| 1 | <?php |
| 2 | /** |
| 3 | * Wrapper for object caching in different caches. |
| 4 | * |
| 5 | * This program is free software; you can redistribute it and/or modify |
| 6 | * it under the terms of the GNU General Public License as published by |
| 7 | * the Free Software Foundation; either version 2 of the License, or |
| 8 | * (at your option) any later version. |
| 9 | * |
| 10 | * This program is distributed in the hope that it will be useful, |
| 11 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 13 | * GNU General Public License for more details. |
| 14 | * |
| 15 | * You should have received a copy of the GNU General Public License along |
| 16 | * with this program; if not, write to the Free Software Foundation, Inc., |
| 17 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. |
| 18 | * http://www.gnu.org/copyleft/gpl.html |
| 19 | * |
| 20 | * @file |
| 21 | * @ingroup Cache |
| 22 | */ |
| 23 | use Wikimedia\ObjectFactory\ObjectFactory; |
| 24 | |
| 25 | /** |
| 26 | * A cache class that replicates all writes to multiple child caches. Reads |
| 27 | * are implemented by reading from the caches in the order they are given in |
| 28 | * the configuration until a cache gives a positive result. |
| 29 | * |
| 30 | * Note that cache key construction will use the first cache backend in the list, |
| 31 | * so make sure that the other backends can handle such keys (e.g. via encoding). |
| 32 | * |
| 33 | * @newable |
| 34 | * @ingroup Cache |
| 35 | */ |
| 36 | class MultiWriteBagOStuff extends BagOStuff { |
| 37 | /** @var BagOStuff[] Backing cache stores in order of highest to lowest tier */ |
| 38 | protected $caches; |
| 39 | |
| 40 | /** @var bool Use async secondary writes */ |
| 41 | protected $asyncWrites = false; |
| 42 | /** @var int[] List of all backing cache indexes */ |
| 43 | protected $cacheIndexes = []; |
| 44 | |
| 45 | /** @var int TTL when a key is copied to a higher cache tier */ |
| 46 | private static $UPGRADE_TTL = 3600; |
| 47 | |
| 48 | /** |
| 49 | * @stable to call |
| 50 | * @param array $params |
| 51 | * - caches: A numbered array of either ObjectFactory::getObjectFromSpec |
| 52 | * arrays yielding BagOStuff objects or direct BagOStuff objects. |
| 53 | * If using the former, the 'args' field *must* be set. |
| 54 | * The first cache is the primary one, being the first to |
| 55 | * be read in the fallback chain. Writes happen to all stores |
| 56 | * in the order they are defined. However, lock()/unlock() calls |
| 57 | * only use the primary store. |
| 58 | * - replication: Either 'sync' or 'async'. This controls whether writes |
| 59 | * to secondary stores are deferred when possible. To use 'async' writes |
| 60 | * requires the 'asyncHandler' option to be set as well. |
| 61 | * Async writes can increase the chance of some race conditions |
| 62 | * or cause keys to expire seconds later than expected. It is |
| 63 | * safe to use for modules when cached values: are immutable, |
| 64 | * invalidation uses logical TTLs, invalidation uses etag/timestamp |
| 65 | * validation against the DB, or merge() is used to handle races. |
| 66 | * @phan-param array{caches:array<int,array|BagOStuff>,replication:string} $params |
| 67 | * @throws InvalidArgumentException |
| 68 | */ |
| 69 | public function __construct( $params ) { |
| 70 | parent::__construct( $params ); |
| 71 | |
| 72 | if ( empty( $params['caches'] ) || !is_array( $params['caches'] ) ) { |
| 73 | throw new InvalidArgumentException( |
| 74 | __METHOD__ . ': "caches" parameter must be an array of caches' |
| 75 | ); |
| 76 | } |
| 77 | |
| 78 | $this->caches = []; |
| 79 | foreach ( $params['caches'] as $cacheInfo ) { |
| 80 | if ( $cacheInfo instanceof BagOStuff ) { |
| 81 | $this->caches[] = $cacheInfo; |
| 82 | } else { |
| 83 | $this->caches[] = ObjectFactory::getObjectFromSpec( $cacheInfo ); |
| 84 | } |
| 85 | } |
| 86 | |
| 87 | $this->attrMap = $this->mergeFlagMaps( $this->caches ); |
| 88 | |
| 89 | $this->asyncWrites = ( |
| 90 | isset( $params['replication'] ) && |
| 91 | $params['replication'] === 'async' && |
| 92 | is_callable( $this->asyncHandler ) |
| 93 | ); |
| 94 | |
| 95 | $this->cacheIndexes = array_keys( $this->caches ); |
| 96 | } |
| 97 | |
| 98 | public function get( $key, $flags = 0 ) { |
| 99 | $args = func_get_args(); |
| 100 | |
| 101 | if ( $this->fieldHasFlags( $flags, self::READ_LATEST ) ) { |
| 102 | // If the latest write was a delete(), we do NOT want to fallback |
| 103 | // to the other tiers and possibly see the old value. Also, this |
| 104 | // is used by merge(), which only needs to hit the primary. |
| 105 | return $this->callKeyMethodOnTierCache( |
| 106 | 0, |
| 107 | __FUNCTION__, |
| 108 | self::ARG0_KEY, |
| 109 | self::RES_NONKEY, |
| 110 | $args |
| 111 | ); |
| 112 | } |
| 113 | |
| 114 | $value = false; |
| 115 | // backends checked |
| 116 | $missIndexes = []; |
| 117 | foreach ( $this->cacheIndexes as $i ) { |
| 118 | $value = $this->callKeyMethodOnTierCache( |
| 119 | $i, |
| 120 | __FUNCTION__, |
| 121 | self::ARG0_KEY, |
| 122 | self::RES_NONKEY, |
| 123 | $args |
| 124 | ); |
| 125 | if ( $value !== false ) { |
| 126 | break; |
| 127 | } |
| 128 | $missIndexes[] = $i; |
| 129 | } |
| 130 | |
| 131 | if ( |
| 132 | $value !== false && |
| 133 | $this->fieldHasFlags( $flags, self::READ_VERIFIED ) && |
| 134 | $missIndexes |
| 135 | ) { |
| 136 | // Backfill the value to the higher (and often faster/smaller) cache tiers |
| 137 | $this->callKeyWriteMethodOnTierCaches( |
| 138 | $missIndexes, |
| 139 | 'set', |
| 140 | self::ARG0_KEY, |
| 141 | self::RES_NONKEY, |
| 142 | [ $key, $value, self::$UPGRADE_TTL ] |
| 143 | ); |
| 144 | } |
| 145 | |
| 146 | return $value; |
| 147 | } |
| 148 | |
| 149 | public function set( $key, $value, $exptime = 0, $flags = 0 ) { |
| 150 | return $this->callKeyWriteMethodOnTierCaches( |
| 151 | $this->cacheIndexes, |
| 152 | __FUNCTION__, |
| 153 | self::ARG0_KEY, |
| 154 | self::RES_NONKEY, |
| 155 | func_get_args() |
| 156 | ); |
| 157 | } |
| 158 | |
| 159 | public function delete( $key, $flags = 0 ) { |
| 160 | return $this->callKeyWriteMethodOnTierCaches( |
| 161 | $this->cacheIndexes, |
| 162 | __FUNCTION__, |
| 163 | self::ARG0_KEY, |
| 164 | self::RES_NONKEY, |
| 165 | func_get_args() |
| 166 | ); |
| 167 | } |
| 168 | |
| 169 | public function add( $key, $value, $exptime = 0, $flags = 0 ) { |
| 170 | // Try the write to the top-tier cache |
| 171 | $ok = $this->callKeyMethodOnTierCache( |
| 172 | 0, |
| 173 | __FUNCTION__, |
| 174 | self::ARG0_KEY, |
| 175 | self::RES_NONKEY, |
| 176 | func_get_args() |
| 177 | ); |
| 178 | |
| 179 | if ( $ok ) { |
| 180 | // Relay the add() using set() if it succeeded. This is meant to handle certain |
| 181 | // migration scenarios where the same store might get written to twice for certain |
| 182 | // keys. In that case, it makes no sense to return false due to "self-conflicts". |
| 183 | $okSecondaries = $this->callKeyWriteMethodOnTierCaches( |
| 184 | array_slice( $this->cacheIndexes, 1 ), |
| 185 | 'set', |
| 186 | self::ARG0_KEY, |
| 187 | self::RES_NONKEY, |
| 188 | [ $key, $value, $exptime, $flags ] |
| 189 | ); |
| 190 | if ( $okSecondaries === false ) { |
| 191 | $ok = false; |
| 192 | } |
| 193 | } |
| 194 | |
| 195 | return $ok; |
| 196 | } |
| 197 | |
| 198 | public function merge( $key, callable $callback, $exptime = 0, $attempts = 10, $flags = 0 ) { |
| 199 | return $this->callKeyWriteMethodOnTierCaches( |
| 200 | $this->cacheIndexes, |
| 201 | __FUNCTION__, |
| 202 | self::ARG0_KEY, |
| 203 | self::RES_NONKEY, |
| 204 | func_get_args() |
| 205 | ); |
| 206 | } |
| 207 | |
| 208 | public function changeTTL( $key, $exptime = 0, $flags = 0 ) { |
| 209 | return $this->callKeyWriteMethodOnTierCaches( |
| 210 | $this->cacheIndexes, |
| 211 | __FUNCTION__, |
| 212 | self::ARG0_KEY, |
| 213 | self::RES_NONKEY, |
| 214 | func_get_args() |
| 215 | ); |
| 216 | } |
| 217 | |
| 218 | public function lock( $key, $timeout = 6, $exptime = 6, $rclass = '' ) { |
| 219 | // Only need to lock the first cache; also avoids deadlocks |
| 220 | return $this->callKeyMethodOnTierCache( |
| 221 | 0, |
| 222 | __FUNCTION__, |
| 223 | self::ARG0_KEY, |
| 224 | self::RES_NONKEY, |
| 225 | func_get_args() |
| 226 | ); |
| 227 | } |
| 228 | |
| 229 | public function unlock( $key ) { |
| 230 | // Only the first cache is locked |
| 231 | return $this->callKeyMethodOnTierCache( |
| 232 | 0, |
| 233 | __FUNCTION__, |
| 234 | self::ARG0_KEY, |
| 235 | self::RES_NONKEY, |
| 236 | func_get_args() |
| 237 | ); |
| 238 | } |
| 239 | |
| 240 | public function deleteObjectsExpiringBefore( |
| 241 | $timestamp, |
| 242 | callable $progress = null, |
| 243 | $limit = INF, |
| 244 | string $tag = null |
| 245 | ) { |
| 246 | $ret = false; |
| 247 | foreach ( $this->caches as $cache ) { |
| 248 | if ( $cache->deleteObjectsExpiringBefore( $timestamp, $progress, $limit, $tag ) ) { |
| 249 | $ret = true; |
| 250 | } |
| 251 | } |
| 252 | |
| 253 | return $ret; |
| 254 | } |
| 255 | |
| 256 | public function getMulti( array $keys, $flags = 0 ) { |
| 257 | // Just iterate over each key in order to handle all the backfill logic |
| 258 | $res = []; |
| 259 | foreach ( $keys as $key ) { |
| 260 | $val = $this->get( $key, $flags ); |
| 261 | if ( $val !== false ) { |
| 262 | $res[$key] = $val; |
| 263 | } |
| 264 | } |
| 265 | |
| 266 | return $res; |
| 267 | } |
| 268 | |
| 269 | public function setMulti( array $valueByKey, $exptime = 0, $flags = 0 ) { |
| 270 | return $this->callKeyWriteMethodOnTierCaches( |
| 271 | $this->cacheIndexes, |
| 272 | __FUNCTION__, |
| 273 | self::ARG0_KEYMAP, |
| 274 | self::RES_NONKEY, |
| 275 | func_get_args() |
| 276 | ); |
| 277 | } |
| 278 | |
| 279 | public function deleteMulti( array $keys, $flags = 0 ) { |
| 280 | return $this->callKeyWriteMethodOnTierCaches( |
| 281 | $this->cacheIndexes, |
| 282 | __FUNCTION__, |
| 283 | self::ARG0_KEYARR, |
| 284 | self::RES_NONKEY, |
| 285 | func_get_args() |
| 286 | ); |
| 287 | } |
| 288 | |
| 289 | public function changeTTLMulti( array $keys, $exptime, $flags = 0 ) { |
| 290 | return $this->callKeyWriteMethodOnTierCaches( |
| 291 | $this->cacheIndexes, |
| 292 | __FUNCTION__, |
| 293 | self::ARG0_KEYARR, |
| 294 | self::RES_NONKEY, |
| 295 | func_get_args() |
| 296 | ); |
| 297 | } |
| 298 | |
| 299 | public function incrWithInit( $key, $exptime, $step = 1, $init = null, $flags = 0 ) { |
| 300 | return $this->callKeyWriteMethodOnTierCaches( |
| 301 | $this->cacheIndexes, |
| 302 | __FUNCTION__, |
| 303 | self::ARG0_KEY, |
| 304 | self::RES_NONKEY, |
| 305 | func_get_args() |
| 306 | ); |
| 307 | } |
| 308 | |
| 309 | public function setMockTime( &$time ) { |
| 310 | parent::setMockTime( $time ); |
| 311 | foreach ( $this->caches as $cache ) { |
| 312 | $cache->setMockTime( $time ); |
| 313 | } |
| 314 | } |
| 315 | |
| 316 | /** |
| 317 | * Call a method on the cache instance for the given cache tier (index) |
| 318 | * |
| 319 | * @param int $index Cache tier |
| 320 | * @param string $method Method name |
| 321 | * @param int $arg0Sig BagOStuff::A0_* constant describing argument 0 |
| 322 | * @param int $rvSig BagOStuff::RV_* constant describing the return value |
| 323 | * @param array $args Method arguments |
| 324 | * @return mixed The result of calling the given method |
| 325 | */ |
| 326 | private function callKeyMethodOnTierCache( $index, $method, $arg0Sig, $rvSig, array $args ) { |
| 327 | return $this->caches[$index]->proxyCall( $method, $arg0Sig, $rvSig, $args, $this ); |
| 328 | } |
| 329 | |
| 330 | /** |
| 331 | * Call a write method on the cache instances, in order, for the given tiers (indexes) |
| 332 | * |
| 333 | * @param int[] $indexes List of cache tiers |
| 334 | * @param string $method Method name |
| 335 | * @param int $arg0Sig BagOStuff::ARG0_* constant describing argument 0 |
| 336 | * @param int $resSig BagOStuff::RES_* constant describing the return value |
| 337 | * @param array $args Method arguments |
| 338 | * @return mixed First synchronous result or false if any failed; null if all asynchronous |
| 339 | */ |
| 340 | private function callKeyWriteMethodOnTierCaches( |
| 341 | array $indexes, |
| 342 | $method, |
| 343 | $arg0Sig, |
| 344 | $resSig, |
| 345 | array $args |
| 346 | ) { |
| 347 | $res = null; |
| 348 | |
| 349 | if ( $this->asyncWrites && array_diff( $indexes, [ 0 ] ) && $method !== 'merge' ) { |
| 350 | // Deep-clone $args to prevent misbehavior when something writes an |
| 351 | // object to the BagOStuff then modifies it afterwards, e.g. T168040. |
| 352 | $args = unserialize( serialize( $args ) ); |
| 353 | } |
| 354 | |
| 355 | foreach ( $indexes as $i ) { |
| 356 | $cache = $this->caches[$i]; |
| 357 | |
| 358 | if ( $i == 0 || !$this->asyncWrites ) { |
| 359 | // Tier 0 store or in sync mode: write synchronously and get result |
| 360 | $storeRes = $cache->proxyCall( $method, $arg0Sig, $resSig, $args, $this ); |
| 361 | if ( $storeRes === false ) { |
| 362 | $res = false; |
| 363 | } elseif ( $res === null ) { |
| 364 | // first synchronous result |
| 365 | $res = $storeRes; |
| 366 | } |
| 367 | } else { |
| 368 | // Secondary write in async mode: do not block this HTTP request |
| 369 | ( $this->asyncHandler )( |
| 370 | function () use ( $cache, $method, $arg0Sig, $resSig, $args ) { |
| 371 | $cache->proxyCall( $method, $arg0Sig, $resSig, $args, $this ); |
| 372 | } |
| 373 | ); |
| 374 | } |
| 375 | } |
| 376 | |
| 377 | return $res; |
| 378 | } |
| 379 | } |