Stamp.Config (stamp v0.1.0)

Copy Markdown View Source

Configuration structure for Stamp. Each stamp is generated and later processed according to the configuration parameters.

Summary

Types

t()

Functions

new(opts \\ [])

Create new Stamp config from options. This function is also used internally to build config at compile time for Ecto IDs. Using this function should be preferred over constructing Stamp.Config structs manually, as it performs validation of the parameters.

Types

t()

@type t() :: %Stamp.Config{
  codec: atom() | nil,
  epoch: pos_integer(),
  node_bits: non_neg_integer(),
  node_fun: fun() | nil,
  partition_bits: non_neg_integer(),
  partition_fun: fun() | nil,
  prefix: String.t() | nil,
  sequence_bits: pos_integer(),
  time_bits: non_neg_integer()
}

Functions

new(opts \\ [])

@spec new(keyword()) :: t()

Create new Stamp config from options. This function is also used internally to build config at compile time for Ecto IDs. Using this function should be preferred over constructing Stamp.Config structs manually, as it performs validation of the parameters.

Supported options:

  • partition_bits - number of bits reserved for partition number. 0 disables partitioning. Default is 0.

  • time_bits - positive number of bits reserved for time. Default is 41.

  • node_bits - number of bits reserved for node number. 0 disables per-node-number sequences, which can be useful if the generator can't ever require more than 1 node. Default is 7.

  • sequence_bits - positive number of bits reserved for sequence. Default is 15.

  • node_fun - 0-arity function returning current node number. The number must be unique across all BEAM nodes, and 1 number per BEAM node is enough (although it's not enforced). All Stamp configurations can share same node number. The number must fit in node_bits without overflow. Required with node_bits > 0. Default is nil (not set).

  • partition_fun - 0-arity function returning current partition. This works as a backchannel with autogenerate: true PK option in Ecto. Current partition for queries can be smuggled in via process dictionary or by other means. When generating IDs directly you can instead pass partition option to Stamp.next_field_id/3 and Stamp.next_id/3. The number must fit in partition_bits without overflow. Required with partition_bits > 0. Default is nil (not set).

  • epoch - the number subtracted from the current unix time in milliseconds to compress it for storage. For permanently stored data the epoch must be chosen once and never changed later. Default is 1784842980000

  • prefix - a Stripe-style prefix to add to encoded IDs. For example, setting it to foo_ will generate IDs that look like so: foo_139546474327455 or foo_ABdsdDggP. If set, the prefix is always added and expected (values without it will trigger an error). Default is nil (disabled).

  • codec - a module implementing Stamp.Codec behaviour. When set, the library will encode the ID after generation/loading, so the final ID will be a string. The encoding must maintain lexicographic order for the IDs to have same sorting in string form. Required when prefix is set. Default is nil (disabled).