Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add microsecond provider #476

Merged
merged 1 commit into from
Sep 15, 2020
Merged

Add microsecond provider #476

merged 1 commit into from
Sep 15, 2020

Conversation

ahawker
Copy link
Owner

@ahawker ahawker commented Aug 30, 2020

The microsecond provider uses more precise clock resolution to
create randomness values that should monotonically increase on
timestamp (millisecond) collision.

When creating a new ULID, we extract the number of microseconds from
our timestamp and use them as the first two bytes of the randomness value.

Caveats:

When using ulid.from_timestamp, we fallback to the default implementation
of 10 bytes of pure randomness. The reason for this, is that the timestamp
that is being passed in by the caller is in milliseconds. Since we don't have
a more accurate timestamp to "steal" bytes from, there's not much we can do. We
cannot make a new epoch timestamp as the microsecond remainder is only accurate
when working within the same millisecond.

Status: Ready

If merged, this adds a microsecond implementation as discussed in #306 .

TODO:

  • Add tests for microsecond provider
  • Add tests for microsecond api
  • Add tests for new provider method

Usage:

>>> from ulid import microsecond as ulid
>>> ulid.new()
<ULID('01EH0VVVEC0BKJHF0370TNGQ4Z')>
>>> ulid.new()
<ULID('01EH0VVWPG0C6VDD0529CAHPNJ')>
>>> ulid.new()
<ULID('01EH0VVX8R0AN45DBYZZYMXVKT')>
>>> ulid.new()
<ULID('01EH0VVYA406BDKKRVCDJQZHYQ')>

@ahawker ahawker mentioned this pull request Aug 30, 2020
@ahawker ahawker force-pushed the feature/microsecond-support branch 2 times, most recently from e1ce063 to 8ca6019 Compare August 30, 2020 23:48
@ahawker ahawker changed the title WIP: Add microsecond provider Add microsecond provider Aug 30, 2020
@ahawker ahawker force-pushed the feature/microsecond-support branch from 8ca6019 to 71b23d3 Compare August 31, 2020 00:02
@codecov
Copy link

codecov bot commented Aug 31, 2020

Codecov Report

Merging #476 into master will not change coverage.
The diff coverage is 100.00%.

Impacted file tree graph

@@            Coverage Diff            @@
##            master      #476   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           17        19    +2     
  Lines          498       547   +49     
  Branches        80        80           
=========================================
+ Hits           498       547   +49     
Impacted Files Coverage Δ
ulid/api/default.py 100.00% <ø> (ø)
ulid/api/monotonic.py 100.00% <ø> (ø)
ulid/api/api.py 100.00% <100.00%> (ø)
ulid/api/microsecond.py 100.00% <100.00%> (ø)
ulid/providers/__init__.py 100.00% <100.00%> (ø)
ulid/providers/base.py 100.00% <100.00%> (ø)
ulid/providers/microsecond.py 100.00% <100.00%> (ø)

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b85fda2...c111067. Read the comment docs.

The microsecond provider uses more precise clock resolution to
create randomness values that should monotonically increase on
timestamp (millisecond) collision.

When creating a new ULID, we extract the number of microseconds from
our timestamp and use them as the first two bytes of the randomness value.

Caveats:

When using `ulid.from_timestamp`, we fallback to the default implementation
of 10 bytes of pure randomness. The reason for this, is that the timestamp
that is being passed in by the caller is in milliseconds. Since we don't have
a more accurate timestamp to "steal" bytes from, there's not much we can do. We
cannot make a new epoch timestamp as the microsecond remainder is only accurate
when working within the same millisecond.
@ahawker ahawker merged commit c111067 into master Sep 15, 2020
@personal-probot personal-probot bot deleted the feature/microsecond-support branch September 15, 2020 01:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants