MediaWiki  1.28.0
UIDGenerator Class Reference

Class for getting statistically unique IDs. More...

Collaboration diagram for UIDGenerator:

Public Member Functions

 __destruct ()
 

Static Public Member Functions

static newRawUUIDv1 ()
 Return an RFC4122 compliant v1 UUID. More...
 
static newRawUUIDv4 ($flags=0)
 Return an RFC4122 compliant v4 UUID. More...
 
static newSequentialPerNodeID ($bucket, $bits=48, $flags=0)
 Return an ID that is sequential only for this node and bucket. More...
 
static newSequentialPerNodeIDs ($bucket, $bits, $count, $flags=0)
 Return IDs that are sequential only for this node and bucket. More...
 
static newTimestampedUID128 ($base=10)
 Get a statistically unique 128-bit unsigned integer ID string. More...
 
static newTimestampedUID88 ($base=10)
 Get a statistically unique 88-bit unsigned integer ID string. More...
 
static newUUIDv1 ()
 Return an RFC4122 compliant v1 UUID. More...
 
static newUUIDv4 ($flags=0)
 Return an RFC4122 compliant v4 UUID. More...
 
static unitTestTearDown ()
 Cleanup resources when tearing down after a unit test. More...
 

Public Attributes

const QUICK_RAND = 1
 
const QUICK_VOLATILE = 2
 

Protected Member Functions

 __construct ()
 
 deleteCacheFiles ()
 Delete all cache files that have been created. More...
 
 getSequentialPerNodeIDs ($bucket, $bits, $count, $flags)
 Return IDs that are sequential only for this node and bucket. More...
 
 getTimeAndDelay ($lockFile, $clockSeqSize, $counterSize, $offsetSize)
 Get a (time,counter,clock sequence) where (time,counter) is higher than any previous (time,counter) value for the given clock sequence. More...
 
 getTimestampedID128 (array $info)
 
 getTimestampedID88 (array $info)
 
 getUUIDv1 (array $info)
 
 intervalsSinceGregorianBinary (array $time, $delta=0)
 
 millisecondsSinceEpochBinary (array $time)
 
 timeWaitUntil (array $time)
 Wait till the current timestamp reaches $time and return the current timestamp. More...
 

Static Protected Member Functions

static millitime ()
 
static singleton ()
 

Protected Attributes

array $fileHandles = []
 
 $lockFile128
 
 $lockFile88
 
 $lockFileUUID
 
 $nodeId32
 
 $nodeId48
 
 $nodeIdFile
 

Static Protected Attributes

static UIDGenerator $instance = null
 

Detailed Description

Class for getting statistically unique IDs.

Since
1.21

Definition at line 31 of file UIDGenerator.php.

Constructor & Destructor Documentation

UIDGenerator::__construct ( )
protected
UIDGenerator::__destruct ( )

Definition at line 627 of file UIDGenerator.php.

Member Function Documentation

UIDGenerator::deleteCacheFiles ( )
protected

Delete all cache files that have been created.

This is a cleanup method primarily meant to be used from unit tests to avoid poluting the local filesystem. If used outside of a unit test environment it should be used with caution as it may destroy state saved in the files.

See also
unitTestTearDown
Since
1.23

Definition at line 594 of file UIDGenerator.php.

References $path, and as.

UIDGenerator::getSequentialPerNodeIDs (   $bucket,
  $bits,
  $count,
  $flags 
)
protected

Return IDs that are sequential only for this node and bucket.

See also
UIDGenerator::newSequentialPerNodeID()
Parameters
string$bucketArbitrary bucket name (should be ASCII)
int$bitsBit size (16 to 48) of resulting numbers before wrap-around
int$countNumber of IDs to return
int$flags(supports UIDGenerator::QUICK_VOLATILE)
Returns
array Ordered list of float integer values
Exceptions
RuntimeException

Definition at line 359 of file UIDGenerator.php.

References $cache, $count, $flags, $path, and wfTempDir().

UIDGenerator::getTimeAndDelay (   $lockFile,
  $clockSeqSize,
  $counterSize,
  $offsetSize 
)
protected

Get a (time,counter,clock sequence) where (time,counter) is higher than any previous (time,counter) value for the given clock sequence.

This is useful for making UIDs sequential on a per-node bases.

Parameters
string$lockFileName of a local lock file
int$clockSeqSizeThe number of possible clock sequence values
int$counterSizeThe number of possible counter values
int$offsetSizeThe number of possible offset values
Returns
array (result of UIDGenerator::millitime(), counter, clock sequence)
Exceptions
RuntimeException

Definition at line 432 of file UIDGenerator.php.

References $time, and timeWaitUntil().

UIDGenerator::getTimestampedID128 ( array  $info)
protected
Parameters
array$infoThe result of UIDGenerator::getTimeAndDelay() or a plain (UIDGenerator::millitime(), counter, clock sequence) array.
Returns
string 128 bits
Exceptions
RuntimeException

Definition at line 185 of file UIDGenerator.php.

References $nodeId48, $time, and millisecondsSinceEpochBinary().

UIDGenerator::getTimestampedID88 ( array  $info)
protected
Parameters
array$infoThe result of UIDGenerator::getTimeAndDelay() or a plain (UIDGenerator::millitime(), counter, clock sequence) array.
Returns
string 88 bits
Exceptions
RuntimeException

Definition at line 131 of file UIDGenerator.php.

References $nodeId32, $time, and millisecondsSinceEpochBinary().

UIDGenerator::getUUIDv1 ( array  $info)
protected
Parameters
array$infoResult of UIDGenerator::getTimeAndDelay()
Returns
string 128 bits

Definition at line 241 of file UIDGenerator.php.

References $nodeId48, and intervalsSinceGregorianBinary().

UIDGenerator::intervalsSinceGregorianBinary ( array  $time,
  $delta = 0 
)
protected
Parameters
array$timeResult of UIDGenerator::millitime()
integer$deltaNumber of intervals to add on to the timestamp
Returns
string 60 bits of "100ns intervals since 15 October 1582" (rolls over in 3400)
Exceptions
RuntimeException

Definition at line 550 of file UIDGenerator.php.

References $time, and list.

Referenced by getUUIDv1().

UIDGenerator::millisecondsSinceEpochBinary ( array  $time)
protected
Parameters
array$timeResult of UIDGenerator::millitime()
Returns
string 46 LSBs of "milliseconds since epoch" in binary (rolls over in 4201)
Exceptions
RuntimeException

Definition at line 533 of file UIDGenerator.php.

References $time, and list.

Referenced by getTimestampedID128(), and getTimestampedID88().

static UIDGenerator::millitime ( )
staticprotected
Returns
array (current time in seconds, milliseconds since then)

Definition at line 577 of file UIDGenerator.php.

References list.

static UIDGenerator::newRawUUIDv1 ( )
static

Return an RFC4122 compliant v1 UUID.

Returns
string 32 hex characters with no hyphens
Exceptions
RuntimeException
Since
1.27

Definition at line 233 of file UIDGenerator.php.

Referenced by UIDGeneratorTest\testUUIDv1().

static UIDGenerator::newRawUUIDv4 (   $flags = 0)
static

Return an RFC4122 compliant v4 UUID.

Parameters
int$flagsBitfield (supports UIDGenerator::QUICK_RAND)
Returns
string 32 hex characters with no hyphens
Exceptions
RuntimeException

Definition at line 312 of file UIDGenerator.php.

References $flags.

Referenced by JobQueueRedis\getNewJobFields(), UIDGeneratorTest\testRawUUIDv4(), and UIDGeneratorTest\testRawUUIDv4QuickRand().

static UIDGenerator::newSequentialPerNodeID (   $bucket,
  $bits = 48,
  $flags = 0 
)
static

Return an ID that is sequential only for this node and bucket.

These IDs are suitable for per-host sequence numbers, e.g. for some packet protocols. If UIDGenerator::QUICK_VOLATILE is used the counter might reset on server restart.

Parameters
string$bucketArbitrary bucket name (should be ASCII)
int$bitsBit size (<=48) of resulting numbers before wrap-around
int$flags(supports UIDGenerator::QUICK_VOLATILE)
Returns
float Integer value as float
Since
1.23

Definition at line 328 of file UIDGenerator.php.

References $flags.

Referenced by UIDGeneratorTest\testNewSequentialID().

static UIDGenerator::newSequentialPerNodeIDs (   $bucket,
  $bits,
  $count,
  $flags = 0 
)
static

Return IDs that are sequential only for this node and bucket.

See also
UIDGenerator::newSequentialPerNodeID()
Parameters
string$bucketArbitrary bucket name (should be ASCII)
int$bitsBit size (16 to 48) of resulting numbers before wrap-around
int$countNumber of IDs to return
int$flags(supports UIDGenerator::QUICK_VOLATILE)
Returns
array Ordered list of float integer values
Since
1.23

Definition at line 343 of file UIDGenerator.php.

References $count, and $flags.

Referenced by CdnCacheUpdate\HTCPPurge(), and UIDGeneratorTest\testNewSequentialIDs().

static UIDGenerator::newTimestampedUID128 (   $base = 10)
static

Get a statistically unique 128-bit unsigned integer ID string.

The bits of the UID are prefixed with the time (down to the millisecond).

These IDs are suitable as globally unique IDs, without any enforced uniqueness. New rows almost always have higher UIDs, which makes B-TREE updates on INSERT fast. They can also be stored as "DECIMAL(39) UNSIGNED" or BINARY(16) in MySQL.

UID generation is serialized on each server (as the node ID is for the whole machine).

Parameters
int$baseSpecifies a base other than 10
Returns
string Number
Exceptions
RuntimeException

Definition at line 167 of file UIDGenerator.php.

References $base.

Referenced by ExternalStoreMwstore\store().

static UIDGenerator::newTimestampedUID88 (   $base = 10)
static

Get a statistically unique 88-bit unsigned integer ID string.

The bits of the UID are prefixed with the time (down to the millisecond).

These IDs are suitable as values for the shard key of distributed data. If a column uses these as values, it should be declared UNIQUE to handle collisions. New rows almost always have higher UIDs, which makes B-TREE updates on INSERT fast. They can also be stored "DECIMAL(27) UNSIGNED" or BINARY(11) in MySQL.

UID generation is serialized on each server (as the node ID is for the whole machine).

Parameters
int$baseSpecifies a base other than 10
Returns
string Number
Exceptions
RuntimeException

Definition at line 114 of file UIDGenerator.php.

References $base.

static UIDGenerator::newUUIDv1 ( )
static

Return an RFC4122 compliant v1 UUID.

Returns
string
Exceptions
RuntimeException
Since
1.27

Definition at line 218 of file UIDGenerator.php.

Referenced by UIDGeneratorTest\testUUIDv1().

static UIDGenerator::newUUIDv4 (   $flags = 0)
static

Return an RFC4122 compliant v4 UUID.

Parameters
int$flagsBitfield (supports UIDGenerator::QUICK_RAND)
Returns
string
Exceptions
RuntimeException

Definition at line 286 of file UIDGenerator.php.

References $flags, MWCryptRand\generateHex(), and wfRandomString().

Referenced by UIDGeneratorTest\testUUIDv4().

static UIDGenerator::singleton ( )
staticprotected
Todo:
: move to MW-specific factory class and inject temp dir
Returns
UIDGenerator

Definition at line 91 of file UIDGenerator.php.

UIDGenerator::timeWaitUntil ( array  $time)
protected

Wait till the current timestamp reaches $time and return the current timestamp.

This returns false if it would have to wait more than 10ms.

Parameters
array$timeResult of UIDGenerator::millitime()
Returns
array|bool UIDGenerator::millitime() result or false

Definition at line 517 of file UIDGenerator.php.

Referenced by getTimeAndDelay().

static UIDGenerator::unitTestTearDown ( )
static

Cleanup resources when tearing down after a unit test.

This is a cleanup method primarily meant to be used from unit tests to avoid poluting the local filesystem. If used outside of a unit test environment it should be used with caution as it may destroy state saved in the files.

See also
deleteCacheFiles
Since
1.23

Definition at line 621 of file UIDGenerator.php.

Referenced by UIDGeneratorTest\tearDown().

Member Data Documentation

array UIDGenerator::$fileHandles = []
protected

Definition at line 44 of file UIDGenerator.php.

UIDGenerator UIDGenerator::$instance = null
staticprotected

Definition at line 33 of file UIDGenerator.php.

UIDGenerator::$lockFile128
protected

Definition at line 40 of file UIDGenerator.php.

UIDGenerator::$lockFile88
protected

Definition at line 39 of file UIDGenerator.php.

UIDGenerator::$lockFileUUID
protected

Definition at line 41 of file UIDGenerator.php.

UIDGenerator::$nodeId32
protected

Definition at line 36 of file UIDGenerator.php.

Referenced by getTimestampedID88().

UIDGenerator::$nodeId48
protected

Definition at line 37 of file UIDGenerator.php.

Referenced by getTimestampedID128(), and getUUIDv1().

UIDGenerator::$nodeIdFile
protected

Definition at line 35 of file UIDGenerator.php.

const UIDGenerator::QUICK_RAND = 1
const UIDGenerator::QUICK_VOLATILE = 2

Definition at line 47 of file UIDGenerator.php.

Referenced by CdnCacheUpdate\HTCPPurge().


The documentation for this class was generated from the following file: