Siebrand has uploaded a new change for review.
https://gerrit.wikimedia.org/r/96542
Change subject: Update documentation and formatting for includes/deferred/
......................................................................
Update documentation and formatting for includes/deferred/
Change-Id: I56f35be6e549aec13c4fbad5ee6301aa29358031
---
M includes/deferred/CallableUpdate.php
M includes/deferred/DeferredUpdates.php
M includes/deferred/HTMLCacheUpdate.php
M includes/deferred/LinksUpdate.php
M includes/deferred/SearchUpdate.php
M includes/deferred/SiteStatsUpdate.php
M includes/deferred/SqlDataUpdate.php
M includes/deferred/SquidUpdate.php
M includes/deferred/ViewCountUpdate.php
9 files changed, 145 insertions(+), 99 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/core
refs/changes/42/96542/1
diff --git a/includes/deferred/CallableUpdate.php
b/includes/deferred/CallableUpdate.php
index c52bb7d..f0569dd 100644
--- a/includes/deferred/CallableUpdate.php
+++ b/includes/deferred/CallableUpdate.php
@@ -5,12 +5,13 @@
*/
class MWCallableUpdate implements DeferrableUpdate {
/**
- * @var closure/callabck
+ * @var closure/callback
*/
private $callback;
/**
* @param callable $callback
+ * @throws MWException
*/
public function __construct( $callback ) {
if ( !is_callable( $callback ) ) {
diff --git a/includes/deferred/DeferredUpdates.php
b/includes/deferred/DeferredUpdates.php
index 053b7f6..5cf0d2b 100644
--- a/includes/deferred/DeferredUpdates.php
+++ b/includes/deferred/DeferredUpdates.php
@@ -46,7 +46,7 @@
/**
* Add an update to the deferred list
- * @param $update DeferrableUpdate Some object that implements
doUpdate()
+ * @param DeferrableUpdate $update Some object that implements
doUpdate()
*/
public static function addUpdate( DeferrableUpdate $update ) {
array_push( self::$updates, $update );
@@ -56,8 +56,8 @@
* HTMLCacheUpdates are the most common deferred update people use. This
* is a shortcut method for that.
* @see HTMLCacheUpdate::__construct()
- * @param $title
- * @param $table
+ * @param Title $title
+ * @param string $table
*/
public static function addHTMLCacheUpdate( $title, $table ) {
self::addUpdate( new HTMLCacheUpdate( $title, $table ) );
@@ -77,7 +77,7 @@
* Do any deferred updates and clear the list
*
* @param string $commit set to 'commit' to commit after every update to
- * prevent lock contention
+ * prevent lock contention
*/
public static function doUpdates( $commit = '' ) {
global $wgDeferredUpdateList;
@@ -93,11 +93,13 @@
return;
}
+ $dbw = false;
$doCommit = $commit == 'commit';
if ( $doCommit ) {
$dbw = wfGetDB( DB_MASTER );
}
+ /** @var DeferrableUpdate $update */
foreach ( $updates as $update ) {
try {
$update->doUpdate();
diff --git a/includes/deferred/HTMLCacheUpdate.php
b/includes/deferred/HTMLCacheUpdate.php
index 8c91347..0713a05 100644
--- a/includes/deferred/HTMLCacheUpdate.php
+++ b/includes/deferred/HTMLCacheUpdate.php
@@ -27,16 +27,15 @@
* @ingroup Cache
*/
class HTMLCacheUpdate implements DeferrableUpdate {
- /**
- * @var Title
- */
+ /** @var Title */
public $mTitle;
+ /** @var string */
public $mTable;
/**
- * @param $titleTo
- * @param $table
+ * @param Title $titleTo
+ * @param string $table
*/
function __construct( Title $titleTo, $table ) {
$this->mTitle = $titleTo;
diff --git a/includes/deferred/LinksUpdate.php
b/includes/deferred/LinksUpdate.php
index 00d26ee..a3f180c 100644
--- a/includes/deferred/LinksUpdate.php
+++ b/includes/deferred/LinksUpdate.php
@@ -28,19 +28,44 @@
class LinksUpdate extends SqlDataUpdate {
// @todo make members protected, but make sure extensions don't break
- public $mId, //!< Page ID of the article linked from
- $mTitle, //!< Title object of the article linked from
- $mParserOutput, //!< Parser output
- $mLinks, //!< Map of title strings to IDs for the links in the
document
- $mImages, //!< DB keys of the images used, in the array key only
- $mTemplates, //!< Map of title strings to IDs for the template
references, including broken ones
- $mExternals, //!< URLs of external links, array key only
- $mCategories, //!< Map of category names to sort keys
- $mInterlangs, //!< Map of language codes to titles
- $mProperties, //!< Map of arbitrary name to value
- $mDb, //!< Database connection reference
- $mOptions, //!< SELECT options to be used (array)
- $mRecursive; //!< Whether to queue jobs for recursive updates
+ /** @var int Page ID of the article linked from */
+ public $mId;
+
+ /** @var Title object of the article linked from */
+ public $mTitle;
+
+ /** @var ParserOutput */
+ public $mParserOutput;
+
+ /** @var array Map of title strings to IDs for the links in the
document */
+ public $mLinks;
+
+ /** @var array DB keys of the images used, in the array key only */
+ public $mImages;
+
+ /** @var array Map of title strings to IDs for the template references,
including broken ones */
+ public $mTemplates;
+
+ /** @var array URLs of external links, array key only */
+ public $mExternals;
+
+ /** @var array Map of category names to sort keys */
+ public $mCategories;
+
+ /** @var array ap of language codes to titles */
+ public $mInterlangs;
+
+ /** @var array Map of arbitrary name to value */
+ public $mProperties;
+
+ /** @var DatabaseBase Database connection reference */
+ public $mDb;
+
+ /** @var array SELECT options to be used */
+ public $mOptions;
+
+ /** @var bool Whether to queue jobs for recursive updates */
+ public $mRecursive;
/**
* @var null|array Added links if calculated.
@@ -55,9 +80,9 @@
/**
* Constructor
*
- * @param $title Title of the page we're updating
- * @param $parserOutput ParserOutput: output from a full parse of this
page
- * @param $recursive Boolean: queue jobs for recursive updates?
+ * @param Title $title Title of the page we're updating
+ * @param ParserOutput $parserOutput Output from a full parse of this
page
+ * @param bool $recursive Queue jobs for recursive updates?
* @throws MWException
*/
function __construct( $title, $parserOutput, $recursive = true ) {
@@ -77,7 +102,8 @@
$this->mId = $title->getArticleID();
if ( !$this->mId ) {
- throw new MWException( "The Title object did not
provide an article ID. Perhaps the page doesn't exist?" );
+ throw new MWException( "The Title object did not
provide an article " .
+ "ID. Perhaps the page doesn't exist?" );
}
$this->mParserOutput = $parserOutput;
@@ -215,7 +241,7 @@
* Queue a RefreshLinks job for any table.
*
* @param Title $title Title to do job for
- * @param String $table Table to use (e.g. 'templatelinks')
+ * @param string $table Table to use (e.g. 'templatelinks')
*/
public static function queueRecursiveJobsForTable( Title $title, $table
) {
wfProfileIn( __METHOD__ );
@@ -243,8 +269,8 @@
/**
* Update all the appropriate counts in the category table.
- * @param array $added associative array of category name => sort key
- * @param array $deleted associative array of category name => sort key
+ * @param array $added Associative array of category name => sort key
+ * @param array $deleted Associative array of category name => sort key
*/
function updateCategoryCounts( $added, $deleted ) {
$a = WikiPage::factory( $this->mTitle );
@@ -262,10 +288,10 @@
/**
* Update a table by doing a delete query then an insert query
- * @param $table
- * @param $prefix
- * @param $deletions
- * @param $insertions
+ * @param string $table Table name
+ * @param string $prefix Field name prefix
+ * @param array $deletions
+ * @param array $insertions Rows to insert
*/
function incrTableUpdate( $table, $prefix, $deletions, $insertions ) {
if ( $table == 'page_props' ) {
@@ -312,7 +338,7 @@
/**
* Get an array of pagelinks insertions for passing to the DB
* Skips the titles specified by the 2-D array $existing
- * @param $existing array
+ * @param array $existing
* @return array
*/
private function getLinkInsertions( $existing = array() ) {
@@ -335,7 +361,7 @@
/**
* Get an array of template insertions. Like getLinkInsertions()
- * @param $existing array
+ * @param array $existing
* @return array
*/
private function getTemplateInsertions( $existing = array() ) {
@@ -357,7 +383,7 @@
/**
* Get an array of image insertions
* Skips the names specified in $existing
- * @param $existing array
+ * @param array $existing
* @return array
*/
private function getImageInsertions( $existing = array() ) {
@@ -375,7 +401,7 @@
/**
* Get an array of externallinks insertions. Skips the names specified
in $existing
- * @param $existing array
+ * @param array $existing
* @return array
*/
private function getExternalInsertions( $existing = array() ) {
@@ -462,7 +488,7 @@
/**
* Get an array of page property insertions
- * @param $existing array
+ * @param array $existing
* @return array
*/
function getPropertyInsertions( $existing = array() ) {
@@ -482,13 +508,16 @@
/**
* Get an array of interwiki insertions for passing to the DB
* Skips the titles specified by the 2-D array $existing
- * @param $existing array
+ * @param array $existing
* @return array
*/
private function getInterwikiInsertions( $existing = array() ) {
$arr = array();
foreach ( $this->mInterwikis as $prefix => $dbkeys ) {
- $diffs = isset( $existing[$prefix] ) ? array_diff_key(
$dbkeys, $existing[$prefix] ) : $dbkeys;
+ $diffs = isset( $existing[$prefix] )
+ ? array_diff_key( $dbkeys, $existing[$prefix] )
+ : $dbkeys;
+
foreach ( $diffs as $dbk => $id ) {
$arr[] = array(
'iwl_from' => $this->mId,
@@ -504,7 +533,7 @@
/**
* Given an array of existing links, returns those links which are not
in $this
* and thus should be deleted.
- * @param $existing array
+ * @param array $existing
* @return array
*/
private function getLinkDeletions( $existing ) {
@@ -523,7 +552,7 @@
/**
* Given an array of existing templates, returns those templates which
are not in $this
* and thus should be deleted.
- * @param $existing array
+ * @param array $existing
* @return array
*/
private function getTemplateDeletions( $existing ) {
@@ -542,7 +571,7 @@
/**
* Given an array of existing images, returns those images which are
not in $this
* and thus should be deleted.
- * @param $existing array
+ * @param array $existing
* @return array
*/
private function getImageDeletions( $existing ) {
@@ -552,7 +581,7 @@
/**
* Given an array of existing external links, returns those links which
are not
* in $this and thus should be deleted.
- * @param $existing array
+ * @param array $existing
* @return array
*/
private function getExternalDeletions( $existing ) {
@@ -562,7 +591,7 @@
/**
* Given an array of existing categories, returns those categories
which are not in $this
* and thus should be deleted.
- * @param $existing array
+ * @param array $existing
* @return array
*/
private function getCategoryDeletions( $existing ) {
@@ -572,7 +601,7 @@
/**
* Given an array of existing interlanguage links, returns those links
which are not
* in $this and thus should be deleted.
- * @param $existing array
+ * @param array $existing
* @return array
*/
private function getInterlangDeletions( $existing ) {
@@ -581,7 +610,7 @@
/**
* Get array of properties which should be deleted.
- * @param $existing array
+ * @param array $existing
* @return array
*/
function getPropertyDeletions( $existing ) {
@@ -591,7 +620,7 @@
/**
* Given an array of existing interwiki links, returns those links
which are not in $this
* and thus should be deleted.
- * @param $existing array
+ * @param array $existing
* @return array
*/
private function getInterwikiDeletions( $existing ) {
@@ -731,7 +760,7 @@
/**
* Get an array of existing categories, with the name in the key and
sort key in the value.
*
- * @return array
+ * @return array of property names and values
*/
private function getExistingProperties() {
$res = $this->mDb->select( 'page_props', array( 'pp_propname',
'pp_value' ),
@@ -771,7 +800,7 @@
/**
* Invalidate any necessary link lists related to page property changes
- * @param $changed
+ * @param array $changed
*/
private function invalidateProperties( $changed ) {
global $wgPagePropLinkInvalidations;
@@ -831,12 +860,13 @@
* Update object handling the cleanup of links tables after a page was deleted.
**/
class LinksDeletionUpdate extends SqlDataUpdate {
- protected $mPage; //!< WikiPage the wikipage that was deleted
+ /** @var WikiPage The WikiPage that was deleted */
+ protected $mPage;
/**
* Constructor
*
- * @param $page WikiPage Page we are updating
+ * @param WikiPage $page Page we are updating
* @throws MWException
*/
function __construct( WikiPage $page ) {
@@ -899,8 +929,8 @@
/**
* Update all the appropriate counts in the category table.
- * @param array $added associative array of category name => sort key
- * @param array $deleted associative array of category name => sort key
+ * @param array $added Associative array of category name => sort key
+ * @param array $deleted Associative array of category name => sort key
*/
function updateCategoryCounts( $added, $deleted ) {
$a = WikiPage::factory( $this->mTitle );
diff --git a/includes/deferred/SearchUpdate.php
b/includes/deferred/SearchUpdate.php
index 85cc5e7..7ca4158 100644
--- a/includes/deferred/SearchUpdate.php
+++ b/includes/deferred/SearchUpdate.php
@@ -29,22 +29,13 @@
* @ingroup Search
*/
class SearchUpdate implements DeferrableUpdate {
- /**
- * Page id being updated
- * @var int
- */
+ /** @var int Page id being updated */
private $id = 0;
- /**
- * Title we're updating
- * @var Title
- */
+ /** @var Title Title we're updating */
private $title;
- /**
- * Content of the page (not text)
- * @var Content|false
- */
+ /** @var Content|false Content of the page (not text) */
private $content;
/**
@@ -52,7 +43,7 @@
*
* @param int $id Page id to update
* @param Title|string $title Title of page to update
- * @param Content|string|false $c Content of the page to update.
+ * @param Content|string|bool $c Content of the page to update.
Default: false.
* If a Content object, text will be gotten from it. String is for
back-compat.
* Passing false tells the backend to just update the title, not the
content
*/
diff --git a/includes/deferred/SiteStatsUpdate.php
b/includes/deferred/SiteStatsUpdate.php
index 10511ee..7bfafee 100644
--- a/includes/deferred/SiteStatsUpdate.php
+++ b/includes/deferred/SiteStatsUpdate.php
@@ -22,11 +22,22 @@
* Class for handling updates to the site_stats table
*/
class SiteStatsUpdate implements DeferrableUpdate {
+ /** @var int */
protected $views = 0;
+
+ /** @var int */
protected $edits = 0;
+
+ /** @var int */
protected $pages = 0;
+
+ /** @var int */
protected $articles = 0;
+
+ /** @var int */
protected $users = 0;
+
+ /** @var int */
protected $images = 0;
// @todo deprecate this constructor
@@ -39,7 +50,7 @@
}
/**
- * @param $deltas Array
+ * @param array $deltas
* @return SiteStatsUpdate
*/
public static function factory( array $deltas ) {
@@ -71,14 +82,13 @@
/**
* Do not call this outside of SiteStatsUpdate
- *
- * @return void
*/
public function tryDBUpdateInternal() {
global $wgSiteStatsAsyncFactor;
$dbw = wfGetDB( DB_MASTER );
$lockKey = wfMemcKey( 'site_stats' ); // prepend wiki ID
+ $pd = array();
if ( $wgSiteStatsAsyncFactor ) {
// Lock the table so we don't have double DB/memcached
updates
if ( !$dbw->lockIsFree( $lockKey, __METHOD__ )
@@ -119,7 +129,7 @@
}
/**
- * @param $dbw DatabaseBase
+ * @param DatabaseBase $dbw
* @return bool|mixed
*/
public static function cacheUpdate( $dbw ) {
@@ -134,7 +144,8 @@
'rc_user != 0',
'rc_bot' => 0,
'rc_log_type != ' . $dbr->addQuotes( 'newusers'
) . ' OR rc_log_type IS NULL',
- 'rc_timestamp >= ' . $dbr->addQuotes(
$dbr->timestamp( wfTimestamp( TS_UNIX ) - $wgActiveUserDays * 24 * 3600 ) ),
+ 'rc_timestamp >= ' . $dbr->addQuotes(
$dbr->timestamp( wfTimestamp( TS_UNIX )
+ - $wgActiveUserDays * 24 * 3600 ) ),
),
__METHOD__
);
@@ -158,9 +169,9 @@
}
/**
- * @param $sql string
- * @param $field string
- * @param $delta integer
+ * @param string $sql
+ * @param string $field
+ * @param int $delta
*/
protected function appendUpdate( &$sql, $field, $delta ) {
if ( $delta ) {
@@ -176,7 +187,7 @@
}
/**
- * @param $type string
+ * @param string $type
* @param string $sign ('+' or '-')
* @return string
*/
@@ -187,9 +198,8 @@
/**
* Adjust the pending deltas for a stat type.
* Each stat type has two pending counters, one for increments and
decrements
- * @param $type string
- * @param $delta integer Delta (positive or negative)
- * @return void
+ * @param string $type
+ * @param int $delta Delta (positive or negative)
*/
protected function adjustPending( $type, $delta ) {
global $wgMemc;
@@ -210,8 +220,7 @@
/**
* Get pending delta counters for each stat type
- * @return Array Positive and negative deltas for each type
- * @return void
+ * @return array Positive and negative deltas for each type
*/
protected function getPendingDeltas() {
global $wgMemc;
@@ -231,7 +240,6 @@
/**
* Reduce pending delta counters after updates have been applied
* @param array $pd Result of getPendingDeltas(), used for DB update
- * @return void
*/
protected function removePendingDeltas( array $pd ) {
global $wgMemc;
diff --git a/includes/deferred/SqlDataUpdate.php
b/includes/deferred/SqlDataUpdate.php
index c98c1fd..09d18c4 100644
--- a/includes/deferred/SqlDataUpdate.php
+++ b/includes/deferred/SqlDataUpdate.php
@@ -31,19 +31,25 @@
* the beginTransaction() and commitTransaction() methods.
*/
abstract class SqlDataUpdate extends DataUpdate {
- protected $mDb; //!< Database connection reference
- protected $mOptions; //!< SELECT options to be used (array)
+ /** @var DatabaseBase Database connection reference */
+ protected $mDb;
- private $mHasTransaction; //!< bool whether a transaction is open on
this object (internal use only!)
- protected $mUseTransaction; //!< bool whether this update should be
wrapped in a transaction
+ /** @var array SELECT options to be used (array) */
+ protected $mOptions;
+
+ /** @var bool Whether a transaction is open on this object (internal
use only!) */
+ private $mHasTransaction;
+
+ /** @var bool Whether this update should be wrapped in a transaction */
+ protected $mUseTransaction;
/**
* Constructor
*
- * @param bool $withTransaction whether this update should be wrapped
in a transaction (default: true).
- * A transaction is only started if no transaction is
already in progress,
- * see beginTransaction() for details.
- **/
+ * @param bool $withTransaction whether this update should be wrapped
in a
+ * transaction (default: true). A transaction is only started if no
+ * transaction is already in progress, see beginTransaction() for
details.
+ */
public function __construct( $withTransaction = true ) {
global $wgAntiLockFlags;
@@ -55,7 +61,8 @@
$this->mOptions = array( 'FOR UPDATE' );
}
- // @todo get connection only when it's needed? make sure that
doesn't break anything, especially transactions!
+ // @todo Get connection only when it's needed? Make sure that
doesn't
+ // break anything, especially transactions!
$this->mDb = wfGetDB( DB_MASTER );
$this->mWithTransaction = $withTransaction;
@@ -63,10 +70,12 @@
}
/**
- * Begin a database transaction, if $withTransaction was given as true
in the constructor for this SqlDataUpdate.
+ * Begin a database transaction, if $withTransaction was given as true
in
+ * the constructor for this SqlDataUpdate.
*
- * Because nested transactions are not supported by the Database class,
this implementation
- * checks Database::trxLevel() and only opens a transaction if none is
already active.
+ * Because nested transactions are not supported by the Database class,
+ * this implementation checks Database::trxLevel() and only opens a
+ * transaction if none is already active.
*/
public function beginTransaction() {
if ( !$this->mWithTransaction ) {
@@ -104,8 +113,8 @@
* Invalidate the cache of a list of pages from a single namespace.
* This is intended for use by subclasses.
*
- * @param $namespace Integer
- * @param $dbkeys Array
+ * @param int $namespace Namespace number
+ * @param array $dbkeys
*/
protected function invalidatePages( $namespace, array $dbkeys ) {
if ( $dbkeys === array() ) {
diff --git a/includes/deferred/SquidUpdate.php
b/includes/deferred/SquidUpdate.php
index 59347d6..bac9f10 100644
--- a/includes/deferred/SquidUpdate.php
+++ b/includes/deferred/SquidUpdate.php
@@ -96,6 +96,7 @@
public static function newFromTitles( $titles, $urlArr = array() ) {
global $wgMaxSquidPurgeTitles;
$i = 0;
+ /** @var Title $title */
foreach ( $titles as $title ) {
$urlArr[] = $title->getInternalURL();
if ( $i++ > $wgMaxSquidPurgeTitles ) {
diff --git a/includes/deferred/ViewCountUpdate.php
b/includes/deferred/ViewCountUpdate.php
index 6863918..ddd2e09 100644
--- a/includes/deferred/ViewCountUpdate.php
+++ b/includes/deferred/ViewCountUpdate.php
@@ -28,12 +28,13 @@
* from that table to update the 'page_counter' field in a batch operation.
*/
class ViewCountUpdate implements DeferrableUpdate {
+ /** @var int Page ID to increment the view count */
protected $id;
/**
* Constructor
*
- * @param $id Integer: page ID to increment the view count
+ * @param int $id Page ID to increment the view count
*/
public function __construct( $id ) {
$this->id = intval( $id );
@@ -48,7 +49,11 @@
$dbw = wfGetDB( DB_MASTER );
if ( $wgHitcounterUpdateFreq <= 1 || $dbw->getType() ==
'sqlite' ) {
- $dbw->update( 'page', array( 'page_counter =
page_counter + 1' ), array( 'page_id' => $this->id ), __METHOD__ );
+ $dbw->update(
+ 'page', array( 'page_counter = page_counter +
1' ),
+ array( 'page_id' => $this->id ),
+ __METHOD__
+ );
return;
}
--
To view, visit https://gerrit.wikimedia.org/r/96542
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I56f35be6e549aec13c4fbad5ee6301aa29358031
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/core
Gerrit-Branch: master
Gerrit-Owner: Siebrand <[email protected]>
_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
