wikimedia /
mediawiki
Duplicate code is one of the most pungent code smells. A rule that is often used is to re-structure code once it is duplicated in three or more places.
Common duplication problems, and corresponding solutions are:
Complex classes like LBFactory often do a lot of different things. To break such a class down, we need to identify a cohesive component within that class. A common approach to find such a component is to look for fields/methods that share the same prefixes, or suffixes. You can also have a look at the cohesion graph to spot any un-connected, or weakly-connected components.
Once you have determined the fields that belong together, you can apply the Extract Class refactoring. If the component makes sense as a sub-class, Extract Subclass is also a candidate, and is often faster.
While breaking up the class, it is a good idea to analyze how other classes use LBFactory, and based on these observations, apply Extract Interface, too.
| 1 | <?php |
||
| 30 | abstract class LBFactory { |
||
| 31 | /** @var ChronologyProtector */ |
||
| 32 | protected $chronProt; |
||
| 33 | /** @var object|string Class name or object With profileIn/profileOut methods */ |
||
| 34 | protected $profiler; |
||
| 35 | /** @var TransactionProfiler */ |
||
| 36 | protected $trxProfiler; |
||
| 37 | /** @var LoggerInterface */ |
||
| 38 | protected $replLogger; |
||
| 39 | /** @var LoggerInterface */ |
||
| 40 | protected $connLogger; |
||
| 41 | /** @var LoggerInterface */ |
||
| 42 | protected $queryLogger; |
||
| 43 | /** @var LoggerInterface */ |
||
| 44 | protected $perfLogger; |
||
| 45 | /** @var callable Error logger */ |
||
| 46 | protected $errorLogger; |
||
| 47 | /** @var BagOStuff */ |
||
| 48 | protected $srvCache; |
||
| 49 | /** @var BagOStuff */ |
||
| 50 | protected $memCache; |
||
| 51 | /** @var WANObjectCache */ |
||
| 52 | protected $wanCache; |
||
| 53 | |||
| 54 | /** @var DatabaseDomain Local domain */ |
||
| 55 | protected $localDomain; |
||
| 56 | /** @var string Local hostname of the app server */ |
||
| 57 | protected $hostname; |
||
| 58 | /** @var array Web request information about the client */ |
||
| 59 | protected $requestInfo; |
||
| 60 | |||
| 61 | /** @var mixed */ |
||
| 62 | protected $ticket; |
||
| 63 | /** @var string|bool String if a requested DBO_TRX transaction round is active */ |
||
| 64 | protected $trxRoundId = false; |
||
| 65 | /** @var string|bool Reason all LBs are read-only or false if not */ |
||
| 66 | protected $readOnlyReason = false; |
||
| 67 | /** @var callable[] */ |
||
| 68 | protected $replicationWaitCallbacks = []; |
||
| 69 | |||
| 70 | /** @var bool Whether this PHP instance is for a CLI script */ |
||
| 71 | protected $cliMode; |
||
| 72 | /** @var string Agent name for query profiling */ |
||
| 73 | protected $agent; |
||
| 74 | |||
| 75 | const SHUTDOWN_NO_CHRONPROT = 0; // don't save DB positions at all |
||
| 76 | const SHUTDOWN_CHRONPROT_ASYNC = 1; // save DB positions, but don't wait on remote DCs |
||
| 77 | const SHUTDOWN_CHRONPROT_SYNC = 2; // save DB positions, waiting on all DCs |
||
| 78 | |||
| 79 | private static $loggerFields = |
||
| 80 | [ 'replLogger', 'connLogger', 'queryLogger', 'perfLogger' ]; |
||
| 81 | |||
| 82 | /** |
||
| 83 | * Construct a manager of ILoadBalancer objects |
||
| 84 | * |
||
| 85 | * Sub-classes will extend the required keys in $conf with additional parameters |
||
| 86 | * |
||
| 87 | * @param $conf $params Array with keys: |
||
| 88 | * - localDomain: A DatabaseDomain or domain ID string. |
||
| 89 | * - readOnlyReason : Reason the master DB is read-only if so [optional] |
||
| 90 | * - srvCache : BagOStuff object for server cache [optional] |
||
| 91 | * - memCache : BagOStuff object for cluster memory cache [optional] |
||
| 92 | * - wanCache : WANObjectCache object [optional] |
||
| 93 | * - hostname : The name of the current server [optional] |
||
| 94 | * - cliMode: Whether the execution context is a CLI script. [optional] |
||
| 95 | * - profiler : Class name or instance with profileIn()/profileOut() methods. [optional] |
||
| 96 | * - trxProfiler: TransactionProfiler instance. [optional] |
||
| 97 | * - replLogger: PSR-3 logger instance. [optional] |
||
| 98 | * - connLogger: PSR-3 logger instance. [optional] |
||
| 99 | * - queryLogger: PSR-3 logger instance. [optional] |
||
| 100 | * - perfLogger: PSR-3 logger instance. [optional] |
||
| 101 | * - errorLogger : Callback that takes an Exception and logs it. [optional] |
||
| 102 | * @throws InvalidArgumentException |
||
| 103 | */ |
||
| 104 | public function __construct( array $conf ) { |
||
| 145 | |||
| 146 | /** |
||
| 147 | * Disables all load balancers. All connections are closed, and any attempt to |
||
| 148 | * open a new connection will result in a DBAccessError. |
||
| 149 | * @see ILoadBalancer::disable() |
||
| 150 | */ |
||
| 151 | public function destroy() { |
||
| 155 | |||
| 156 | /** |
||
| 157 | * Create a new load balancer object. The resulting object will be untracked, |
||
| 158 | * not chronology-protected, and the caller is responsible for cleaning it up. |
||
| 159 | * |
||
| 160 | * @param bool|string $domain Domain ID, or false for the current domain |
||
| 161 | * @return ILoadBalancer |
||
| 162 | */ |
||
| 163 | abstract public function newMainLB( $domain = false ); |
||
| 164 | |||
| 165 | /** |
||
| 166 | * Get a cached (tracked) load balancer object. |
||
| 167 | * |
||
| 168 | * @param bool|string $domain Domain ID, or false for the current domain |
||
| 169 | * @return ILoadBalancer |
||
| 170 | */ |
||
| 171 | abstract public function getMainLB( $domain = false ); |
||
| 172 | |||
| 173 | /** |
||
| 174 | * Create a new load balancer for external storage. The resulting object will be |
||
| 175 | * untracked, not chronology-protected, and the caller is responsible for |
||
| 176 | * cleaning it up. |
||
| 177 | * |
||
| 178 | * @param string $cluster External storage cluster, or false for core |
||
| 179 | * @param bool|string $domain Domain ID, or false for the current domain |
||
| 180 | * @return ILoadBalancer |
||
| 181 | */ |
||
| 182 | abstract protected function newExternalLB( $cluster, $domain = false ); |
||
| 183 | |||
| 184 | /** |
||
| 185 | * Get a cached (tracked) load balancer for external storage |
||
| 186 | * |
||
| 187 | * @param string $cluster External storage cluster, or false for core |
||
| 188 | * @param bool|string $domain Domain ID, or false for the current domain |
||
| 189 | * @return ILoadBalancer |
||
| 190 | */ |
||
| 191 | abstract public function getExternalLB( $cluster, $domain = false ); |
||
| 192 | |||
| 193 | /** |
||
| 194 | * Execute a function for each tracked load balancer |
||
| 195 | * The callback is called with the load balancer as the first parameter, |
||
| 196 | * and $params passed as the subsequent parameters. |
||
| 197 | * |
||
| 198 | * @param callable $callback |
||
| 199 | * @param array $params |
||
| 200 | */ |
||
| 201 | abstract public function forEachLB( $callback, array $params = [] ); |
||
| 202 | |||
| 203 | /** |
||
| 204 | * Prepare all tracked load balancers for shutdown |
||
| 205 | * @param integer $mode One of the class SHUTDOWN_* constants |
||
| 206 | * @param callable|null $workCallback Work to mask ChronologyProtector writes |
||
| 207 | */ |
||
| 208 | public function shutdown( |
||
| 220 | |||
| 221 | /** |
||
| 222 | * Call a method of each tracked load balancer |
||
| 223 | * |
||
| 224 | * @param string $methodName |
||
| 225 | * @param array $args |
||
| 226 | */ |
||
| 227 | protected function forEachLBCallMethod( $methodName, array $args = [] ) { |
||
| 235 | |||
| 236 | /** |
||
| 237 | * Commit all replica DB transactions so as to flush any REPEATABLE-READ or SSI snapshot |
||
| 238 | * |
||
| 239 | * @param string $fname Caller name |
||
| 240 | * @since 1.28 |
||
| 241 | */ |
||
| 242 | public function flushReplicaSnapshots( $fname = __METHOD__ ) { |
||
| 245 | |||
| 246 | /** |
||
| 247 | * Commit on all connections. Done for two reasons: |
||
| 248 | * 1. To commit changes to the masters. |
||
| 249 | * 2. To release the snapshot on all connections, master and replica DB. |
||
| 250 | * @param string $fname Caller name |
||
| 251 | * @param array $options Options map: |
||
| 252 | * - maxWriteDuration: abort if more than this much time was spent in write queries |
||
| 253 | */ |
||
| 254 | public function commitAll( $fname = __METHOD__, array $options = [] ) { |
||
| 258 | |||
| 259 | /** |
||
| 260 | * Flush any master transaction snapshots and set DBO_TRX (if DBO_DEFAULT is set) |
||
| 261 | * |
||
| 262 | * The DBO_TRX setting will be reverted to the default in each of these methods: |
||
| 263 | * - commitMasterChanges() |
||
| 264 | * - rollbackMasterChanges() |
||
| 265 | * - commitAll() |
||
| 266 | * |
||
| 267 | * This allows for custom transaction rounds from any outer transaction scope. |
||
| 268 | * |
||
| 269 | * @param string $fname |
||
| 270 | * @throws DBTransactionError |
||
| 271 | * @since 1.28 |
||
| 272 | */ |
||
| 273 | public function beginMasterChanges( $fname = __METHOD__ ) { |
||
| 284 | |||
| 285 | /** |
||
| 286 | * Commit changes on all master connections |
||
| 287 | * @param string $fname Caller name |
||
| 288 | * @param array $options Options map: |
||
| 289 | * - maxWriteDuration: abort if more than this much time was spent in write queries |
||
| 290 | * @throws Exception |
||
| 291 | */ |
||
| 292 | public function commitMasterChanges( $fname = __METHOD__, array $options = [] ) { |
||
| 322 | |||
| 323 | /** |
||
| 324 | * Rollback changes on all master connections |
||
| 325 | * @param string $fname Caller name |
||
| 326 | * @since 1.23 |
||
| 327 | */ |
||
| 328 | public function rollbackMasterChanges( $fname = __METHOD__ ) { |
||
| 337 | |||
| 338 | /** |
||
| 339 | * Log query info if multi DB transactions are going to be committed now |
||
| 340 | */ |
||
| 341 | private function logIfMultiDbTransaction() { |
||
| 360 | |||
| 361 | /** |
||
| 362 | * Determine if any master connection has pending changes |
||
| 363 | * @return bool |
||
| 364 | * @since 1.23 |
||
| 365 | */ |
||
| 366 | public function hasMasterChanges() { |
||
| 374 | |||
| 375 | /** |
||
| 376 | * Detemine if any lagged replica DB connection was used |
||
| 377 | * @return bool |
||
| 378 | * @since 1.28 |
||
| 379 | */ |
||
| 380 | public function laggedReplicaUsed() { |
||
| 388 | |||
| 389 | /** |
||
| 390 | * Determine if any master connection has pending/written changes from this request |
||
| 391 | * @param float $age How many seconds ago is "recent" [defaults to LB lag wait timeout] |
||
| 392 | * @return bool |
||
| 393 | * @since 1.27 |
||
| 394 | */ |
||
| 395 | public function hasOrMadeRecentMasterChanges( $age = null ) { |
||
| 402 | |||
| 403 | /** |
||
| 404 | * Waits for the replica DBs to catch up to the current master position |
||
| 405 | * |
||
| 406 | * Use this when updating very large numbers of rows, as in maintenance scripts, |
||
| 407 | * to avoid causing too much lag. Of course, this is a no-op if there are no replica DBs. |
||
| 408 | * |
||
| 409 | * By default this waits on all DB clusters actually used in this request. |
||
| 410 | * This makes sense when lag being waiting on is caused by the code that does this check. |
||
| 411 | * In that case, setting "ifWritesSince" can avoid the overhead of waiting for clusters |
||
| 412 | * that were not changed since the last wait check. To forcefully wait on a specific cluster |
||
| 413 | * for a given wiki, use the 'wiki' parameter. To forcefully wait on an "external" cluster, |
||
| 414 | * use the "cluster" parameter. |
||
| 415 | * |
||
| 416 | * Never call this function after a large DB write that is *still* in a transaction. |
||
| 417 | * It only makes sense to call this after the possible lag inducing changes were committed. |
||
| 418 | * |
||
| 419 | * @param array $opts Optional fields that include: |
||
| 420 | * - wiki : wait on the load balancer DBs that handles the given wiki |
||
| 421 | * - cluster : wait on the given external load balancer DBs |
||
| 422 | * - timeout : Max wait time. Default: ~60 seconds |
||
| 423 | * - ifWritesSince: Only wait if writes were done since this UNIX timestamp |
||
| 424 | * @throws DBReplicationWaitError If a timeout or error occured waiting on a DB cluster |
||
| 425 | * @since 1.27 |
||
| 426 | */ |
||
| 427 | public function waitForReplication( array $opts = [] ) { |
||
| 491 | |||
| 492 | /** |
||
| 493 | * Add a callback to be run in every call to waitForReplication() before waiting |
||
| 494 | * |
||
| 495 | * Callbacks must clear any transactions that they start |
||
| 496 | * |
||
| 497 | * @param string $name Callback name |
||
| 498 | * @param callable|null $callback Use null to unset a callback |
||
| 499 | * @since 1.28 |
||
| 500 | */ |
||
| 501 | public function setWaitForReplicationListener( $name, callable $callback = null ) { |
||
| 508 | |||
| 509 | /** |
||
| 510 | * Get a token asserting that no transaction writes are active |
||
| 511 | * |
||
| 512 | * @param string $fname Caller name (e.g. __METHOD__) |
||
| 513 | * @return mixed A value to pass to commitAndWaitForReplication() |
||
| 514 | * @since 1.28 |
||
| 515 | */ |
||
| 516 | public function getEmptyTransactionTicket( $fname ) { |
||
| 524 | |||
| 525 | /** |
||
| 526 | * Convenience method for safely running commitMasterChanges()/waitForReplication() |
||
| 527 | * |
||
| 528 | * This will commit and wait unless $ticket indicates it is unsafe to do so |
||
| 529 | * |
||
| 530 | * @param string $fname Caller name (e.g. __METHOD__) |
||
| 531 | * @param mixed $ticket Result of getEmptyTransactionTicket() |
||
| 532 | * @param array $opts Options to waitForReplication() |
||
| 533 | * @throws DBReplicationWaitError |
||
| 534 | * @since 1.28 |
||
| 535 | */ |
||
| 536 | public function commitAndWaitForReplication( $fname, $ticket, array $opts = [] ) { |
||
| 559 | |||
| 560 | /** |
||
| 561 | * @param string $dbName DB master name (e.g. "db1052") |
||
| 562 | * @return float|bool UNIX timestamp when client last touched the DB or false if not recent |
||
| 563 | * @since 1.28 |
||
| 564 | */ |
||
| 565 | public function getChronologyProtectorTouched( $dbName ) { |
||
| 568 | |||
| 569 | /** |
||
| 570 | * Disable the ChronologyProtector for all load balancers |
||
| 571 | * |
||
| 572 | * This can be called at the start of special API entry points |
||
| 573 | * |
||
| 574 | * @since 1.27 |
||
| 575 | */ |
||
| 576 | public function disableChronologyProtection() { |
||
| 579 | |||
| 580 | /** |
||
| 581 | * @return ChronologyProtector |
||
| 582 | */ |
||
| 583 | protected function getChronologyProtector() { |
||
| 611 | |||
| 612 | /** |
||
| 613 | * Get and record all of the staged DB positions into persistent memory storage |
||
| 614 | * |
||
| 615 | * @param ChronologyProtector $cp |
||
| 616 | * @param callable|null $workCallback Work to do instead of waiting on syncing positions |
||
| 617 | * @param string $mode One of (sync, async); whether to wait on remote datacenters |
||
| 618 | */ |
||
| 619 | protected function shutdownChronologyProtector( |
||
| 644 | |||
| 645 | /** |
||
| 646 | * Base parameters to LoadBalancer::__construct() |
||
| 647 | * @return array |
||
| 648 | */ |
||
| 649 | final protected function baseLoadBalancerParams() { |
||
| 666 | |||
| 667 | /** |
||
| 668 | * @param ILoadBalancer $lb |
||
| 669 | */ |
||
| 670 | protected function initLoadBalancer( ILoadBalancer $lb ) { |
||
| 675 | |||
| 676 | /** |
||
| 677 | * Set a new table prefix for the existing local domain ID for testing |
||
| 678 | * |
||
| 679 | * @param string $prefix |
||
| 680 | * @since 1.28 |
||
| 681 | */ |
||
| 682 | public function setDomainPrefix( $prefix ) { |
||
| 693 | |||
| 694 | /** |
||
| 695 | * Close all open database connections on all open load balancers. |
||
| 696 | * @since 1.28 |
||
| 697 | */ |
||
| 698 | public function closeAll() { |
||
| 701 | |||
| 702 | /** |
||
| 703 | * @param string $agent Agent name for query profiling |
||
| 704 | * @since 1.28 |
||
| 705 | */ |
||
| 706 | public function setAgentName( $agent ) { |
||
| 709 | |||
| 710 | /** |
||
| 711 | * Append ?cpPosTime parameter to a URL for ChronologyProtector purposes if needed |
||
| 712 | * |
||
| 713 | * Note that unlike cookies, this works accross domains |
||
| 714 | * |
||
| 715 | * @param string $url |
||
| 716 | * @param float $time UNIX timestamp just before shutdown() was called |
||
| 717 | * @return string |
||
| 718 | * @since 1.28 |
||
| 719 | */ |
||
| 720 | public function appendPreShutdownTimeAsQuery( $url, $time ) { |
||
| 732 | |||
| 733 | /** |
||
| 734 | * @param array $info Map of fields, including: |
||
| 735 | * - IPAddress : IP address |
||
| 736 | * - UserAgent : User-Agent HTTP header |
||
| 737 | * - ChronologyProtection : cookie/header value specifying ChronologyProtector usage |
||
| 738 | * @since 1.28 |
||
| 739 | */ |
||
| 740 | public function setRequestInfo( array $info ) { |
||
| 743 | |||
| 744 | function __destruct() { |
||
| 747 | } |
||
| 748 |
Loading history...
This check marks PHPDoc comments that could not be parsed by our parser. To see which comment annotations we can parse, please refer to our documentation on supported doc-types.