document uuid functions

[stevengj]

Base.Random defines a UUID type and a uuid4() function to generate random UUIDs (see also #12506) corresponding to RFC 4122, but they don't seem to be documented. Probably we should document them.

• They are already used in several packages (IJulia, Bokeh, Escher, Jewel, and ProfileView)
• There is a redundant external package for this (Merge with Base? JuliaAttic/UUID.jl#13)
• Time-based "UUIDs" are employed in the core Julia to timestamp modules (

  julia/src/module.c

  Line 32 in dcc448b

  m->uuid = uv_now(uv_default_loop());

  ); we should maybe use a proper UUID algorithm for this.

[JeffBezanson]

The UUID.jl package seems to be more thorough. It's not that much code, so if we're going to use UUIDs in Base then we should probably move the package into Base and replace Base.uuid4.

[StefanKarpinski]

Packages will also need UUIDs in order to make renaming them work smoothly.

[stevengj]

The UUID.jl package is certainly more verbose. The implementation of uuid4 in base seems far cleaner, though (assuming it is correct), and makes me think that uuid1 could be cleaned up similarly.

[WestleyArgentum]

Huh, Base.uuid4 is definitely a lot cleaner... is it to spec though? Think it's RFC 4122... if no one is quite sure I could probably find some time this weekend to read through it and port UUID.jl into base

[wildart]

Please, put UUID.jl functionality into Base.

[StefanKarpinski]

Relevant portion of the spec:

https://tools.ietf.org/html/rfc4122#section-4.4

I think it's correct but could probably use a double check.

[WestleyArgentum]

Yep, double checked, pretty cool. Seems like v1 is going to be a little more complicated, but I'll see if I can implement that and some of the conversions and things we have in UUID.jl

[stevengj]

v1 doesn't seem too bad, something like:

function uuid1(rng::AbstractRNG=Base.Random.GLOBAL_RNG)
    timestamp = (UInt64(now() - DateTime(1582,10,15))*10) | 0x1000000000000000
    clocksequence = rand(rng, UInt16) & 0x3fff
    node_id = (rand(rng, UInt64) & 0x0000ffffffffffff) | 0x0000010000000000
    return Base.Random.UUID(#= ...combine as specified in 4.1.2... =#)
end

It looks like it can be way shorter than in UUID.jl.

[stevengj]

Or rather, now(Dates.UTC).

[WestleyArgentum]

Lol, sorry, stepped out to dinner. Will check when back but that looks just
about right. The one thing I'd say is that we should accept a clock seq,
default it, and call random. And I remember seeing the python
implementation saved a global last timestamp that it would increment if u
got the same value because u were running fast or something

On Sun, Aug 9, 2015, 19:29 Steven G. Johnson notifications@github.com
wrote:

Or rather, now(Dates.UTC).

—
Reply to this email directly or view it on GitHub
#12507 (comment).

[stevengj]

Better, yet, generate rand(rng, UInt128) as in uuid4() and then mask out the bits for the timestamp, version, etc., to be or-ed in.

[stevengj]

@WestleyArgentum, my understanding was that the whole point of the random "clock sequence" was to handle the case of repeated timestamps, so I don't think a global is necessary.

Why allow the clock-sequence as a parameter? Unless the user is keeping track of the time stamps etcetera they can't really set this sensibly, can they? And if they are tracking those things they may just want to implement their own UUID1 algorithm

[WestleyArgentum]

Re: clock sequence, looks like it's intended as a potential optimization
(if u know the previous then all u have to do is inc), but if we wrote the
algorithm to first generate a 128bit random number and masked things then
there's no additional overhead, so we could omit it. Then the only time u
might want it is if you're using it to keep track of ids or something, but
that seems extremely unlikely.

On Sun, Aug 9, 2015, 19:36 Steven G. Johnson notifications@github.com
wrote:

@WestleyArgentum https://github.com/WestleyArgentum, my understanding
was that the whole point of the random "clock sequence" was to handle the
case of repeated timestamps, so I don't think a global is necessary.

—
Reply to this email directly or view it on GitHub
#12507 (comment).

[WestleyArgentum]

I don't think this is quite right yet, but this is what I'm thinking:

function uuid1(rng::AbstractRNG=Base.Random.GLOBAL_RNG)
    u = rand(rng, Uint128)

    # mask off clock sequence and node
    u &= 0x00000000000000003fffffffffffffff

    # set the unicast/multicast bit
    u |= 0x00000000000000000000010000000000

    # 0x01b21dd213814000 is the number of milliseconds between
    # the UUID epoch and Unix epoch
    timestamp = round(Uint64, time() * 1e7) + 0x01b21dd213814000
    ts_low = timestamp & typemax(Uint32)
    ts_mid = (timestamp >> 32) & typemax(Uint16)
    ts_hi_and_ver = (timestamp >> 48) & 0x0fff

    u |= convert(Uint128, ts_low) << 96
    u |= convert(Uint128, ts_mid) << 80
    u |= convert(Uint128, ts_hi_and_ver) << 64

    Base.Random.UUID(u)
end

@stevengj I like how clean your timestamp calculation is, but I didn't quite understand why you were bitwise or-ing with 0x1000000000000000 and I wasn't sure about the resolution of now(Dates.UTC). Am I being dumb?