/** @var int DB handle should have DBO_TRX disabled and the caller will leave it as such */
const CONN_TRX_AUTOCOMMIT = 1;
+ /** @var int Return null on connection failure instead of throwing an exception */
+ const CONN_SILENCE_ERRORS = 2;
/** @var string Manager of ILoadBalancer instances is running post-commit callbacks */
const STAGE_POSTCOMMIT_CALLBACKS = 'stage-postcommit-callbacks';
* - errorLogger : Callback that takes an Exception and logs it. [optional]
* - deprecationLogger: Callback to log a deprecation warning. [optional]
* - roundStage: STAGE_POSTCOMMIT_* class constant; for internal use [optional]
+ * - ownerId: integer ID of an LBFactory instance that manages this instance [optional]
* @throws InvalidArgumentException
*/
public function __construct( array $params );
/**
* @param DatabaseDomain|string|bool $domain Database domain
- * @return string Value of $domain if provided or the local domain otherwise
+ * @return string Value of $domain if it is foreign or the local domain otherwise
* @since 1.32
*/
public function resolveDomainID( $domain );
/**
* Get the index of the reader connection, which may be a replica DB
*
- * This takes into account load ratios and lag times. It should
- * always return a consistent index during a given invocation.
+ * This takes into account load ratios and lag times. It should return a consistent
+ * index during the life time of the load balancer. This initially checks replica DBs
+ * for connectivity to avoid returning an unusable server. This means that connections
+ * might be attempted by calling this method (usally one at the most but possibly more).
+ * Subsequent calls with the same $group will not need to make new connection attempts
+ * since the acquired connection for each group is preserved.
*
- * Side effect: opens connections to databases
- * @param string|bool $group Query group, or false for the generic reader
+ * @param string|bool $group Query group, or false for the generic group
* @param string|bool $domain Domain ID, or false for the current domain
* @throws DBError
* @return bool|int|string
public function getReaderIndex( $group = false, $domain = false );
/**
- * Set the master wait position
+ * Set the master position to reach before the next generic group DB handle query
*
- * If a DB_REPLICA connection has been opened already, then wait immediately.
- * Otherwise sets a variable telling it to wait if such a connection is opened.
+ * If a generic replica DB connection is already open then this immediately waits
+ * for that DB to catch up to the specified replication position. Otherwise, it will
+ * do so once such a connection is opened.
*
- * This only applies to connections to the generic replica DB for this request.
* If a timeout happens when waiting, then getLaggedReplicaMode()/laggedReplicaUsed()
* will return true.
*
public function waitFor( $pos );
/**
- * Set the master wait position and wait for a "generic" replica DB to catch up to it
+ * Set the master wait position and wait for a generic replica DB to catch up to it
*
* This can be used a faster proxy for waitForAll()
*
*
* @note This method throws DBAccessError if ILoadBalancer::disable() was called
*
- * @throws DBError
- * @return Database
+ * @throws DBError If any error occurs that prevents the yielding of a (live) IDatabase
+ * @return IDatabase|bool This returns false on failure if CONN_SILENCE_ERRORS is set
*/
public function getConnection( $i, $groups = [], $domain = false, $flags = 0 );
*
* @see ILoadBalancer::getConnection() for parameter information
*
- * @param int $db Server index or DB_MASTER/DB_REPLICA
+ * @param int $i Server index or DB_MASTER/DB_REPLICA
* @param array|string|bool $groups Query group(s), or false for the generic reader
* @param string|bool $domain Domain ID, or false for the current domain
* @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTOCOMMIT)
* @return MaintainableDBConnRef
*/
- public function getMaintenanceConnectionRef( $db, $groups = [], $domain = false, $flags = 0 );
-
- /**
- * Open a connection to the server given by the specified index
- *
- * The index must be an actual index into the array. If a connection to the server is
- * already open and not considered an "in use" foreign connection, this simply returns it.
- *
- * Avoid using CONN_TRX_AUTOCOMMIT for databases with ATTR_DB_LEVEL_LOCKING (e.g. sqlite)
- * in order to avoid deadlocks. ILoadBalancer::getServerAttributes() can be used to check
- * such flags beforehand.
- *
- * If the caller uses $domain or sets CONN_TRX_AUTOCOMMIT in $flags, then it must
- * also call ILoadBalancer::reuseConnection() on the handle when finished using it.
- * In all other cases, this is not necessary, though not harmful either.
- * Avoid the use of begin() or startAtomic() on any such connections.
- *
- * @note This method throws DBAccessError if ILoadBalancer::disable() was called
- *
- * @param int $i Server index (does not support DB_MASTER/DB_REPLICA)
- * @param string|bool $domain Domain ID, or false for the current domain
- * @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTOCOMMIT)
- * @return Database|bool Returns false on errors
- * @throws DBAccessError
- */
- public function openConnection( $i, $domain = false, $flags = 0 );
+ public function getMaintenanceConnectionRef( $i, $groups = [], $domain = false, $flags = 0 );
/**
* @return int
/**
* Commit transactions on all open connections
* @param string $fname Caller name
+ * @param int|null $owner ID of the calling instance (e.g. the LBFactory ID)
* @throws DBExpectedError
*/
- public function commitAll( $fname = __METHOD__ );
+ public function commitAll( $fname = __METHOD__, $owner = null );
/**
* Run pre-commit callbacks and defer execution of post-commit callbacks
*
* Use this only for mutli-database commits
*
+ * @param string $fname Caller name
+ * @param int|null $owner ID of the calling instance (e.g. the LBFactory ID)
* @return int Number of pre-commit callbacks run (since 1.32)
*/
- public function finalizeMasterChanges();
+ public function finalizeMasterChanges( $fname = __METHOD__, $owner = null );
/**
* Perform all pre-commit checks for things like replication safety
*
* @param array $options Includes:
* - maxWriteDuration : max write query duration time in seconds
+ * @param string $fname Caller name
+ * @param int|null $owner ID of the calling instance (e.g. the LBFactory ID)
* @throws DBTransactionError
*/
- public function approveMasterChanges( array $options );
+ public function approveMasterChanges( array $options, $fname, $owner = null );
/**
* Flush any master transaction snapshots and set DBO_TRX (if DBO_DEFAULT is set)
* - commitAll()
* This allows for custom transaction rounds from any outer transaction scope.
*
- * @param string $fname
+ * @param string $fname Caller name
+ * @param int|null $owner ID of the calling instance (e.g. the LBFactory ID)
* @throws DBExpectedError
*/
- public function beginMasterChanges( $fname = __METHOD__ );
+ public function beginMasterChanges( $fname = __METHOD__, $owner = null );
/**
* Issue COMMIT on all open master connections to flush changes and view snapshots
* @param string $fname Caller name
+ * @param int|null $owner ID of the calling instance (e.g. the LBFactory ID)
* @throws DBExpectedError
*/
- public function commitMasterChanges( $fname = __METHOD__ );
+ public function commitMasterChanges( $fname = __METHOD__, $owner = null );
/**
* Consume and run all pending post-COMMIT/ROLLBACK callbacks and commit dangling transactions
*
+ * @param string $fname Caller name
+ * @param int|null $owner ID of the calling instance (e.g. the LBFactory ID)
* @return Exception|null The first exception or null if there were none
*/
- public function runMasterTransactionIdleCallbacks();
+ public function runMasterTransactionIdleCallbacks( $fname = __METHOD__, $owner = null );
/**
* Run all recurring post-COMMIT/ROLLBACK listener callbacks
*
+ * @param string $fname Caller name
+ * @param int|null $owner ID of the calling instance (e.g. the LBFactory ID)
* @return Exception|null The first exception or null if there were none
*/
- public function runMasterTransactionListenerCallbacks();
+ public function runMasterTransactionListenerCallbacks( $fname = __METHOD__, $owner = null );
/**
* Issue ROLLBACK only on master, only if queries were done on connection
* @param string $fname Caller name
+ * @param int|null $owner ID of the calling instance (e.g. the LBFactory ID)
* @throws DBExpectedError
*/
- public function rollbackMasterChanges( $fname = __METHOD__ );
+ public function rollbackMasterChanges( $fname = __METHOD__, $owner = null );
/**
* Commit all replica DB transactions so as to flush any REPEATABLE-READ or SSI snapshots
* the aliases can be removed, and then the old X-named indexes dropped.
*
* @param string[] $aliases
- * @return mixed
* @since 1.31
*/
public function setIndexAliases( array $aliases );
dépôts / lhc / web / wiklou.git / blobdiff