README.md 3.12 KB
Newer Older
benoît chesneau's avatar
benoît chesneau committed
1
2
3
4


# hlc - Hybrid Logical Clock in Erlang. #

benoît chesneau's avatar
benoît chesneau committed
5
Copyright (c) 2014-2015 Benoît Chesneau.
benoît chesneau's avatar
benoît chesneau committed
6

benoît chesneau's avatar
benoît chesneau committed
7
__Version:__ 3.0.1
benoît chesneau's avatar
benoît chesneau committed
8
9
10

hlc implements the Hybrid Logical Clock outlined in [Logical Physical Clocks
and Consistent Snapshots in Globally Distributed
benoît chesneau's avatar
benoît chesneau committed
11
Databases](http://www.cse.buffalo.edu/tech-reports/2014-04.pdf).
benoît chesneau's avatar
benoît chesneau committed
12

13
14
15
16
17
> Note: you can use it to have timestamps that are are a combination of both a
> physical and a logical component to support monotonic increments without
> degenerate cases causing timestamps to diverge from wall clock time. It's
> usefull to distribute transactions or such things.

benoît chesneau's avatar
benoît chesneau committed
18
[![Build Status](https://gitlab.com/barrel-db/hlc/badges/master/build.svg)](https://gitlab.com/barrel-db/hlc/commits/master)
benoît chesneau's avatar
benoît chesneau committed
19
20
[![Hex pm](http://img.shields.io/hexpm/v/hlc.svg?style=flat)](https://hex.pm/packages/hlc)

benoît chesneau's avatar
benoît chesneau committed
21
22
## Documentation

benoît chesneau's avatar
benoît chesneau committed
23
Full doc is available in the [`hlc`](http://gitlab.com/barrel-db/hlc/blob/master/doc/hlc.md) module.
benoît chesneau's avatar
benoît chesneau committed
24

benoît chesneau's avatar
benoît chesneau committed
25
26
## Example of usage

Bikram Chatterjee's avatar
Typo    
Bikram Chatterjee committed
27
Create a logical clock using `hlc:new/0`:
benoît chesneau's avatar
benoît chesneau committed
28
29

```
benoît chesneau's avatar
benoît chesneau committed
30
31
1> {ok, C} = hlc:start_link().
{ok,<0.158.0>}
benoît chesneau's avatar
benoît chesneau committed
32
```
benoît chesneau's avatar
benoît chesneau committed
33
Return a timestamp for the current time:
benoît chesneau's avatar
benoît chesneau committed
34

benoît chesneau's avatar
benoît chesneau committed
35
36
37
38
39
40
```
2> Now = hlc:now(C).
{timestamp,1511564016030,0}
```

> Note: by default it using `erlang:system_time(millisecond)` to get the physical time.
benoît chesneau's avatar
benoît chesneau committed
41

42
You can update the current clock from the members of the cluster using `hlc:update/2`.
benoît chesneau's avatar
benoît chesneau committed
43

benoît chesneau's avatar
fix doc    
benoît chesneau committed
44
> :heavy_exclamation_mark: A clock is not locked, you need to make sure that only one user can update it at a time
benoît chesneau's avatar
benoît chesneau committed
45
> using the `now/1` or `update/2` functions.
46

benoît chesneau's avatar
benoît chesneau committed
47
48
49
50
51
52
53
### Comparaison

Compare 2 clocks using `hlc:ts_less/2` or `hlc:ts_equal/2`:

Ex, compare if A is inferior to B:

```
Bikram Chatterjee's avatar
Typo    
Bikram Chatterjee committed
54
{MClock, MClockFun} = hlc:manual_clock(),
benoît chesneau's avatar
benoît chesneau committed
55
{ok, C} = hlc:start_link(MClockFun, 0),
benoît chesneau's avatar
benoît chesneau committed
56

Bikram Chatterjee's avatar
Typo    
Bikram Chatterjee committed
57
58
A = hlc:timestamp(C),
B = hlc:timestamp(C),
benoît chesneau's avatar
benoît chesneau committed
59
60
61

?assert(A =:= B),

Bikram Chatterjee's avatar
Typo    
Bikram Chatterjee committed
62
hlc:set_manual_clock(MClock, 1),
benoît chesneau's avatar
benoît chesneau committed
63
B1 = hlc:now(C),
64
true = hlc:less(A, B1).
benoît chesneau's avatar
fix doc    
benoît chesneau committed
65
66
```

benoît chesneau's avatar
benoît chesneau committed
67
To test if they are equal use `hlc:ts_equal/2`.
benoît chesneau's avatar
fix doc    
benoît chesneau committed
68

benoît chesneau's avatar
benoît chesneau committed
69
70
71
72
## Performance

You can check the performance using the module `hlc_harness`:

benoît chesneau's avatar
benoît chesneau committed
73
74
```
1> hlc_harness:timed_generate(10000).
benoît chesneau's avatar
benoît chesneau committed
75
76
generating timestamp: 0.035 s
...
benoît chesneau's avatar
benoît chesneau committed
77
2> hlc_harness:timed_generate(100000).
benoît chesneau's avatar
benoît chesneau committed
78
79
generating timestamp: 0.295 s
...
benoît chesneau's avatar
benoît chesneau committed
80
81
82
3> hlc_harness:timed_generate(1000000).
generating timestamp: 2.586 s
```
benoît chesneau's avatar
benoît chesneau committed
83

benoît chesneau's avatar
benoît chesneau committed
84
85
86
87
88
## Ownership and License

The contributors are listed in AUTHORS. This project uses the MPL v2
license, see LICENSE.

benoît chesneau's avatar
fix doc    
benoît chesneau committed
89
hlc uses the [C4.1 (Collective Code Construction
benoît chesneau's avatar
benoît chesneau committed
90
91
92
93
94
95
96
Contract)](http://rfc.zeromq.org/spec:22) process for contributions.

## Development

Under C4.1 process, you are more than welcome to help us by:

* join the discussion over anything from design to code style try out
benoît chesneau's avatar
fix doc    
benoît chesneau committed
97
* and [submit issue reports](https://github.com/refuge/hlc/issues/new)
benoît chesneau's avatar
benoît chesneau committed
98
* or feature requests pick a task in
benoît chesneau's avatar
fix doc    
benoît chesneau committed
99
* [issues](https://github.com/refuge/hlc/issues) and get it done fork
benoît chesneau's avatar
benoît chesneau committed
100
101
102
103
104
105
* the repository and have your own fixes send us pull requests and even
* star this project ^_^

To  run the test suite:

```
benoît chesneau's avatar
benoît chesneau committed
106
rebar3 eunit
benoît chesneau's avatar
fix doc    
benoît chesneau committed
107
108
```

benoît chesneau's avatar
benoît chesneau committed
109
110
111
112
113
114


## Modules ##


<table width="100%" border="0" summary="list of modules">
benoît chesneau's avatar
benoît chesneau committed
115
116
<tr><td><a href="http://gitlab.com/barrel-db/hlc/blob/master/doc/hlc.md" class="module">hlc</a></td></tr>
<tr><td><a href="http://gitlab.com/barrel-db/hlc/blob/master/doc/hlc_harness.md" class="module">hlc_harness</a></td></tr></table>
benoît chesneau's avatar
benoît chesneau committed
117