Page MenuHomePhorge
Files F112350

No OneTemporary
Actions

Size
5 KB
Referenced Files
None
Subscribers
None

View Options

diff --git a/README.md b/README.md
index e2dc261..d6ac6aa 100644
--- a/README.md
+++ b/README.md
@@ -1,104 +1,107 @@
# ❄ FlakeId
> Decentralized, k-ordered ID generation service
Flake Ids are 128-bit identifiers, sortable by time, and can be generated safely from a multi-node system without
coordination.
-It consists of a 64 bit timestamp, 48 bit worker identifier, and 16 bit sequence. They are usually
-represented as a Base 62 string; and can be sorted either by bit or by their string representation.
+Flake Ids consist of a 64 bit timestamp, 48 bit worker identifier, and 16 bit sequence. They are usually
+represented as a Base 62 string and can be sorted either by bit or by their string representation.
The sort precision is limited to a millisecond, which is probably fine enough for most usages.
## Installation
Add `flake_id` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:flake_id, "~> 0.1.0"}
]
end
```
## Configuration
### Worker ID
-The worker ID is a very important part of a flake. It is what guarantees that individual node part of the same system
-can generate IDs without risks of collision, so be sure of picking ones that are guaranteed to be unique for your
-system.
+The Worker ID is a very important part of a flake. It guarantees that individual nodes within the same system
+can generate IDs without risks of collision. Take care to choose Worker IDs that are guaranteed to be unique
+for your system.
-You have multiple strategies available, depending on your setup:
+You have multiple strategies available depending on your setup:
* random byte-string, generated at node boot
* erlang node name
* mac address (either random, or manually specified)
* fixed string or integer
-It is configured as `:worker` in the `:flake_id` app environement, and is picked up at boot time.
+It is configured as `:worker` in the `:flake_id` app environement and is picked up at boot time.
Worker: `:mac | {:mac, iface} | :node | :random | String.t | Integer.t`
-### Persisted Time hint
+### Persisted Time Hint
-Flake's time is dependent on your OS system clock. At runtime, Flake will refuse to generate IDs if the time went
-backwards. However, in some cases, after a system reboot, your system clock may be backwards than the last time Flake
-ran.
+Flake's time is dependent on your OS system clock. At runtime Flake will refuse to generate IDs if the system clock goes
+backwards. In some cases after an OS reboot the clock may be incorrectly set to a time in the past which will trigger
+this condition. Enabling a time hint file will prevent this by refusing to start the Flake worker.
-Enabling a time hint file will prevent this by refusing to start the Flake worker if current time is backwards than the
-last run time.
-
-This configured as `:time_hint` in `:flake_id` app environement. By default, it is disabled (`false`). Possible values
-are `true` in which case the time hint file will be stored in flake_id priv dir, or can be set to a string pointing to a
-file.
+Persisted Time hint is configured as `:time_hint` in the `:flake_id` app environement. By default it is disabled (`false`).
+Other accepted values are `true` which stores the time hint file in flake_id priv dir or it can be set to a string pointing
+to a file.
## Usage
-For most uses, just use `get/0`:
+### get/0
+
+The most common usage will be via `get/0`:
```elixir
iex> FlakeId.get()
"9n3171dJZpdD77K3DU"
```
-In complement, you can also generate flakes in-process, without hitting a node-wide worker. This is especially useful
-when you have long-running processes that does a lot of insertions/ID generation. The first call will be slower than the
-subsequent ones, as it have to set-up the Flake state.
+In addition you can also generate flakes in-process without hitting a node-wide worker. This is especially useful
+when you have long-running processes that do a lot of insertions/ID generation. Note that the first call will be slowest as
+it has to setup the Flake state.
-Each process would have its Flake state stored in the process dictionary, and the worker-id is derived from the global
-worker id and the current PID:
+### get_local/0
+
+Each process can have its Flake state stored in the process dictionary and the Worker ID is derived from the global
+Worker ID and the current PID:
```elixir
iex> FlakeId.get_local()
```
-If you wish to insert historical data while preservering sorting, you can achieve this using a backdated flake. In that
-case, you have to provide yourself a UNIQUE worker-id (for the given time). Be very careful at the unique value being
-really unique, otherwise you may generate the same flake twice.
+### backdate/2
+
+If you wish to insert historical data while preserving sorting, you can achieve this using a backdated flake. In that
+case you have to provide yourself a **UNIQUE** Worker ID (for the given time). Be very careful to ensure the uniqueness
+of the Worker ID otherwise you may generate the same flake twice.
```elixir
iex> FlakeId.backdate("https://flakesocial.com/status/390929393992", ~U[2019-12-05 07:15:00.793018Z])
""
```
See [https://hexdocs.pm/flake_id](https://hexdocs.pm/flake_id) for the complete documentation.
### With Ecto
It is possible to use `FlakeId` with [`Ecto`](https://github.com/elixir-ecto/ecto/).
See [`FlakeId.Ecto.Type`](https://hexdocs.pm/flake_id/FlakeId.Ecto.Type.html) documentation for detailed instructions.
If you wish to migrate from integer serial ids to Flake, see [`FlakeId.Ecto.CompatType`](https://hexdocs.pm/flake_id/FlakeId.Ecto.Type.html) for instructions.
## Prior Art
* [flaky](https://github.com/nirvana/flaky), released under the terms of the Truly Free License,
* [Flake](https://github.com/boundary/flake), Copyright 2012, Boundary, Apache License, Version 2.0
## Copyright and License
-Copyright © 2017-2019 [Pleroma Authors](https://pleroma.social/)
+Copyright © 2017-2020 [Pleroma Authors](https://pleroma.social/)
FlakeId source code is licensed under the GNU LGPLv3 License.

File Metadata

Mime Type
text/x-diff
Expires
Sat, Nov 23, 9:42 AM (20 h, 31 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
38938
Default Alt Text
(5 KB)

Event Timeline