MediaWiki REL1_35
NameTableStore.php
Go to the documentation of this file.
1<?php
21namespace MediaWiki\Storage;
22
23use Exception;
25use Psr\Log\LoggerInterface;
27use Wikimedia\Assert\Assert;
31
37
40
42 private $cache;
43
45 private $logger;
46
48 private $tableCache = null;
49
51 private $domain = false;
52
54 private $cacheTTL;
55
57 private $table;
59 private $idField;
61 private $nameField;
63 private $normalizationCallback = null;
65 private $insertCallback = null;
66
85 public function __construct(
86 ILoadBalancer $dbLoadBalancer,
88 LoggerInterface $logger,
89 $table,
92 callable $normalizationCallback = null,
93 $dbDomain = false,
94 callable $insertCallback = null
95 ) {
96 $this->loadBalancer = $dbLoadBalancer;
97 $this->cache = $cache;
98 $this->logger = $logger;
99 $this->table = $table;
100 $this->idField = $idField;
101 $this->nameField = $nameField;
102 $this->normalizationCallback = $normalizationCallback;
103 $this->domain = $dbDomain;
104 $this->cacheTTL = IExpiringStore::TTL_MONTH;
105 $this->insertCallback = $insertCallback;
106 }
107
114 private function getDBConnection( $index, $flags = 0 ) {
115 return $this->loadBalancer->getConnectionRef( $index, [], $this->domain, $flags );
116 }
117
126 private function getCacheKey() {
127 return $this->cache->makeGlobalKey(
128 'NameTableSqlStore',
129 $this->table,
130 $this->loadBalancer->resolveDomainID( $this->domain )
131 );
132 }
133
138 private function normalizeName( $name ) {
139 if ( $this->normalizationCallback === null ) {
140 return $name;
141 }
142 return call_user_func( $this->normalizationCallback, $name );
143 }
144
162 public function acquireId( $name ) {
163 Assert::parameterType( 'string', $name, '$name' );
164 $name = $this->normalizeName( $name );
165
167 $searchResult = array_search( $name, $table, true );
168 if ( $searchResult === false ) {
169 $id = $this->store( $name );
170 if ( $id === null ) {
171 // RACE: $name was already in the db, probably just inserted, so load from master.
172 // Use DBO_TRX to avoid missing inserts due to other threads or REPEATABLE-READs.
173 $table = $this->reloadMap( ILoadBalancer::CONN_TRX_AUTOCOMMIT );
174
175 $searchResult = array_search( $name, $table, true );
176 if ( $searchResult === false ) {
177 // Insert failed due to IGNORE flag, but DB_MASTER didn't give us the data
178 $m = "No insert possible but master didn't give us a record for " .
179 "'{$name}' in '{$this->table}'";
180 $this->logger->error( $m );
181 throw new NameTableAccessException( $m );
182 }
183 } else {
184 if ( isset( $table[$id] ) ) {
185 // This can happen when a transaction is rolled back and acquireId is called in
186 // an onTransactionResolution() callback, which gets executed before retryStore()
187 // has a chance to run. The right thing to do in this case is to discard the old
188 // value. According to the contract of acquireId, the caller should not have
189 // used it outside the transaction, so it should not be persisted anywhere after
190 // the rollback.
191 $m = "Got ID $id for '$name' from insert"
192 . " into '{$this->table}', but ID $id was previously associated with"
193 . " the name '{$table[$id]}'. Overriding the old value, which presumably"
194 . " has been removed from the database due to a transaction rollback.";
195
196 $this->logger->warning( $m );
197 }
198
199 $table[$id] = $name;
200 $searchResult = $id;
201
202 // As store returned an ID we know we inserted so delete from WAN cache
203 $dbw = $this->getDBConnection( DB_MASTER );
204 $dbw->onTransactionPreCommitOrIdle( function () {
205 $this->cache->delete( $this->getCacheKey() );
206 }, __METHOD__ );
207 }
208 $this->tableCache = $table;
209 }
210
211 return $searchResult;
212 }
213
226 public function reloadMap( $connFlags = 0 ) {
227 if ( $connFlags !== 0 && defined( 'MW_PHPUNIT_TEST' ) ) {
228 // HACK: We can't use $connFlags while doing PHPUnit tests, because the
229 // fake database tables are bound to a single connection.
230 $connFlags = 0;
231 }
232
233 $dbw = $this->getDBConnection( DB_MASTER, $connFlags );
234 $this->tableCache = $this->loadTable( $dbw );
235 $dbw->onTransactionPreCommitOrIdle( function () {
236 $this->cache->reap( $this->getCacheKey(), INF );
237 }, __METHOD__ );
238
239 return $this->tableCache;
240 }
241
252 public function getId( $name ) {
253 Assert::parameterType( 'string', $name, '$name' );
254 $name = $this->normalizeName( $name );
255
257 $searchResult = array_search( $name, $table, true );
258
259 if ( $searchResult !== false ) {
260 return $searchResult;
261 }
262
263 throw NameTableAccessException::newFromDetails( $this->table, 'name', $name );
264 }
265
277 public function getName( $id ) {
278 Assert::parameterType( 'integer', $id, '$id' );
279
281 if ( array_key_exists( $id, $table ) ) {
282 return $table[$id];
283 }
284 $fname = __METHOD__;
285
286 $table = $this->cache->getWithSetCallback(
287 $this->getCacheKey(),
288 $this->cacheTTL,
289 function ( $oldValue, &$ttl, &$setOpts ) use ( $id, $fname ) {
290 // Check if cached value is up-to-date enough to have $id
291 if ( is_array( $oldValue ) && array_key_exists( $id, $oldValue ) ) {
292 // Completely leave the cache key alone
293 $ttl = WANObjectCache::TTL_UNCACHEABLE;
294 // Use the old value
295 return $oldValue;
296 }
297 // Regenerate from replica DB, and master DB if needed
298 foreach ( [ DB_REPLICA, DB_MASTER ] as $source ) {
299 // Log a fallback to master
300 if ( $source === DB_MASTER ) {
301 $this->logger->info(
302 $fname . ' falling back to master select from ' .
303 $this->table . ' with id ' . $id
304 );
305 }
306 $db = $this->getDBConnection( $source );
307 $cacheSetOpts = Database::getCacheSetOptions( $db );
308 $table = $this->loadTable( $db );
309 if ( array_key_exists( $id, $table ) ) {
310 break; // found it
311 }
312 }
313 // Use the value from last source checked
314 $setOpts += $cacheSetOpts;
315
316 return $table;
317 },
318 [ 'minAsOf' => INF ] // force callback run
319 );
320
321 $this->tableCache = $table;
322
323 if ( array_key_exists( $id, $table ) ) {
324 return $table[$id];
325 }
326
327 throw NameTableAccessException::newFromDetails( $this->table, 'id', $id );
328 }
329
337 public function getMap() {
338 return $this->getTableFromCachesOrReplica();
339 }
340
344 private function getTableFromCachesOrReplica() {
345 if ( $this->tableCache !== null ) {
346 return $this->tableCache;
347 }
348
349 $table = $this->cache->getWithSetCallback(
350 $this->getCacheKey(),
351 $this->cacheTTL,
352 function ( $oldValue, &$ttl, &$setOpts ) {
353 $dbr = $this->getDBConnection( DB_REPLICA );
354 $setOpts += Database::getCacheSetOptions( $dbr );
355 return $this->loadTable( $dbr );
356 }
357 );
358
359 $this->tableCache = $table;
360
361 return $table;
362 }
363
371 private function loadTable( IDatabase $db ) {
372 $result = $db->select(
373 $this->table,
374 [
375 'id' => $this->idField,
376 'name' => $this->nameField
377 ],
378 [],
379 __METHOD__,
380 [ 'ORDER BY' => 'id' ]
381 );
382
383 $assocArray = [];
384 foreach ( $result as $row ) {
385 $assocArray[$row->id] = $row->name;
386 }
387
388 return $assocArray;
389 }
390
397 private function store( $name ) {
398 Assert::parameterType( 'string', $name, '$name' );
399 Assert::parameter( $name !== '', '$name', 'should not be an empty string' );
400 // Note: this is only called internally so normalization of $name has already occurred.
401
402 $dbw = $this->getDBConnection( DB_MASTER );
403
404 $id = null;
405 $dbw->doAtomicSection(
406 __METHOD__,
407 function ( IDatabase $unused, $fname )
408 use ( $name, &$id, $dbw ) {
409 // NOTE: use IDatabase from the parent scope here, not the function parameter.
410 // If $dbw is a wrapper around the actual DB, we need to call the wrapper here,
411 // not the inner instance.
412 $dbw->insert(
413 $this->table,
414 $this->getFieldsToStore( $name ),
415 $fname,
416 [ 'IGNORE' ]
417 );
418
419 if ( $dbw->affectedRows() === 0 ) {
420 $this->logger->info(
421 'Tried to insert name into table ' . $this->table . ', but value already existed.'
422 );
423
424 return;
425 }
426
427 $id = $dbw->insertId();
428
429 // Any open transaction may still be rolled back. If that happens, we have to re-try the
430 // insertion and restore a consistent state of the cached table.
431 $dbw->onAtomicSectionCancel(
432 function ( $trigger, IDatabase $unused ) use ( $name, $id, $dbw ) {
433 $this->retryStore( $dbw, $name, $id );
434 },
435 $fname );
436 },
437 IDatabase::ATOMIC_CANCELABLE
438 );
439
440 return $id;
441 }
442
451 private function retryStore( IDatabase $dbw, $name, $id ) {
452 // NOTE: in the closure below, use the IDatabase from the original method call,
453 // not the one passed to the closure as a parameter.
454 // If $dbw is a wrapper around the actual DB, we need to call the wrapper,
455 // not the inner instance.
456
457 try {
458 $dbw->doAtomicSection(
459 __METHOD__,
460 function ( IDatabase $unused, $fname ) use ( $name, $id, $dbw ) {
461 // Try to insert a row with the ID we originally got.
462 // If that fails (because of a key conflict), we will just try to get another ID again later.
463 $dbw->insert(
464 $this->table,
465 $this->getFieldsToStore( $name, $id ),
466 $fname
467 );
468
469 // Make sure we re-load the map in case this gets rolled back again.
470 // We could re-try once more, but that bears the risk of an infinite loop.
471 // So let's just give up on the ID.
473 function ( $trigger, IDatabase $unused ) {
474 $this->logger->warning(
475 'Re-insertion of name into table ' . $this->table
476 . ' was rolled back. Giving up and reloading the cache.'
477 );
478 $this->reloadMap( ILoadBalancer::CONN_TRX_AUTOCOMMIT );
479 },
480 $fname
481 );
482
483 $this->logger->info(
484 'Re-insert name into table ' . $this->table . ' after failed transaction.'
485 );
486 },
487 IDatabase::ATOMIC_CANCELABLE
488 );
489 } catch ( Exception $ex ) {
490 $this->logger->error(
491 'Re-insertion of name into table ' . $this->table . ' failed: ' . $ex->getMessage()
492 );
493 } finally {
494 // NOTE: we reload regardless of whether the above insert succeeded. There is
495 // only three possibilities: the insert succeeded, so the new map will have
496 // the desired $id/$name mapping. Or the insert failed because another
497 // process already inserted that same $id/$name mapping, in which case the
498 // new map will also have it. Or another process grabbed the desired ID for
499 // another name, or the database refuses to insert the given ID into the
500 // auto increment field - in that case, the new map will not have a mapping
501 // for $name (or has a different mapping for $name). In that last case, we can
502 // only hope that the ID produced within the failed transaction has not been
503 // used outside that transaction.
504
505 $this->reloadMap( ILoadBalancer::CONN_TRX_AUTOCOMMIT );
506 }
507 }
508
514 private function getFieldsToStore( $name, $id = null ) {
515 $fields = [];
516
517 $fields[$this->nameField] = $name;
518
519 if ( $id !== null ) {
520 $fields[$this->idField] = $id;
521 }
522
523 if ( $this->insertCallback !== null ) {
524 $fields = call_user_func( $this->insertCallback, $fields );
525 }
526 return $fields;
527 }
528
529}
Exception representing a failure to look up a row from a name table.
static newFromDetails( $tableName, $accessType, $accessValue)
store( $name)
Stores the given name in the DB, returning the ID when an insert occurs.
getId( $name)
Get the id of the given name.
getName( $id)
Get the name of the given id.
getMap()
Get the whole table, in no particular order as a map of ids to names.
acquireId( $name)
Acquire the id of the given name.
retryStore(IDatabase $dbw, $name, $id)
After the initial insertion got rolled back, this can be used to try the insertion again,...
loadTable(IDatabase $db)
Gets the table from the db.
getCacheKey()
Gets the cache key for names.
reloadMap( $connFlags=0)
Reloads the name table from the master database, and purges the WAN cache entry.
__construct(ILoadBalancer $dbLoadBalancer, WANObjectCache $cache, LoggerInterface $logger, $table, $idField, $nameField, callable $normalizationCallback=null, $dbDomain=false, callable $insertCallback=null)
Multi-datacenter aware caching interface.
Relational database abstraction object.
Definition Database.php:50
Generic interface providing TTL constants for lightweight expiring object stores.
Basic database interface for live and lazy-loaded relation database handles.
Definition IDatabase.php:38
doAtomicSection( $fname, callable $callback, $cancelable=self::ATOMIC_NOT_CANCELABLE)
Perform an atomic section of reversable SQL statements from a callback.
select( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
Execute a SELECT query constructed using the various parameters provided.
onAtomicSectionCancel(callable $callback, $fname=__METHOD__)
Run a callback when the atomic section is cancelled.
insert( $table, $rows, $fname=__METHOD__, $options=[])
Insert the given row(s) into a table.
Database cluster connection, tracking, load balancing, and transaction manager interface.
$source
const DB_REPLICA
Definition defines.php:25
const DB_MASTER
Definition defines.php:29