Class for getting statistically unique IDs. More...

Collaboration diagram for UIDGenerator:

Public Member Functions
	__destruct ()
Static Public Member Functions
static	newRawUUIDv4 ($flags=0)
	Return an RFC4122 compliant v4 UUID.
static	newSequentialPerNodeID ($bucket, $bits=48, $flags=0)
	Return an ID that is sequential only for this node and bucket.
static	newSequentialPerNodeIDs ($bucket, $bits, $count, $flags=0)
	Return IDs that are sequential only for this node and bucket.
static	newTimestampedUID128 ($base=10)
	Get a statistically unique 128-bit unsigned integer ID string.
static	newTimestampedUID88 ($base=10)
	Get a statistically unique 88-bit unsigned integer ID string.
static	newUUIDv4 ($flags=0)
	Return an RFC4122 compliant v4 UUID.
static	unitTestTearDown ()
	Cleanup resources when tearing down after a unit test.
Public Attributes
const	QUICK_RAND = 1
const	QUICK_VOLATILE = 2
Protected Member Functions
	__construct ()
	deleteCacheFiles ()
	Delete all cache files that have been created.
	getSequentialPerNodeIDs ($bucket, $bits, $count, $flags)
	Return IDs that are sequential only for this node and bucket.
	getTimestampAndDelay ($lockFile, $clockSeqSize, $counterSize)
	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)
	millisecondsSinceEpochBinary (array $time)
	timeWaitUntil (array $time)
	Wait till the current timestamp reaches $time and return the current timestamp.
Static Protected Member Functions
static	millitime ()
static	singleton ()
Protected Attributes
array	$fileHandles = array()
	*
	$lockFile128
	$lockFile88
	$nodeId32
	$nodeId48
	$nodeIdFile
Static Protected Attributes
static	$instance = null

Detailed Description

Class for getting statistically unique IDs.

Since:: 1.21

Definition at line 29 of file UIDGenerator.php.

Constructor & Destructor Documentation

UIDGenerator::__construct ( ) [protected]

Definition at line 45 of file UIDGenerator.php.

References array(), MWCryptRand\generateHex(), wfBaseConvert(), wfIsWindows(), wfRestoreWarnings(), wfShellExec(), wfSuppressWarnings(), and wfTempDir().

UIDGenerator::__destruct ( )

Definition at line 503 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 470 of file UIDGenerator.php.

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 (1 to 10000)
int	$flags	(supports UIDGenerator::QUICK_VOLATILE)

Returns:: array Ordered list of float integer values

Definition at line 263 of file UIDGenerator.php.

UIDGenerator::getTimestampAndDelay	(	$	lockFile,
		$	clockSeqSize,
		$	counterSize
	)		`[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

Returns:: array (result of UIDGenerator::millitime(), counter, clock sequence)

Exceptions:

MWException

Definition at line 344 of file UIDGenerator.php.

UIDGenerator::getTimestampedID128 ( array $ info ) [protected]

Parameters:

array $info (UIDGenerator::millitime(), counter, clock sequence)

Returns:: string 128 bits

Definition at line 166 of file UIDGenerator.php.

UIDGenerator::getTimestampedID88 ( array $ info ) [protected]

Parameters:

array $info (UIDGenerator::millitime(), counter, clock sequence)

Returns:: string 88 bits

Definition at line 122 of file UIDGenerator.php.

UIDGenerator::millisecondsSinceEpochBinary ( array $ time ) [protected]

Parameters:

array $time Result of UIDGenerator::millitime()

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

Definition at line 439 of file UIDGenerator.php.

static UIDGenerator::millitime ( ) [static, protected]

Returns:: array (current time in seconds, milliseconds since then)

Definition at line 453 of file UIDGenerator.php.

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:

MWException

Definition at line 217 of file UIDGenerator.php.

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

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	$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 (1 to 10000)
int	$flags	(supports UIDGenerator::QUICK_VOLATILE)

Returns:: array Ordered list of float integer values

Since:: 1.23

Definition at line 248 of file UIDGenerator.php.

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

Returns:: string Number

Exceptions:

MWException

Definition at line 152 of file UIDGenerator.php.

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

Returns:: string Number

Exceptions:

MWException

Definition at line 108 of file UIDGenerator.php.

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

Return an RFC4122 compliant v4 UUID.

Parameters:

int $flags Bitfield (supports UIDGenerator::QUICK_RAND)

Returns:: string

Exceptions:

MWException

Definition at line 191 of file UIDGenerator.php.

Referenced by UIDGeneratorTest\testUUIDv4().

static UIDGenerator::singleton ( ) [static, protected]

Returns:: UIDGenerator

Definition at line 85 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 $time Result of UIDGenerator::millitime()

Returns:: array|bool UIDGenerator::millitime() result or false

Definition at line 424 of file UIDGenerator.php.

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.