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 ()

	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 ( $time)
	Wait till the current timestamp reaches $time and return the current timestamp. More...

Static Protected Member Functions
static	singleton ()

Protected Attributes
array	$fileHandles = []
	Cached file handles. More...

string	$lockFile128
	Local file path. More...

string	$lockFile88
	Local file path. More...

string	$lockFileUUID
	Local file path. More...

string	$nodeId32
	Node ID in binary (32 bits) More...

string	$nodeId48
	Node ID in binary (48 bits) More...

string	$nodeIdFile
	Local file path. More...

Static Protected Attributes
static UIDGenerator	$instance = null

Private Member Functions
	deleteCacheFiles ()
	Delete all cache files that have been created. More...

Detailed Description

Class for getting statistically unique IDs.

Since: 1.21

Definition at line 30 of file UIDGenerator.php.

Constructor & Destructor Documentation

◆ __construct()

UIDGenerator::__construct ( )

protected

Definition at line 53 of file UIDGenerator.php.

References $line, MWCryptRand\generateHex(), wfIsWindows(), wfShellExec(), and wfTempDir().

◆ __destruct()

UIDGenerator::__destruct ( )

Definition at line 683 of file UIDGenerator.php.

Member Function Documentation

◆ deleteCacheFiles()

UIDGenerator::deleteCacheFiles ( )

private

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 648 of file UIDGenerator.php.

References $path, and as.

◆ getSequentialPerNodeIDs()

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

protected

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

See also: UIDGenerator::newSequentialPerNodeID()

Parameters

string	$bucket	Arbitrary bucket name (should be ASCII)
int	$bits	Bit size (16 to 48) of resulting numbers before wrap-around
int	$count	Number of IDs to return
int	$flags	(supports UIDGenerator::QUICK_VOLATILE)

Returns: array Ordered list of float integer values

Exceptions

RuntimeException

Definition at line 363 of file UIDGenerator.php.

References $cache, $path, wfIsCLI(), and wfTempDir().

◆ getTimeAndDelay()

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	$lockFile	Name of a local lock file
int	$clockSeqSize	The number of possible clock sequence values
int	$counterSize	The number of possible counter values
int	$offsetSize	The number of possible offset values

Returns

array Array with the following keys:

array 'time': array of seconds int and milliseconds int.
int 'counter'.
int 'clkSeq'.
int 'offset': .
int 'offsetCounter'.

Exceptions

RuntimeException

Definition at line 443 of file UIDGenerator.php.

References captcha-old\count, and timeWaitUntil().

◆ getTimestampedID128()

UIDGenerator::getTimestampedID128 ( array $info )

protected

Parameters

array $info The result of UIDGenerator::getTimeAndDelay(), for sub classes, a seqencial array like (time, offsetCounter, clkSeq).

Returns: string 128 bits

Exceptions

RuntimeException

Definition at line 189 of file UIDGenerator.php.

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

◆ getTimestampedID88()

UIDGenerator::getTimestampedID88 ( array $info )

protected

Parameters

array $info result of UIDGenerator::getTimeAndDelay(), or for sub classes, a seqencial array like (time, offsetCounter).

Returns: string 88 bits

Exceptions

RuntimeException

Definition at line 135 of file UIDGenerator.php.

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

◆ getUUIDv1()

UIDGenerator::getUUIDv1 ( array $info )

protected

Parameters

array $info Result of UIDGenerator::getTimeAndDelay()

Returns: string 128 bits

Definition at line 245 of file UIDGenerator.php.

References $nodeId48, and intervalsSinceGregorianBinary().

◆ intervalsSinceGregorianBinary()

UIDGenerator::intervalsSinceGregorianBinary	(	array	$time,
			$delta = `0`
	)

protected

Parameters

array	$time	Array of second and millisecond integers
int	$delta	Number 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 612 of file UIDGenerator.php.

References $time, and list.

Referenced by getUUIDv1().

◆ millisecondsSinceEpochBinary()

UIDGenerator::millisecondsSinceEpochBinary ( array $time )

protected

Parameters

array $time Array of second and millisecond integers

Returns: string 46 LSBs of "milliseconds since epoch" in binary (rolls over in 4201)

Exceptions

RuntimeException

Definition at line 595 of file UIDGenerator.php.

References $time, and list.

Referenced by getTimestampedID128(), and getTimestampedID88().

◆ newRawUUIDv1()

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 237 of file UIDGenerator.php.

Referenced by UIDGeneratorTest\testUUIDv1().

◆ newRawUUIDv4()

static UIDGenerator::newRawUUIDv4 ( $flags = 0 )

static

Return an RFC4122 compliant v4 UUID.

Parameters

int $flags Bitfield (supports UIDGenerator::QUICK_RAND)

Returns: string 32 hex characters with no hyphens

Exceptions

RuntimeException

Definition at line 316 of file UIDGenerator.php.

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

◆ newSequentialPerNodeID()

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	$bucket	Arbitrary bucket name (should be ASCII)
int	$bits	Bit 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 332 of file UIDGenerator.php.

Referenced by UIDGeneratorTest\testNewSequentialID().

◆ newSequentialPerNodeIDs()

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	$bucket	Arbitrary bucket name (should be ASCII)
int	$bits	Bit size (16 to 48) of resulting numbers before wrap-around
int	$count	Number of IDs to return
int	$flags	(supports UIDGenerator::QUICK_VOLATILE)

Returns: array Ordered list of float integer values

Since: 1.23

Definition at line 347 of file UIDGenerator.php.

References singleton().

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

◆ newTimestampedUID128()

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 $base Specifies a base other than 10

Returns: string Number

Exceptions

RuntimeException

Definition at line 171 of file UIDGenerator.php.

References $base, and singleton().

Referenced by ExternalStoreMwstore\store().

◆ newTimestampedUID88()

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 $base Specifies a base other than 10

Returns: string Number

Exceptions

RuntimeException

Definition at line 118 of file UIDGenerator.php.

References $base, and singleton().

◆ newUUIDv1()

static UIDGenerator::newUUIDv1 ( )

static

Return an RFC4122 compliant v1 UUID.

Returns: string

Exceptions

RuntimeException

Since: 1.27

Definition at line 222 of file UIDGenerator.php.

References singleton().

Referenced by UIDGeneratorTest\testUUIDv1().

◆ newUUIDv4()

static UIDGenerator::newUUIDv4 ( $flags = 0 )

static

Return an RFC4122 compliant v4 UUID.

Parameters

int $flags Bitfield (supports UIDGenerator::QUICK_RAND)

Returns: string

Exceptions

RuntimeException

Definition at line 290 of file UIDGenerator.php.

References MWCryptRand\generateHex(), QUICK_RAND, and wfRandomString().

Referenced by UIDGeneratorTest\testUUIDv4().

◆ singleton()

static UIDGenerator::singleton ( )

staticprotected

Todo:: move to MW-specific factory class and inject temp dir

Returns: UIDGenerator

Definition at line 95 of file UIDGenerator.php.

References $instance.

Referenced by newSequentialPerNodeIDs(), newTimestampedUID128(), newTimestampedUID88(), newUUIDv1(), and unitTestTearDown().

◆ timeWaitUntil()

UIDGenerator::timeWaitUntil ( $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

int $time Result of time()

Returns: int|bool Timestamp or false

Definition at line 576 of file UIDGenerator.php.

References $time.

Referenced by getTimeAndDelay().

◆ unitTestTearDown()

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.

Definition at line 677 of file UIDGenerator.php.

References singleton().

Referenced by UIDGeneratorTest\tearDown().

Member Data Documentation

◆ $fileHandles

array UIDGenerator::$fileHandles = []

protected

Cached file handles.

Definition at line 48 of file UIDGenerator.php.

◆ $instance

UIDGenerator UIDGenerator::$instance = null

staticprotected

Definition at line 32 of file UIDGenerator.php.

Referenced by singleton().

◆ $lockFile128

string UIDGenerator::$lockFile128

protected

Local file path.

Definition at line 43 of file UIDGenerator.php.

◆ $lockFile88

string UIDGenerator::$lockFile88

protected

Local file path.

Definition at line 41 of file UIDGenerator.php.

◆ $lockFileUUID

string UIDGenerator::$lockFileUUID

protected

Local file path.

Definition at line 45 of file UIDGenerator.php.

◆ $nodeId32

string UIDGenerator::$nodeId32

protected

Node ID in binary (32 bits)

Definition at line 36 of file UIDGenerator.php.

Referenced by getTimestampedID88().

◆ $nodeId48

string UIDGenerator::$nodeId48

protected

Node ID in binary (48 bits)

Definition at line 38 of file UIDGenerator.php.

Referenced by getTimestampedID128(), and getUUIDv1().

◆ $nodeIdFile

string UIDGenerator::$nodeIdFile

protected

Local file path.

Definition at line 34 of file UIDGenerator.php.

◆ QUICK_RAND

const UIDGenerator::QUICK_RAND = 1

Definition at line 50 of file UIDGenerator.php.

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

◆ QUICK_VOLATILE

const UIDGenerator::QUICK_VOLATILE = 2

Definition at line 51 of file UIDGenerator.php.

Referenced by CdnCacheUpdate\HTCPPurge().

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

includes/utils/UIDGenerator.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

◆ __destruct()

Member Function Documentation

◆ deleteCacheFiles()

◆ getSequentialPerNodeIDs()

◆ getTimeAndDelay()

◆ getTimestampedID128()

◆ getTimestampedID88()

◆ getUUIDv1()

◆ intervalsSinceGregorianBinary()

◆ millisecondsSinceEpochBinary()

◆ newRawUUIDv1()

◆ newRawUUIDv4()

◆ newSequentialPerNodeID()

◆ newSequentialPerNodeIDs()

◆ newTimestampedUID128()

◆ newTimestampedUID88()

◆ newUUIDv1()

◆ newUUIDv4()

◆ singleton()

◆ timeWaitUntil()

◆ unitTestTearDown()

Member Data Documentation

◆ $fileHandles

◆ $instance

◆ $lockFile128

◆ $lockFile88

◆ $lockFileUUID

◆ $nodeId32

◆ $nodeId48

◆ $nodeIdFile

◆ QUICK_RAND

◆ QUICK_VOLATILE