github.com/bingoohuang/gg@v0.0.0-20240325092523-45da7dee9335/pkg/snow/README.md (about)

     1  # snowflake
     2  
     3  snowflake is a [Go](https://golang.org/) package that provides
     4  
     5  * A very simple Twitter snowflake generator.
     6  * Methods to parse existing snowflake IDs.
     7  * Methods to convert a snowflake ID into several other data types and back.
     8  * JSON Marshal/Unmarshal functions to easily use snowflake IDs within a JSON API.
     9  * Monotonic Clock calculations protect from clock drift.
    10  * Default nodeID is set to main last part of IPv4 (on en0/eth0 interface), eg. nodeID = 3 when IP is 192.168.1.3
    11  
    12  **For help with this package or general Go discussion, please join the [Discord Gophers](https://discord.gg/0f1SbxBZjYq9jLBk) chat server.**
    13  
    14  ## Status
    15  
    16  This package should be considered stable and completed.  Any additions in the
    17  future will strongly avoid API changes to existing functions.
    18  
    19  ### ID Format
    20  
    21  By default, the ID format follows the original Twitter snowflake format.
    22  
    23  * The ID as a whole is a 63 bit integer stored in an int64
    24  * 41 bits used to store a timestamp with millisecond precision, using a custom epoch.
    25  * 10 bits used to store a node id - a range from 0 through 1023.
    26  * 12 bits used to store a sequence number - a range from 0 through 4095.
    27  
    28  ### Custom Format
    29  
    30  You can alter the number of bits used for the node id and step number (sequence)
    31  by setting the snowflake.NodeBits and snowflake.StepBits values.  Remember that
    32  There is a maximum of 22 bits available that can be shared between these two
    33  values. You do not have to use all 22 bits.
    34  
    35  ### Custom Epoch
    36  
    37  By default this package uses the Twitter Epoch of 1288834974657 or Nov 04 2010 01:42:54.
    38  You can set your own epoch value by setting snowflake.Epoch to a time in milliseconds
    39  to use as the epoch.
    40  
    41  ### Custom Notes
    42  
    43  When setting custom epoch or bit values you need to set them prior to calling
    44  any functions on the snowflake package, including NewNode().  Otherwise the
    45  custom values you set will not be applied correctly.
    46  
    47  ### How it Works.
    48  
    49  Each time you Next an ID, it works, like this.
    50  
    51  * A timestamp with millisecond precision is stored using 41 bits of the ID.
    52  * Then the NodeID is added in subsequent bits.
    53  * Then the Sequence Number is added, starting at 0 and incrementing for each ID generated in the same millisecond. If you Next enough IDs in the same millisecond that the sequence would roll over or overfill then the Next function will pause until the next millisecond.
    54  
    55  The default Twitter format shown below.
    56  
    57  ```
    58  +--------------------------------------------------------------------------+
    59  | 1 Bit Unused | 41 Bit Timestamp |  10 Bit NodeID  |   12 Bit Sequence ID |
    60  +--------------------------------------------------------------------------+
    61  ```
    62  
    63  Using the default settings, this allows for 4096 unique IDs to be generated every millisecond, per Node ID.
    64  
    65  ## Getting Started
    66  
    67  ### Installing
    68  
    69  This assumes you already have a working Go environment, if not please see
    70  [this page](https://golang.org/doc/install) first.
    71  
    72  ```sh
    73  go get github.com/bingoohuang/snow
    74  ```
    75  
    76  ### Usage
    77  
    78  Import the package into your project then construct a new snowflake Node using a
    79  unique node number. The default settings permit a node number range from 0 to 1023.
    80  If you have set a custom NodeBits value, you will need to calculate what your
    81  node number range will be. With the node object call the Next() method to
    82  Next and return a unique snowflake ID.
    83  
    84  Keep in mind that each node you create must have a unique node number, even
    85  across multiple servers.  If you do not keep node numbers unique the generator
    86  cannot guarantee unique IDs across all nodes.
    87  
    88  ### Example Program
    89  
    90  #### Use default Snowflake Node
    91  
    92  ```go
    93  // Next return a new generated snowflake ID by the Global snow.DefaultNode
    94  // with the 10-bits node ID which get the last 8-bits from host IP v4.
    95  id := snow.Next()
    96  
    97  // Print out the ID in a few different ways.
    98  fmt.Printf("Int64  ID: %d\n", id)
    99  fmt.Printf("String ID: %s\n", id)
   100  ```
   101  
   102  #### Use customized Snowflake Node
   103  
   104  ```go
   105  // Create a new Node with a Node number of 1
   106  node, err := snow.NewNode(snow.WithNodeID(1))
   107  if err != nil {
   108      fmt.Println(err)
   109      return
   110  }
   111  
   112  // Next return a new generated snowflake ID.
   113  id := node.Next()
   114  
   115  // Print out the ID in a few different ways.
   116  fmt.Printf("Int64  ID: %d\n", id)
   117  fmt.Printf("String ID: %s\n", id)
   118  fmt.Printf("Base2  ID: %s\n", id.Base2())
   119  fmt.Printf("Base64 ID: %s\n", id.Base64())
   120  fmt.Printf("ID       : %d\n", node.Next().Int64())
   121  ```
   122  
   123  ### Performance
   124  
   125  With default settings, this snowflake generator should be sufficiently fast
   126  enough on most systems to Next 4096 unique ID's per millisecond. This is
   127  the maximum that the snowflake ID format supports. That is, around 243-244
   128  nanoseconds per operation.
   129  
   130  Since the snowflake generator is single threaded the primary limitation will be
   131  the maximum speed of a single processor on your system.
   132  
   133  To benchmark the generator on your system run the following command inside the
   134  snowflake package directory.
   135  
   136  ```sh
   137  go test -run=^$ -bench=.
   138  ```