From af86e56356c4208f29d047037f56f5f6afb662d3 Mon Sep 17 00:00:00 2001 From: Antoine Musso Date: Fri, 18 Mar 2011 18:12:58 +0000 Subject: [PATCH] documentation for BacklinkCache class - still need examples - could use peer review - no functional changes --- includes/BacklinkCache.php | 117 +++++++++++++++++++++++++++++++------ 1 file changed, 99 insertions(+), 18 deletions(-) diff --git a/includes/BacklinkCache.php b/includes/BacklinkCache.php index 02b0f170c5..c568eb20c4 100644 --- a/includes/BacklinkCache.php +++ b/includes/BacklinkCache.php @@ -1,21 +1,77 @@ getBacklinkCache(). + * File for BacklinkCache class + * @file + */ + +/** + * Class for fetching backlink lists, approximate backlink counts and + * partitions. This is a shared cache. + * + * Instances of this class should typically be fetched with the method + * $title->getBacklinkCache(). + * + * Ideally you should only get your backlinks from here when you think + * there is some advantage in caching them. Otherwise it's just a waste + * of memory. * - * Ideally you should only get your backlinks from here when you think there is some - * advantage in caching them. Otherwise it's just a waste of memory. + * Introduced by r47317 + * + * @internal documentation reviewed on 18 Mar 2011 by hashar + * + * @author Tim Starling + * @copyright © 2009, Tim Starling, Domas Mituzas + * @copyright © 2010, Max Sem + * @copyright © 2011, Ashar Voultoiz */ class BacklinkCache { + + /** + * Multi dimensions array representing batches. Keys are: + * > (string) links table name + * > 'numRows' : Number of rows for this link table + * > 'batches' : array( $start, $end ) + * + * @see BacklinkCache::partitionResult() + * @todo Should be private + * + * Cleared with BacklinkCache::clear() + */ var $partitionCache = array(); + + /** + * Contains the whole links from a database result. + * This is raw data that will be partitioned in $partitionCache + * + * @todo Should be private + * + * Initialized with BacklinkCache::getLinks() + * Cleared with BacklinkCache::clear() + */ var $fullResultCache = array(); - var $title; + + /** + * Local copy of a database object. + * + * Accessor: BacklinkCache::getDB() + * Mutator : BacklinkCache::setDB() + * Cleared with BacklinkCache::clear() + * + * @todo Should be private + */ var $db; + /** + * Local copy of a Title object + * @todo Should be private + */ + var $title; + const CACHE_EXPIRY = 3600; /** * Create a new BacklinkCache + * @param Title $title : Title object to create a backlink cache for. */ function __construct( $title ) { $this->title = $title; @@ -23,14 +79,15 @@ class BacklinkCache { /** * Serialization handler, diasallows to serialize the database to prevent - * failures after this class is deserialized from cache with dead DB connection. + * failures after this class is deserialized from cache with dead DB + * connection. */ function __sleep() { return array( 'partitionCache', 'fullResultCache', 'title' ); } /** - * Clear locally stored data + * Clear locally stored data and database object. */ function clear() { $this->partitionCache = array(); @@ -45,6 +102,11 @@ class BacklinkCache { $this->db = $db; } + /** + * Get the slave connection to the database + * When non existing, will initialize the connection. + * @return Database object + */ protected function getDB() { if ( !isset( $this->db ) ) { $this->db = wfGetDB( DB_SLAVE ); @@ -95,6 +157,7 @@ class BacklinkCache { return $ta; } + // FIXME : make this a function? if ( !isset( $this->fullResultCache[$table] ) ) { wfDebug( __METHOD__ . ": from DB\n" ); $res = $this->getDB()->select( @@ -117,14 +180,15 @@ class BacklinkCache { /** * Get the field name prefix for a given table + * @param $table String */ protected function getPrefix( $table ) { static $prefixes = array( - 'pagelinks' => 'pl', - 'imagelinks' => 'il', + 'pagelinks' => 'pl', + 'imagelinks' => 'il', 'categorylinks' => 'cl', 'templatelinks' => 'tl', - 'redirect' => 'rd', + 'redirect' => 'rd', ); if ( isset( $prefixes[$table] ) ) { @@ -135,18 +199,22 @@ class BacklinkCache { } /** - * Get the SQL condition array for selecting backlinks, with a join on the page table + * Get the SQL condition array for selecting backlinks, with a join + * on the page table. + * @param $table String */ protected function getConditions( $table ) { $prefix = $this->getPrefix( $table ); + // FIXME imagelinks and categorylinks do not rely on getNamespace, + // they could be moved up for nicer case statements switch ( $table ) { case 'pagelinks': case 'templatelinks': case 'redirect': $conds = array( "{$prefix}_namespace" => $this->title->getNamespace(), - "{$prefix}_title" => $this->title->getDBkey(), + "{$prefix}_title" => $this->title->getDBkey(), "page_id={$prefix}_from" ); break; @@ -171,6 +239,8 @@ class BacklinkCache { /** * Get the approximate number of backlinks + * @param $table String + * @return integer */ public function getNumLinks( $table ) { if ( isset( $this->fullResultCache[$table] ) ) { @@ -189,15 +259,17 @@ class BacklinkCache { /** * Partition the backlinks into batches. - * Returns an array giving the start and end of each range. The first batch has - * a start of false, and the last batch has an end of false. + * Returns an array giving the start and end of each range. The firsti + * batch has a start of false, and the last batch has an end of false. * * @param $table String: the links table name * @param $batchSize Integer * @return Array */ public function partition( $table, $batchSize ) { - // Try cache + + // 1) try this per process cache first + if ( isset( $this->partitionCache[$table][$batchSize] ) ) { wfDebug( __METHOD__ . ": got from partition cache\n" ); return $this->partitionCache[$table][$batchSize]['batches']; @@ -206,7 +278,9 @@ class BacklinkCache { $this->partitionCache[$table][$batchSize] = false; $cacheEntry =& $this->partitionCache[$table][$batchSize]; - // Try full result cache + + // 2) try full result cache + if ( isset( $this->fullResultCache[$table] ) ) { $cacheEntry = $this->partitionResult( $this->fullResultCache[$table], $batchSize ); wfDebug( __METHOD__ . ": got from full result cache\n" ); @@ -214,7 +288,9 @@ class BacklinkCache { return $cacheEntry['batches']; } - // Try memcached + + // 3) ... fallback to memcached ... + global $wgMemc; $memcKey = wfMemcKey( @@ -233,7 +309,9 @@ class BacklinkCache { return $cacheEntry['batches']; } - // Fetch from database + + // 4) ... finally fetch from the slow database :( + $this->getLinks( $table ); $cacheEntry = $this->partitionResult( $this->fullResultCache[$table], $batchSize ); // Save to memcached @@ -245,6 +323,9 @@ class BacklinkCache { /** * Partition a DB result with backlinks in it into batches + * @param $res database result + * @param $batchSize integer + * @return array @see */ protected function partitionResult( $res, $batchSize ) { $batches = array(); -- 2.20.1