Skip to content
This repository has been archived by the owner on Jul 9, 2024. It is now read-only.

Commit

Permalink
Merge pull request #113 from uuid6/draft-04-6-7-2022
Browse files Browse the repository at this point in the history 
Draft 04 - 6-7-2022
  • Loading branch information
@kyzer-davis
kyzer-davis authored Jun 7, 2022
2 parents d192e2f + d56820a commit b774ab1
Show file tree
Hide file tree
Showing 4 changed files with 498 additions and 327 deletions.
89 changes: 65 additions & 24 deletions draft-peabody-dispatch-new-uuid-format-04.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@
This document presents new Universally Unique Identifier (UUID) formats for use in modern applications and databases.
" name="description">
<meta content="xml2rfc 3.12.7" name="generator">
<meta content="xml2rfc 3.12.10" name="generator">
<meta content="uuid" name="keyword">
<meta content="draft-peabody-dispatch-new-uuid-format-04" name="ietf.draft">
<!-- Generator version information:
xml2rfc 3.12.7
xml2rfc 3.12.10
Python 3.6.9
appdirs 1.4.4
ConfigArgParse 1.2.3
Expand All @@ -34,7 +34,7 @@
setuptools 40.6.2
six 1.15.0
-->
<link href="/tmp/VQ8rJd9OGR.dir/draft-peabody-dispatch-new-uuid-format-04.xml" rel="alternate" type="application/rfc+xml">
<link href="/tmp/PAJeXu2PYg.dir/draft-peabody-dispatch-new-uuid-format-04.xml" rel="alternate" type="application/rfc+xml">
<link href="#copyright" rel="license">
<style type="text/css">/*

Expand Down Expand Up @@ -175,10 +175,6 @@
}
.alignCenter > *:first-child {
border: none;
/* this isn't optimal, but it's an existence proof. PrinceXML doesn't
support flexbox yet.
*/
display: table;
margin: 0 auto;
}

Expand Down Expand Up @@ -1192,11 +1188,11 @@
<thead><tr>
<td class="left">Internet-Draft</td>
<td class="center">new-uuid-format</td>
<td class="right">May 2022</td>
<td class="right">June 2022</td>
</tr></thead>
<tfoot><tr>
<td class="left">Peabody &amp; Davis</td>
<td class="center">Expires 27 November 2022</td>
<td class="center">Expires 9 December 2022</td>
<td class="right">[Page]</td>
</tr></tfoot>
</table>
Expand All @@ -1212,12 +1208,12 @@
<a href="https://www.rfc-editor.org/rfc/rfc4122" class="eref">4122</a> (if approved)</dd>
<dt class="label-published">Published:</dt>
<dd class="published">
<time datetime="2022-05-26" class="published">26 May 2022</time>
<time datetime="2022-06-07" class="published">7 June 2022</time>
</dd>
<dt class="label-intended-status">Intended Status:</dt>
<dd class="intended-status">Standards Track</dd>
<dt class="label-expires">Expires:</dt>
<dd class="expires"><time datetime="2022-11-27">27 November 2022</time></dd>
<dd class="expires"><time datetime="2022-12-09">9 December 2022</time></dd>
<dt class="label-authors">Authors:</dt>
<dd class="authors">
<div class="author">
Expand Down Expand Up @@ -1254,7 +1250,7 @@ <h2 id="name-status-of-this-memo">
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."<a href="#section-boilerplate.1-3" class="pilcrow"></a></p>
<p id="section-boilerplate.1-4">
This Internet-Draft will expire on 27 November 2022.<a href="#section-boilerplate.1-4" class="pilcrow"></a></p>
This Internet-Draft will expire on 9 December 2022.<a href="#section-boilerplate.1-4" class="pilcrow"></a></p>
</section>
</div>
<div id="copyright">
Expand Down Expand Up @@ -1605,7 +1601,7 @@ <h3 id="name-changelog">
<p id="section-3.1-3.2.1">- Fixed bad GMT offset in Test Vector Appendix<a href="#section-3.1-3.2.1" class="pilcrow"></a></p>
</li>
<li class="compact ulEmpty" id="section-3.1-3.3">
<p id="section-3.1-3.3.1">- Changed some MAY to SHOULD in Counters section<a href="#section-3.1-3.3.1" class="pilcrow"></a></p>
<p id="section-3.1-3.3.1">- Removed MAY in Counters section<a href="#section-3.1-3.3.1" class="pilcrow"></a></p>
</li>
<li class="compact ulEmpty" id="section-3.1-3.4">
<p id="section-3.1-3.4.1">- Condensed Counter Type into Counter Methods to reduce text<a href="#section-3.1-3.4.1" class="pilcrow"></a></p>
Expand All @@ -1618,6 +1614,9 @@ <h3 id="name-changelog">
</li>
<li class="compact ulEmpty" id="section-3.1-3.7">
<p id="section-3.1-3.7.1">- Allow timestamp increment if counter overflows<a href="#section-3.1-3.7.1" class="pilcrow"></a></p>
</li>
<li class="compact ulEmpty" id="section-3.1-3.8">
<p id="section-3.1-3.8.1">- Replaced UUIDv8 C code snippet with full generation example<a href="#section-3.1-3.8.1" class="pilcrow"></a></p>
</li>
</ul>
<p id="section-3.1-4">draft-03<a href="#section-3.1-4" class="pilcrow"></a></p>
Expand Down Expand Up @@ -2153,7 +2152,7 @@ <h3 id="name-monotonicity-and-counters">
<span class="break"></span><dl class="dlNewline" id="section-6.2-9">
<dt id="section-6.2-9.1">Counter Rollover Guards:</dt>
<dd style="margin-left: 1.5em" id="section-6.2-9.2">
The technique from Fixed-Length Dedicated Counter Seeding which describes allocating a segment of the fixed-length counter as a rollover guard is also recommended and SHOULD be employed to help mitigate counter rollover issues.
The technique from Fixed-Length Dedicated Counter Seeding which describes allocating a segment of the fixed-length counter as a rollover guard is also helpful to mitigate counter rollover issues.
This same technique can be leveraged with Monotonic random counter methods by ensuring the total length of a possible increment in the least significant, right most position is less than the total length of the random being incremented.
As such the most significant, left-most, bits can be incremented as rollover guarding.<a href="#section-6.2-9.2" class="pilcrow"></a>
</dd>
Expand Down Expand Up @@ -2570,23 +2569,65 @@ <h3 id="name-creating-a-uuidv7-value">
<h3 id="name-creating-a-uuidv8-value">
<a href="#appendix-A.3" class="section-number selfRef">A.3. </a><a href="#name-creating-a-uuidv8-value" class="section-name selfRef">Creating a UUIDv8 Value</a>
</h3>
<p id="appendix-A.3-1">UUIDv8 will vary greatly from implementation to implementation. A good candidate use case for UUIDv8 is to embed exotic timestamps like the one found in this example which employs approximately 0.25 milliseconds and approximately 5 microseconds per timestamp tick as a 48 bit value.<a href="#appendix-A.3-1" class="pilcrow"></a></p>
<p id="appendix-A.3-1">UUIDv8 will vary greatly from implementation to implementation.<a href="#appendix-A.3-1" class="pilcrow"></a></p>
<p id="appendix-A.3-2">The following example utilizes:<a href="#appendix-A.3-2" class="pilcrow"></a></p>
<ul class="normal">
<li class="normal" id="appendix-A.3-3.1">
<p id="appendix-A.3-3.1.1">32 bit custom-epoch timestamp (seconds elapsed since 2020-01-01 00:00:00 UTC)<a href="#appendix-A.3-3.1.1" class="pilcrow"></a></p>
</li>
<li class="normal" id="appendix-A.3-3.2">
<p id="appendix-A.3-3.2.1">16 bit exotic resolution (~15 microsecond) subsecond timestamp encoded using the fractional representation<a href="#appendix-A.3-3.2.1" class="pilcrow"></a></p>
</li>
<li class="normal" id="appendix-A.3-3.3">
<p id="appendix-A.3-3.3.1">58 bit random number<a href="#appendix-A.3-3.3.1" class="pilcrow"></a></p>
</li>
<li class="normal" id="appendix-A.3-3.4">
<p id="appendix-A.3-3.4.1">8 bit application-specific unique node ID<a href="#appendix-A.3-3.4.1" class="pilcrow"></a></p>
</li>
<li class="normal" id="appendix-A.3-3.5">
<p id="appendix-A.3-3.5.1">8 bit rolling sequence number<a href="#appendix-A.3-3.5.1" class="pilcrow"></a></p>
</li>
</ul>
<span id="name-uuidv8-function-in-c"></span><figure id="figure-8">
<div class="alignLeft art-text artwork" id="appendix-A.3-2.1">
<div class="alignLeft art-text artwork" id="appendix-A.3-4.1">
<pre>
#include &lt;stdint.h&gt;
#include &lt;stdio.h&gt;
#include &lt;time.h&gt;

int main() {
struct timespec tp;
clock_gettime(CLOCK_REALTIME, &amp;tp);
uint64_t timestamp = (uint64_t)tp.tv_sec &lt;&lt; 12;
int get_random_bytes(uint8_t *buffer, int count) {
// ...
}

// compute 12 bit (~0.25 msec precision) fraction from nsecs
timestamp |= ((uint64_t)tp.tv_nsec &lt;&lt; 12) / 1000000000;
int generate_uuidv8(uint8_t *uuid, uint8_t node_id) {
struct timespec tp;
if (clock_gettime(CLOCK_REALTIME, &amp;tp) != 0)
return -1; // real-time clock error

// 32 bit biased timestamp (seconds elapsed since 2020-01-01 00:00:00 UTC)
uint32_t timestamp_sec = tp.tv_sec - 1577836800;
uuid[0] = timestamp_sec &gt;&gt; 24;
uuid[1] = timestamp_sec &gt;&gt; 16;
uuid[2] = timestamp_sec &gt;&gt; 8;
uuid[3] = timestamp_sec;

// 16 bit subsecond fraction (~15 microsecond resolution)
uint16_t timestamp_subsec = ((uint64_t)tp.tv_nsec &lt;&lt; 16) / 1000000000;
uuid[4] = timestamp_subsec &gt;&gt; 8;
uuid[5] = timestamp_subsec;

// 58 bit random number and required ver and var fields
if (get_random_bytes(&amp;uuid[6], 8) != 0)
return -1; // random number generator error
uuid[6] = 0x80 | (uuid[6] &amp; 0x0f);
uuid[8] = 0x80 | (uuid[8] &amp; 0x3f);

// 8 bit application-specific node ID to guarantee application-wide uniqueness
uuid[14] = node_id;

// 8 bit rolling sequence number to help ensure process-wide uniqueness
static uint8_t sequence = 0;
uuid[15] = sequence++; // NOTE: unprotected from race conditions

printf("%08llx-%04llx\n", timestamp &gt;&gt; 16, timestamp &amp; 0xFFFF);
return 0;
}
</pre>
Expand Down
Loading

0 comments on commit b774ab1

Please sign in to comment.