class UIDGenerator {
/** @var UIDGenerator */
protected static $instance = null;
-
- protected $nodeIdFile; // string; local file path
- protected $nodeId32; // string; node ID in binary (32 bits)
- protected $nodeId48; // string; node ID in binary (48 bits)
-
- protected $lockFile88; // string; local file path
- protected $lockFile128; // string; local file path
- protected $lockFileUUID; // string; local file path
-
- /** @var array */
- protected $fileHandles = []; // cache file handles
+ /** @var string Local file path */
+ protected $nodeIdFile;
+ /** @var string Node ID in binary (32 bits) */
+ protected $nodeId32;
+ /** @var string Node ID in binary (48 bits) */
+ protected $nodeId48;
+
+ /** @var string Local file path */
+ protected $lockFile88;
+ /** @var string Local file path */
+ protected $lockFile128;
+ /** @var string Local file path */
+ protected $lockFileUUID;
+
+ /** @var array Cached file handles */
+ protected $fileHandles = []; // cached file handles
const QUICK_RAND = 1; // get randomness from fast and insecure sources
const QUICK_VOLATILE = 2; // use an APC like in-memory counter if available
}
/**
- * @todo: move to MW-specific factory class and inject temp dir
+ * @todo move to MW-specific factory class and inject temp dir
* @return UIDGenerator
*/
protected static function singleton() {
}
/**
- * @param array $info The result of UIDGenerator::getTimeAndDelay() or
- * a plain (UIDGenerator::millitime(), counter, clock sequence) array.
+ * @param array $info result of UIDGenerator::getTimeAndDelay(), or
+ * for sub classes, a seqencial array like (time, offsetCounter).
* @return string 88 bits
* @throws RuntimeException
*/
}
/**
- * @param array $info The result of UIDGenerator::getTimeAndDelay() or
- * a plain (UIDGenerator::millitime(), counter, clock sequence) array.
+ * @param array $info The result of UIDGenerator::getTimeAndDelay(),
+ * for sub classes, a seqencial array like (time, offsetCounter, clkSeq).
* @return string 128 bits
* @throws RuntimeException
*/
protected function getSequentialPerNodeIDs( $bucket, $bits, $count, $flags ) {
if ( $count <= 0 ) {
return []; // nothing to do
- } elseif ( $bits < 16 || $bits > 48 ) {
+ }
+ if ( $bits < 16 || $bits > 48 ) {
throw new RuntimeException( "Requested bit size ($bits) is out of range." );
}
$counter = null; // post-increment persistent counter value
// Use APC/etc if requested, available, and not in CLI mode;
- // Counter values would not survive accross script instances in CLI mode.
+ // Counter values would not survive across script instances in CLI mode.
$cache = null;
if ( ( $flags & self::QUICK_VOLATILE ) && !wfIsCLI() ) {
$cache = MediaWikiServices::getInstance()->getLocalServerObjectCache();
// Acquire the UID lock file
if ( $handle === false ) {
throw new RuntimeException( "Could not open '{$path}'." );
- } elseif ( !flock( $handle, LOCK_EX ) ) {
+ }
+ if ( !flock( $handle, LOCK_EX ) ) {
fclose( $handle );
throw new RuntimeException( "Could not acquire '{$path}'." );
}
* @param int $clockSeqSize The number of possible clock sequence values
* @param int $counterSize The number of possible counter values
* @param int $offsetSize The number of possible offset values
- * @return array (result of UIDGenerator::millitime(), counter, clock sequence)
+ * @return array Array with the following keys:
+ * - array 'time': array of seconds int and milliseconds int.
+ * - int 'counter'.
+ * - int 'clkSeq'.
+ * - int 'offset': .
+ * - int 'offsetCounter'.
* @throws RuntimeException
*/
protected function getTimeAndDelay( $lockFile, $clockSeqSize, $counterSize, $offsetSize ) {
// Acquire the UID lock file
if ( $handle === false ) {
throw new RuntimeException( "Could not open '{$this->$lockFile}'." );
- } elseif ( !flock( $handle, LOCK_EX ) ) {
+ }
+ if ( !flock( $handle, LOCK_EX ) ) {
fclose( $handle );
throw new RuntimeException( "Could not acquire '{$this->$lockFile}'." );
}
- // Get the current timestamp, clock sequence number, last time, and counter
+
+ // The formatters that use this method expect a timestamp with millisecond
+ // precision and a counter upto a certain size. When more IDs than the counter
+ // size are generated during the same timestamp, an exception is thrown as we
+ // cannot increment further, because the formatted ID would not have enough
+ // bits to fit the counter.
+ //
+ // To orchestrate this between independant PHP processes on the same hosts,
+ // we must have a common sense of time so that we only have to maintain
+ // a single counter in a single lock file.
+
rewind( $handle );
- $data = explode( ' ', fgets( $handle ) ); // "<clk seq> <sec> <msec> <counter> <offset>"
- $clockChanged = false; // clock set back significantly?
- if ( count( $data ) == 5 ) { // last UID info already initialized
+ // Format of lock file contents:
+ // "<clk seq> <sec> <msec> <counter> <rand offset>"
+ $data = explode( ' ', fgets( $handle ) );
+
+ // Did the clock get moved back significantly?
+ $clockChanged = false;
+
+ if ( count( $data ) === 5 ) {
+ // The UID lock file was already initialized
$clkSeq = (int)$data[0] % $clockSeqSize;
$prevTime = [ (int)$data[1], (int)$data[2] ];
- $offset = (int)$data[4] % $counterSize; // random counter offset
- $counter = 0; // counter for UIDs with the same timestamp
- // Delay until the clock reaches the time of the last ID.
- // This detects any microtime() drift among processes.
+ // Counter for UIDs with the same timestamp,
+ $counter = 0;
+ $randOffset = (int)$data[4] % $counterSize;
+
+ // If the system clock moved backwards by an NTP sync,
+ // or if the last writer process had its clock drift ahead,
+ // Try to catch up if the gap is small, so that we can keep a single
+ // monotonic logic file.
$time = $this->timeWaitUntil( $prevTime );
- if ( !$time ) { // too long to delay?
- $clockChanged = true; // bump clock sequence number
- $time = self::millitime();
- } elseif ( $time == $prevTime ) {
- // Bump the counter if there are timestamp collisions
+ if ( $time === false ) {
+ // Timed out. Treat it as a new clock
+ $clockChanged = true;
+ $time = $this->millitime();
+ } elseif ( $time === $prevTime ) {
+ // Sanity check, only keep remainder if a previous writer wrote
+ // something here that we don't accept.
$counter = (int)$data[3] % $counterSize;
- if ( ++$counter >= $counterSize ) { // sanity (starts at 0)
- flock( $handle, LOCK_UN ); // abort
+ // Bump the counter if the time has not changed yet
+ if ( ++$counter >= $counterSize ) {
+ // More IDs generated with the same time than counterSize can accomodate
+ flock( $handle, LOCK_UN );
throw new RuntimeException( "Counter overflow for timestamp value." );
}
}
- } else { // last UID info not initialized
+ } else {
+ // Initialize UID lock file information
$clkSeq = mt_rand( 0, $clockSeqSize - 1 );
+ $time = $this->millitime();
$counter = 0;
- $offset = mt_rand( 0, $offsetSize - 1 );
- $time = self::millitime();
+ $randOffset = mt_rand( 0, $offsetSize - 1 );
}
// microtime() and gettimeofday() can drift from time() at least on Windows.
// The drift is immediate for processes running while the system clock changes.
// time() does not have this problem. See https://bugs.php.net/bug.php?id=42659.
- if ( abs( time() - $time[0] ) >= 2 ) {
+ $drift = time() - $time[0];
+ if ( abs( $drift ) >= 2 ) {
// We don't want processes using too high or low timestamps to avoid duplicate
// UIDs and clock sequence number churn. This process should just be restarted.
flock( $handle, LOCK_UN ); // abort
- throw new RuntimeException( "Process clock is outdated or drifted." );
+ throw new RuntimeException( "Process clock is outdated or drifted ({$drift}s)." );
}
// If microtime() is synced and a clock change was detected, then the clock went back
if ( $clockChanged ) {
- // Bump the clock sequence number and also randomize the counter offset,
+ // Bump the clock sequence number and also randomize the extra offset,
// which is useful for UIDs that do not include the clock sequence number.
$clkSeq = ( $clkSeq + 1 ) % $clockSeqSize;
- $offset = mt_rand( 0, $offsetSize - 1 );
+ $randOffset = mt_rand( 0, $offsetSize - 1 );
trigger_error( "Clock was set back; sequence number incremented." );
}
- // Update the (clock sequence number, timestamp, counter)
+
+ // Update and release the UID lock file
ftruncate( $handle, 0 );
rewind( $handle );
- fwrite( $handle, "{$clkSeq} {$time[0]} {$time[1]} {$counter} {$offset}" );
+ fwrite( $handle, "{$clkSeq} {$time[0]} {$time[1]} {$counter} {$randOffset}" );
fflush( $handle );
- // Release the UID lock file
flock( $handle, LOCK_UN );
return [
'time' => $time,
'counter' => $counter,
'clkSeq' => $clkSeq,
- 'offset' => $offset,
- 'offsetCounter' => $counter + $offset
+ 'offset' => $randOffset,
+ 'offsetCounter' => $counter + $randOffset,
];
}
*/
protected function timeWaitUntil( array $time ) {
do {
- $ct = self::millitime();
+ $ct = $this->millitime();
if ( $ct >= $time ) { // https://secure.php.net/manual/en/language.operators.comparison.php
return $ct; // current timestamp is higher than $time
}
/**
* @return array (current time in seconds, milliseconds since then)
*/
- protected static function millitime() {
+ protected function millitime() {
list( $msec, $sec ) = explode( ' ', microtime() );
return [ (int)$sec, (int)( $msec * 1000 ) ];
*
* @see unitTestTearDown
* @since 1.23
+ * @codeCoverageIgnore
*/
- protected function deleteCacheFiles() {
- // Bug: 44850
+ private function deleteCacheFiles() {
+ // T46850
foreach ( $this->fileHandles as $path => $handle ) {
if ( $handle !== null ) {
fclose( $handle );
* environment it should be used with caution as it may destroy state saved
* in the files.
*
+ * @internal For use by unit tests
* @see deleteCacheFiles
* @since 1.23
+ * @codeCoverageIgnore
*/
public static function unitTestTearDown() {
- // Bug: 44850
+ // T46850
$gen = self::singleton();
$gen->deleteCacheFiles();
}
dépôts / lhc / web / wiklou.git / blobdiff