Skip to content

Commit 7bba2f9

Browse files
committed
docs: rephrase generator clock rollback handling
1 parent 1eb3cd7 commit 7bba2f9

File tree

1 file changed

+11
-6
lines changed

1 file changed

+11
-6
lines changed

src/main/java/io/github/scru128/Scru128Generator.java

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
/**
1212
* Represents a SCRU128 ID generator that encapsulates the monotonic counters and other internal states.
1313
* <p>
14-
* The generator offers four different methods to generate a SCRU128 ID:
14+
* The generator comes with four different methods that generate a SCRU128 ID:
1515
* <table border="1">
1616
* <caption>Comparison of generator functions</caption>
1717
* <tr><th>Flavor</th> <th>Timestamp</th><th>Thread-</th><th>On big clock rewind</th></tr>
@@ -21,11 +21,16 @@
2121
* <tr><td>{@link #generateOrAbortCore}</td><td>Argument</td> <td>Unsafe</td> <td>Returns null</td></tr>
2222
* </table>
2323
* <p>
24-
* All of these methods return monotonically increasing IDs unless a timestamp provided is significantly (by default,
25-
* more than ten seconds) smaller than the one embedded in the immediately preceding ID. If such a significant clock
26-
* rollback is detected, the {@code generate} (OrReset) method resets the generator and returns a new ID based on the
27-
* given timestamp, while the {@code OrAbort} variants abort and return null. The {@code Core} functions offer
28-
* low-level thread-unsafe primitives.
24+
* All of the four return a monotonically increasing ID by reusing the previous timestamp even if the one provided is
25+
* smaller than the immediately preceding ID's. However, when such a clock rollback is considered significant (by
26+
* default, more than ten seconds):
27+
* <ol>
28+
* <li>{@code generate} (OrReset) methods reset the generator and return a new ID based on the given timestamp, breaking
29+
* the increasing order of IDs.</li>
30+
* <li>{@code OrAbort} variants abort and return null immediately.</li>
31+
* </ol>
32+
* <p>
33+
* The {@code Core} functions offer low-level thread-unsafe primitives to customize the behavior.
2934
*/
3035
public class Scru128Generator implements Iterable<@NotNull Scru128Id>, Iterator<@NotNull Scru128Id> {
3136
/**

0 commit comments

Comments
 (0)