Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ toBytes(): string toHexadecimal(): string toUrn(): string to
- `getTimestampMillis()` returns the embedded timestamp as unix milliseconds for RFC time-based versions (v1, v2, v6, v7) and is much cheaper than `getDateTime()` since it builds no object. It floors to the millisecond, while `getDateTime()` rounds v1/v2/v6 100 ns timestamps to the nearest microsecond as ramsey/uuid does; it throws `UnsupportedOperationException` for non-time-based versions and non-RFC variants.
- `Uuid::uuid7()` accepts a unix-millisecond `int` as well as a `DateTimeInterface`, which skips the DateTime machinery entirely. The procedural `uuid_v7_at(int $unixMillis)` is the fastest explicit-timestamp form.
- Live-clock `uuid1()` and `uuid6()` share a timestamp high-water mark. If the clock stalls or moves backward, the next timestamp advances by 100 ns while preserving any supplied node and clock sequence. This prevents repeats within one process, or one thread under ZTS. You must coordinate node and clock-sequence values across processes, forks, threads, and restarts when you supply fixed values. `fromDateTime()` preserves your explicit timestamp and does not use this monotonic state.
- Live-clock `uuid2()` keeps its own high-water mark on the visible 28-bit timestamp portion (`time_mid` + `time_hi`; `time_low` is the local identifier, so the shared v1/v6 mark would be invisible until a bit-32 carry), but only when you supply both `node` and `clockSeq`. A defaulted node or clock sequence is freshly random per call, so those callers never repeat and their output is unchanged. When the mark applies and the clock stalls or moves backward, the next visible timestamp advances by one unit, which is 2^32 × 100 ns ≈ 429.5 s of embedded time per call: `getDateTime()`/`getTimestampMillis()` read back the advanced time. The 28-bit visible field exhausts after roughly 2.36×10^8 stalled calls from the current epoch, after which `uuid2()` throws `UnsupportedOperationException` ("v2 timestamp exhausted") until the worker exits. As with v1/v6, you must coordinate the local identifier, node, and clock sequence across processes, forks, threads, and restarts when you supply fixed values.
- Live-clock `uuid2()` keeps its own high-water mark on the visible 28-bit timestamp portion (`time_mid` + `time_hi`; `time_low` is the local identifier, so the shared v1/v6 mark would be invisible until a bit-32 carry), but only when you supply both `node` and `clockSeq`. Calls with a defaulted node or clock sequence use fresh randomness instead of this high-water mark, so uniqueness is not guaranteed. With a supplied node and defaulted clock sequence, only six random clock-sequence bits remain after the local domain replaces the low byte; calls with the same local identifier and domain can repeat within one visible timestamp interval. When the mark applies and the clock stalls or moves backward, the next visible timestamp advances by one unit, which is 2^32 × 100 ns ≈ 429.5 s of embedded time per call: `getDateTime()`/`getTimestampMillis()` read back the advanced time. The 28-bit visible field exhausts after roughly 2.36×10^8 stalled calls from the current epoch, after which `uuid2()` throws `UnsupportedOperationException` ("v2 timestamp exhausted") until the worker exits. As with v1/v6, you must coordinate the local identifier, node, and clock sequence across processes, forks, threads, and restarts when you supply fixed values.
- Live-clock UUIDv7 carries sub-millisecond precision (RFC 9562 §6.2 Method 3): `rand_a` encodes the sub-ms fraction. When the millisecond/sub-millisecond time key repeats or moves backward, the counter in `rand_b` advances by a fresh CSPRNG-selected value from `1..2^24` inclusive, carrying into the time key on overflow. Single and batch calls share this monotonic state within a process, or within a thread under ZTS; ties across threads or processes carry no order. Explicit `uuid7($dateTime)` and `uuid7($unixMillis)` calls do not use the monotonic state. `getDateTime()` reads back at millisecond precision, matching `ramsey/uuid`.
- `getVariant()` returns `0` (NCS), `2` (RFC 4122), `6` (Microsoft), `7` (future); `getVersion()` is `null` for nil/max and non-RFC variants.
- `getDateTime()` works for RFC time-based versions (v1, v2, v6, v7) and throws `FastUuid\Exception\UnsupportedOperationException` for non-time-based versions and non-RFC variants.
Expand Down
10 changes: 5 additions & 5 deletions fast_uuid.c
Original file line number Diff line number Diff line change
Expand Up @@ -932,9 +932,9 @@ static zend_result fu_gen_v6(unsigned char *b) { return fu_gen_v6_ex(b, NULL, -1
/* DCE Security (v2): v1 time layout, but time_low := local identifier and
clock_seq_low := local domain; version nibble = 2. The low 32 timestamp bits
are sacrificed for the local id, so v2 time resolution is coarse.
monotonic is true only when the caller supplied both node and clockseq: a
defaulted node or clockseq is freshly random per call, so only the
both-supplied case can repeat on a stalled clock. */
monotonic is true only when the caller supplied both node and clockseq.
Defaulted fields use fresh randomness instead; this does not guarantee
uniqueness (only six clockseq bits survive the local-domain overwrite). */
static zend_result fu_gen_v2(unsigned char *b, uint32_t local_id, unsigned char local_domain,
const unsigned char *node, int clockseq, zend_bool monotonic) {
uint64_t g;
Expand Down Expand Up @@ -1477,8 +1477,8 @@ PHP_METHOD(FastUuid_Uuid, uuid2) {
if (fu_node_arg(node_str, node_long, node_null, node, &np) == FAILURE) RETURN_THROWS();
int cseq; if (fu_clockseq_arg(clockseq, cs_null, &cseq) == FAILURE) RETURN_THROWS();
unsigned char b[16];
/* Only a fully supplied node+clockseq pair can repeat on a stalled clock;
defaulted values are random per call, so the mark would only add drift. */
/* Apply the high-water mark only to a fully supplied node+clockseq pair;
defaulted values retain the randomized path without the mark or its drift. */
zend_bool mono = (!node_null && !cs_null);
if (fu_gen_v2(b, local_id, (unsigned char)local_domain, np, cseq, mono) == FAILURE) RETURN_THROWS();
fu_return_uuid(return_value, b);
Expand Down
Loading