MediaWiki  master
Wikimedia\UUID\GlobalIdGenerator Class Reference

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

Collaboration diagram for Wikimedia\UUID\GlobalIdGenerator:

Public Member Functions

 __construct ( $tempDirectory, BagOStuff $srvCache, callable $shellCallback)
 
 __destruct ()
 
 getTimestampFromUUIDv1 (string $uuid, int $format=TS_MW)
 Get timestamp in a specified format from UUIDv1. More...
 
 newRawUUIDv1 ()
 Return an RFC4122 compliant v1 UUID. More...
 
 newRawUUIDv4 ()
 Return an RFC4122 compliant v4 UUID. More...
 
 newSequentialPerNodeID ( $bucket, $bits=48, $flags=0)
 Return an ID that is sequential only for this node and bucket. More...
 
 newSequentialPerNodeIDs ( $bucket, $bits, $count, $flags=0)
 Return IDs that are sequential only for this node and bucket. More...
 
 newTimestampedUID128 ( $base=10)
 Get a statistically unique 128-bit unsigned integer ID string. More...
 
 newTimestampedUID88 ( $base=10)
 Get a statistically unique 88-bit unsigned integer ID string. More...
 
 newUUIDv1 ()
 Return an RFC4122 compliant v1 UUID. More...
 
 newUUIDv4 ()
 Return an RFC4122 compliant v4 UUID. More...
 
 unitTestTearDown ()
 Cleanup resources when tearing down after a unit test (T46850) More...
 

Public Attributes

const QUICK_VOLATILE = 1
 

Protected Member Functions

 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...
 

Protected Attributes

array $fileHandles = []
 Cached file handles. More...
 
bool $loaded = false
 Whether initialization completed. 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...
 
callable $shellCallback
 Callback for running shell commands. More...
 
BagOStuff $srvCache
 Server-local persistent cache instance. More...
 
string $tmpDir
 Temporary directory. More...
 

Private Member Functions

 deleteCacheFiles ()
 Delete all cache files that have been created (T46850) More...
 
 getNodeId32 ()
 
 getNodeId48 ()
 
 load ()
 Load the node ID information. More...
 

Private Attributes

const FILE_PREFIX = 'mw-GlobalIdGenerator'
 Avoid using CLASS so namespace separators aren't interpreted as path components on Windows (T259693) More...
 

Detailed Description

Class for getting statistically unique IDs without a central coordinator.

Since
1.35

Definition at line 36 of file GlobalIdGenerator.php.

Constructor & Destructor Documentation

◆ __construct()

Wikimedia\UUID\GlobalIdGenerator::__construct (   $tempDirectory,
BagOStuff  $srvCache,
callable  $shellCallback 
)
Parameters
string$tempDirectoryA writable temporary directory
BagOStuff$srvCacheA server-local APC-like cache instance
callback$shellCallbackA callback that takes a shell command and returns the output

Definition at line 76 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\$shellCallback, and Wikimedia\UUID\GlobalIdGenerator\$srvCache.

◆ __destruct()

Wikimedia\UUID\GlobalIdGenerator::__destruct ( )

Definition at line 738 of file GlobalIdGenerator.php.

Member Function Documentation

◆ deleteCacheFiles()

Wikimedia\UUID\GlobalIdGenerator::deleteCacheFiles ( )
private

Delete all cache files that have been created (T46850)

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

Definition at line 707 of file GlobalIdGenerator.php.

References $path.

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

◆ getNodeId32()

Wikimedia\UUID\GlobalIdGenerator::getNodeId32 ( )
private

◆ getNodeId48()

Wikimedia\UUID\GlobalIdGenerator::getNodeId48 ( )
private

◆ getSequentialPerNodeIDs()

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

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

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 GlobalIdGenerator::QUICK_VOLATILE)
Returns
array Ordered list of float integer values
Exceptions
RuntimeException
See also
GlobalIdGenerator::newSequentialPerNodeID()

Definition at line 364 of file GlobalIdGenerator.php.

References $cache, $path, and Wikimedia\UUID\GlobalIdGenerator\$srvCache.

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 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 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 444 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$infoThe result of GlobalIdGenerator::getTimeAndDelay(), for sub classes, a seqencial array like (time, offsetCounter, clkSeq).
Returns
string 128 bits
Exceptions
RuntimeException

Definition at line 176 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\getNodeId48(), and Wikimedia\UUID\GlobalIdGenerator\millisecondsSinceEpochBinary().

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

◆ getTimestampedID88()

Wikimedia\UUID\GlobalIdGenerator::getTimestampedID88 ( array  $info)
protected
Parameters
array$inforesult of GlobalIdGenerator::getTimeAndDelay(), or for sub classes, a sequential array like (time, offsetCounter).
Returns
string 88 bits
Exceptions
RuntimeException

Definition at line 124 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\getNodeId32(), and Wikimedia\UUID\GlobalIdGenerator\millisecondsSinceEpochBinary().

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

◆ getTimestampFromUUIDv1()

Wikimedia\UUID\GlobalIdGenerator::getTimestampFromUUIDv1 ( string  $uuid,
int  $format = TS_MW 
)

Get timestamp in a specified format from UUIDv1.

Parameters
string$uuidthe UUID to get the timestamp from
int$formatthe format to convert the timestamp to. Default: TS_MW
Returns
string|false timestamp in requested format or false

Definition at line 335 of file GlobalIdGenerator.php.

◆ getUUIDv1()

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

◆ intervalsSinceGregorianBinary()

Wikimedia\UUID\GlobalIdGenerator::intervalsSinceGregorianBinary ( array  $time,
  $delta = 0 
)
protected
Parameters
array$timeArray of second and millisecond integers
int$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 613 of file GlobalIdGenerator.php.

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

◆ load()

Wikimedia\UUID\GlobalIdGenerator::load ( )
private

Load the node ID information.

Definition at line 640 of file GlobalIdGenerator.php.

References $line.

Referenced by Wikimedia\UUID\GlobalIdGenerator\getNodeId32(), and Wikimedia\UUID\GlobalIdGenerator\getNodeId48().

◆ millisecondsSinceEpochBinary()

Wikimedia\UUID\GlobalIdGenerator::millisecondsSinceEpochBinary ( array  $time)
protected
Parameters
array$timeArray of second and millisecond integers
Returns
string 46 LSBs of "milliseconds since epoch" in binary (rolls over in 4201)
Exceptions
RuntimeException

Definition at line 596 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 261 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 294 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\newUUIDv4().

◆ newSequentialPerNodeID()

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

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 GlobalIdGenerator::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 GlobalIdGenerator::QUICK_VOLATILE)
Returns
float Integer value as float

Definition at line 310 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\newSequentialPerNodeIDs().

◆ newSequentialPerNodeIDs()

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

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

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 GlobalIdGenerator::QUICK_VOLATILE)
Returns
array Ordered list of float integer values
See also
GlobalIdGenerator::newSequentialPerNodeID()

Definition at line 324 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\getSequentialPerNodeIDs().

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

◆ newTimestampedUID128()

Wikimedia\UUID\GlobalIdGenerator::newTimestampedUID128 (   $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$baseSpecifies a base other than 10
Returns
string Number
Exceptions
RuntimeException

Definition at line 159 of file GlobalIdGenerator.php.

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

◆ newTimestampedUID88()

Wikimedia\UUID\GlobalIdGenerator::newTimestampedUID88 (   $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$baseSpecifies a base other than 10
Returns
string Number
Exceptions
RuntimeException

Definition at line 107 of file GlobalIdGenerator.php.

References $base, 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 206 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 271 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$timeResult of time()
Returns
int|bool Timestamp or false

Definition at line 577 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.

Definition at line 734 of file GlobalIdGenerator.php.

References Wikimedia\UUID\GlobalIdGenerator\deleteCacheFiles().

Member Data Documentation

◆ $fileHandles

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

Cached file handles.

Definition at line 61 of file GlobalIdGenerator.php.

◆ $loaded

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

Whether initialization completed.

Definition at line 52 of file GlobalIdGenerator.php.

◆ $lockFile128

string Wikimedia\UUID\GlobalIdGenerator::$lockFile128
protected

Local file path.

Definition at line 56 of file GlobalIdGenerator.php.

◆ $lockFile88

string Wikimedia\UUID\GlobalIdGenerator::$lockFile88
protected

Local file path.

Definition at line 54 of file GlobalIdGenerator.php.

◆ $lockFileUUID

string Wikimedia\UUID\GlobalIdGenerator::$lockFileUUID
protected

Local file path.

Definition at line 58 of file GlobalIdGenerator.php.

◆ $nodeId32

string Wikimedia\UUID\GlobalIdGenerator::$nodeId32
protected

Node ID in binary (32 bits)

Definition at line 47 of file GlobalIdGenerator.php.

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

◆ $nodeId48

string Wikimedia\UUID\GlobalIdGenerator::$nodeId48
protected

Node ID in binary (48 bits)

Definition at line 49 of file GlobalIdGenerator.php.

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

◆ $nodeIdFile

string Wikimedia\UUID\GlobalIdGenerator::$nodeIdFile
protected

Local file path.

Definition at line 45 of file GlobalIdGenerator.php.

◆ $shellCallback

callable Wikimedia\UUID\GlobalIdGenerator::$shellCallback
protected

Callback for running shell commands.

Definition at line 40 of file GlobalIdGenerator.php.

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

◆ $srvCache

BagOStuff Wikimedia\UUID\GlobalIdGenerator::$srvCache
protected

Server-local persistent cache instance.

Definition at line 38 of file GlobalIdGenerator.php.

Referenced by Wikimedia\UUID\GlobalIdGenerator\__construct(), and Wikimedia\UUID\GlobalIdGenerator\getSequentialPerNodeIDs().

◆ $tmpDir

string Wikimedia\UUID\GlobalIdGenerator::$tmpDir
protected

Temporary directory.

Definition at line 43 of file GlobalIdGenerator.php.

◆ FILE_PREFIX

const Wikimedia\UUID\GlobalIdGenerator::FILE_PREFIX = 'mw-GlobalIdGenerator'
private

Avoid using CLASS so namespace separators aren't interpreted as path components on Windows (T259693)

Definition at line 69 of file GlobalIdGenerator.php.

◆ QUICK_VOLATILE

const Wikimedia\UUID\GlobalIdGenerator::QUICK_VOLATILE = 1

Definition at line 63 of file GlobalIdGenerator.php.


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