# hlc - Hybrid Logical Clock in Erlang. #

Copyright (c) 2014-2015 Benoît Chesneau.

__Version:__ 3.0.0

hlc implements the Hybrid Logical Clock outlined in [Logical Physical Clocks
and Consistent Snapshots in Globally Distributed

> 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.

[![Build Status](](
[![Hex pm](](

## Documentation

Full doc is available in the [`hlc`]( module.

## Example of usage

Create a logical clock using `hlc:new/0`:

1> {ok, C} = hlc:start_link().
Return a timestamp for the current time:

2> Now = hlc:now(C).

> Note: by default it using `erlang:system_time(millisecond)` to get the physical time.

You can update the current clock from the members of the cluster using `hlc:update/2`.

> :heavy_exclamation_mark: A clock is not locked, you need to make sure that only one user can update it at a time
> using the `now/1` or `update/2` functions.

### Comparaison

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

Ex, compare if A is inferior to B:

{MClock, MClockFun} = hlc:manual_clock(),
{ok, C} = hlc:start_link(MClockFun, 0),

A = hlc:timestamp(C),
B = hlc:timestamp(C),

?assert(A =:= B),

hlc:set_manual_clock(MClock, 1),
B1 = hlc:now(C),
true = hlc:less(A, B1).

To test if they are equal use `hlc:ts_equal/2`.

## Performance

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

1> hlc_harness:timed_generate(10000).
generating timestamp: 0.035 s
2> hlc_harness:timed_generate(100000).
generating timestamp: 0.295 s
3> hlc_harness:timed_generate(1000000).
generating timestamp: 2.586 s

## Ownership and License

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

hlc uses the [C4.1 (Collective Code Construction
Contract)]( 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
* and [submit issue reports](
* or feature requests pick a task in
* [issues]( and get it done fork
* the repository and have your own fixes send us pull requests and even
* star this project ^_^

To  run the test suite:

rebar3 eunit

## Modules ##

<table width="100%" border="0" summary="list of modules">
<tr><td><a href="" class="module">hlc</a></td></tr>
<tr><td><a href="" class="module">hlc_harness</a></td></tr></table>