From 5820f735aef6f9a890a4f8c630152ca9c2ad3786 Mon Sep 17 00:00:00 2001 From: Aaron Schulz Date: Tue, 1 Dec 2015 15:15:47 -0800 Subject: [PATCH] Add more BacklinkJobUtils comments Change-Id: Ic1b9f730c3876214dfebf7623a2d4dec5c9c08af --- includes/jobqueue/utils/BacklinkJobUtils.php | 21 ++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/includes/jobqueue/utils/BacklinkJobUtils.php b/includes/jobqueue/utils/BacklinkJobUtils.php index c8e5df66f7..51ccf612fe 100644 --- a/includes/jobqueue/utils/BacklinkJobUtils.php +++ b/includes/jobqueue/utils/BacklinkJobUtils.php @@ -25,6 +25,27 @@ /** * Class with Backlink related Job helper methods * + * When an asset changes, a base job can be inserted to update all assets that depend on it. + * The base job splits into per-title "leaf" jobs and a "remnant" job to handle the remaining + * range of backlinks. This recurs until the remnant job's backlink range is small enough that + * only leaf jobs are created from it. + * + * For example, if templates A and B are edited (at the same time) the queue will have: + * (A base, B base) + * When these jobs run, the queue will have per-title and remnant partition jobs: + * (titleX,titleY,titleZ,...,A remnant,titleM,titleN,titleO,...,B remnant) + * + * This works best when the queue is FIFO, for several reasons: + * - a) Since the remnant jobs are enqueued after the leaf jobs, the slower leaf jobs have to + * get popped prior to the fast remnant jobs. This avoids flooding the queue with leaf jobs + * for every single backlink of widely used assets (which can be millions). + * - b) Other jobs going in the queue still get a chance to run after a widely used asset changes. + * This is due to the large remnant job pushing to the end of the queue with each division. + * + * The size of the queues used in this manner depend on the number of assets changes and the + * number of workers. Also, with FIFO-per-partition queues, the queue size can be somewhat larger, + * depending on the number of queue partitions. + * * @ingroup JobQueue * @since 1.23 */ -- 2.20.1