Class for getting statistically unique IDs without a central coordinator. More...

Public Member Functions
	__construct ( $tempDirectory, $shellCallback)

	__destruct ()

	getTimestampFromUUIDv1 (string $uuid, int\|TS $format=TS::MW)
	Get timestamp in a specified format from UUIDv1.

	newRawUUIDv1 ()
	Return an RFC4122 compliant v1 UUID.

	newRawUUIDv4 ()
	Return an RFC4122 compliant v4 UUID.

	newSequentialPerNodeID ( $bucket, $bits=48)
	Return an ID that is sequential only for this node and bucket.

	newSequentialPerNodeIDs ( $bucket, $bits, $count)
	Return IDs that are sequential only for this node and bucket.

	newTimestampedUID128 (int $base=10)
	Get a statistically unique 128-bit unsigned integer ID string.

	newTimestampedUID88 (int $base=10)
	Get a statistically unique 88-bit unsigned integer ID string.

	newUUIDv1 ()
	Return an RFC4122 compliant v1 UUID.

	newUUIDv4 ()
	Return an RFC4122 compliant v4 UUID.

	unitTestTearDown ()
	Cleanup resources when tearing down after a unit test (T46850)

Protected Member Functions
	getSequentialPerNodeIDs ( $bucket, $bits, $count)
	Return IDs that are sequential only for this node and bucket.

	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.

	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.

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

bool	$loaded = false
	Whether initialization completed.

string	$lockFile128
	Local file path.

string	$lockFile88
	Local file path.

string	$lockFileUUID
	Local file path.

string	$nodeId32
	Node ID in binary (32 bits)

string	$nodeId48
	Node ID in binary (48 bits)

string	$nodeIdFile
	Local file path.

callable	$shellCallback
	Callback for running shell commands.

string	$tmpDir
	Temporary directory.

string	$uniqueFilePrefix
	File prefix containing user ID to prevent collisions if multiple users run MediaWiki (T268420) and getmyuid() is enabled.

Detailed Description

Class for getting statistically unique IDs without a central coordinator.

Since: 1.35

Definition at line 20 of file GlobalIdGenerator.php.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\UUID\GlobalIdGenerator::__construct	(		$tempDirectory,
			$shellCallback )

Parameters

string \| bool	$tempDirectory	A writable temporary directory
callback	$shellCallback	A callback that takes a shell command and returns the output

Definition at line 71 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\$shellCallback.

◆ __destruct()

Wikimedia\UUID\GlobalIdGenerator::__destruct ( )

Definition at line 733 of file GlobalIdGenerator.php.

Member Function Documentation

◆ getSequentialPerNodeIDs()

Wikimedia\UUID\GlobalIdGenerator::getSequentialPerNodeIDs	(	$bucket,
		$bits,
		$count )

protected

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

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

Returns: array Ordered list of float integer values

Exceptions

RuntimeException

See also: GlobalIdGenerator::newSequentialPerNodeID()

Definition at line 360 of file GlobalIdGenerator.php.

References $path.

Referenced by Wikimedia\UUID\GlobalIdGenerator\newSequentialPerNodeIDs().

◆ getTimeAndDelay()

Wikimedia\UUID\GlobalIdGenerator::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 basis.

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:

GlobalIdGenerator::CLOCK_TIME: (integer seconds, integer milliseconds) array
GlobalIdGenerator::CLOCK_COUNTER: integer millisecond tie-breaking counter
GlobalIdGenerator::CLOCK_SEQUENCE: integer clock identifier that is local to the node
GlobalIdGenerator::CLOCK_OFFSET: integer offset for millisecond tie-breaking counter
GlobalIdGenerator::CLOCK_OFFSET_COUNTER: integer; CLOCK_COUNTER with CLOCK_OFFSET applied

Exceptions

RuntimeException

Definition at line 432 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\timeWaitUntil().

Referenced by Wikimedia\UUID\GlobalIdGenerator\newTimestampedUID128(), Wikimedia\UUID\GlobalIdGenerator\newTimestampedUID88(), and Wikimedia\UUID\GlobalIdGenerator\newUUIDv1().

◆ getTimestampedID128()

Wikimedia\UUID\GlobalIdGenerator::getTimestampedID128 ( array $info )

protected

Parameters

array $info The result of GlobalIdGenerator::getTimeAndDelay()

Returns: string 128 bits

Exceptions

RuntimeException

Definition at line 178 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\millisecondsSinceEpochBinary().

Referenced by Wikimedia\UUID\GlobalIdGenerator\newTimestampedUID128().

◆ getTimestampedID88()

Wikimedia\UUID\GlobalIdGenerator::getTimestampedID88 ( array $info )

protected

Parameters

array $info result of GlobalIdGenerator::getTimeAndDelay()

Returns: string 88 bits

Exceptions

RuntimeException

Definition at line 132 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\millisecondsSinceEpochBinary().

Referenced by Wikimedia\UUID\GlobalIdGenerator\newTimestampedUID88().

◆ getTimestampFromUUIDv1()

Wikimedia\UUID\GlobalIdGenerator::getTimestampFromUUIDv1	(	string	$uuid,
		int\|TS	$format = TS::MW )

Get timestamp in a specified format from UUIDv1.

Parameters

string	$uuid	the UUID to get the timestamp from
int \| TS	$format	the format to convert the timestamp to. Default: TS::MW

Returns: string|false timestamp in requested format or false

Definition at line 332 of file GlobalIdGenerator.php.

◆ getUUIDv1()

Wikimedia\UUID\GlobalIdGenerator::getUUIDv1 ( array $info )

protected

Parameters

array $info Result of GlobalIdGenerator::getTimeAndDelay()

Returns: string 128 bits

Definition at line 215 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\intervalsSinceGregorianBinary().

Referenced by Wikimedia\UUID\GlobalIdGenerator\newUUIDv1().

◆ intervalsSinceGregorianBinary()

Wikimedia\UUID\GlobalIdGenerator::intervalsSinceGregorianBinary	(	array	$time,
			$delta = 0 )

protected

Parameters

	array{0:int,1:int}	$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 600 of file GlobalIdGenerator.php.

Referenced by Wikimedia\UUID\GlobalIdGenerator\getUUIDv1().

◆ millisecondsSinceEpochBinary()

Wikimedia\UUID\GlobalIdGenerator::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 583 of file GlobalIdGenerator.php.

Referenced by Wikimedia\UUID\GlobalIdGenerator\getTimestampedID128(), and Wikimedia\UUID\GlobalIdGenerator\getTimestampedID88().

◆ newRawUUIDv1()

Wikimedia\UUID\GlobalIdGenerator::newRawUUIDv1 ( )

Return an RFC4122 compliant v1 UUID.

Returns: string 32 hex characters with no hyphens

Exceptions

RuntimeException

Definition at line 262 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\newUUIDv1().

◆ newRawUUIDv4()

Wikimedia\UUID\GlobalIdGenerator::newRawUUIDv4 ( )

Return an RFC4122 compliant v4 UUID.

Returns: string 32 hex characters with no hyphens

Exceptions

RuntimeException

Definition at line 295 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\newUUIDv4().

◆ newSequentialPerNodeID()

Wikimedia\UUID\GlobalIdGenerator::newSequentialPerNodeID	(		$bucket,
			$bits = 48 )

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.

Parameters

string	$bucket	Arbitrary bucket name (should be ASCII)
int	$bits	Bit size (<=48) of resulting numbers before wrap-around

Returns: float Integer value as float

Definition at line 308 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\newSequentialPerNodeIDs().

◆ newSequentialPerNodeIDs()

Wikimedia\UUID\GlobalIdGenerator::newSequentialPerNodeIDs	(	$bucket,
		$bits,
		$count )

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

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

Returns: array Ordered list of float integer values

See also: GlobalIdGenerator::newSequentialPerNodeID()

Definition at line 321 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\getSequentialPerNodeIDs().

Referenced by Wikimedia\UUID\GlobalIdGenerator\newSequentialPerNodeID().

◆ newTimestampedUID128()

Wikimedia\UUID\GlobalIdGenerator::newTimestampedUID128 ( int $base = 10 )

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 163 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\getTimeAndDelay(), and Wikimedia\UUID\GlobalIdGenerator\getTimestampedID128().

◆ newTimestampedUID88()

Wikimedia\UUID\GlobalIdGenerator::newTimestampedUID88 ( int $base = 10 )

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 117 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\getTimeAndDelay(), and Wikimedia\UUID\GlobalIdGenerator\getTimestampedID88().

◆ newUUIDv1()

Wikimedia\UUID\GlobalIdGenerator::newUUIDv1 ( )

Return an RFC4122 compliant v1 UUID.

Returns: string

Exceptions

RuntimeException

Definition at line 204 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\getTimeAndDelay(), and Wikimedia\UUID\GlobalIdGenerator\getUUIDv1().

Referenced by Wikimedia\UUID\GlobalIdGenerator\newRawUUIDv1().

◆ newUUIDv4()

Wikimedia\UUID\GlobalIdGenerator::newUUIDv4 ( )

Return an RFC4122 compliant v4 UUID.

Returns: string

Exceptions

RuntimeException

Definition at line 272 of file GlobalIdGenerator.php.

Referenced by Wikimedia\UUID\GlobalIdGenerator\newRawUUIDv4().

◆ timeWaitUntil()

Wikimedia\UUID\GlobalIdGenerator::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 563 of file GlobalIdGenerator.php.

Referenced by Wikimedia\UUID\GlobalIdGenerator\getTimeAndDelay().

◆ unitTestTearDown()

Wikimedia\UUID\GlobalIdGenerator::unitTestTearDown ( )

Cleanup resources when tearing down after a unit test (T46850)

This is a cleanup method primarily meant to be used from unit tests to avoid polluting 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.

Access: internal: For use by unit tests

See also: deleteCacheFiles

Definition at line 729 of file GlobalIdGenerator.php.

Member Data Documentation

◆ $fileHandles

array Wikimedia\UUID\GlobalIdGenerator::$fileHandles = []

protected

Cached file handles.

Definition at line 48 of file GlobalIdGenerator.php.

◆ $loaded

bool Wikimedia\UUID\GlobalIdGenerator::$loaded = false

protected

Whether initialization completed.

Definition at line 39 of file GlobalIdGenerator.php.

◆ $lockFile128

string Wikimedia\UUID\GlobalIdGenerator::$lockFile128

protected

Local file path.

Definition at line 43 of file GlobalIdGenerator.php.

◆ $lockFile88

string Wikimedia\UUID\GlobalIdGenerator::$lockFile88

protected

Local file path.

Definition at line 41 of file GlobalIdGenerator.php.

◆ $lockFileUUID

string Wikimedia\UUID\GlobalIdGenerator::$lockFileUUID

protected

Local file path.

Definition at line 45 of file GlobalIdGenerator.php.

◆ $nodeId32

string Wikimedia\UUID\GlobalIdGenerator::$nodeId32

protected

Node ID in binary (32 bits)

Definition at line 34 of file GlobalIdGenerator.php.

◆ $nodeId48

string Wikimedia\UUID\GlobalIdGenerator::$nodeId48

protected

Node ID in binary (48 bits)

Definition at line 36 of file GlobalIdGenerator.php.

◆ $nodeIdFile

string Wikimedia\UUID\GlobalIdGenerator::$nodeIdFile

protected

Local file path.

Definition at line 32 of file GlobalIdGenerator.php.

◆ $shellCallback

callable Wikimedia\UUID\GlobalIdGenerator::$shellCallback

protected

Callback for running shell commands.

Definition at line 22 of file GlobalIdGenerator.php.

Referenced by Wikimedia\UUID\GlobalIdGenerator\__construct().

◆ $tmpDir

string Wikimedia\UUID\GlobalIdGenerator::$tmpDir

protected

Temporary directory.

Definition at line 25 of file GlobalIdGenerator.php.

◆ $uniqueFilePrefix

string Wikimedia\UUID\GlobalIdGenerator::$uniqueFilePrefix

protected

File prefix containing user ID to prevent collisions if multiple users run MediaWiki (T268420) and getmyuid() is enabled.

Definition at line 30 of file GlobalIdGenerator.php.

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

includes/libs/UUID/GlobalIdGenerator.php

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

◆ __destruct()

Member Function Documentation

◆ getSequentialPerNodeIDs()

◆ getTimeAndDelay()

◆ getTimestampedID128()

◆ getTimestampedID88()

◆ getTimestampFromUUIDv1()

◆ getUUIDv1()

◆ intervalsSinceGregorianBinary()

◆ millisecondsSinceEpochBinary()

◆ newRawUUIDv1()

◆ newRawUUIDv4()

◆ newSequentialPerNodeID()

◆ newSequentialPerNodeIDs()

◆ newTimestampedUID128()

◆ newTimestampedUID88()

◆ newUUIDv1()

◆ newUUIDv4()

◆ timeWaitUntil()

◆ unitTestTearDown()

Member Data Documentation

◆ $fileHandles

◆ $loaded

◆ $lockFile128

◆ $lockFile88

◆ $lockFileUUID

◆ $nodeId32

◆ $nodeId48

◆ $nodeIdFile

◆ $shellCallback

◆ $tmpDir

◆ $uniqueFilePrefix