fluo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Keith Turner <ke...@deenlo.com>
Subject Re: Oracle Server Javadoc
Date Fri, 22 Dec 2017 14:39:35 GMT
The wording could definitely be improved.  Maybe something like "The
Oracle provides logical timestamps from a strictly increasing set and
never provides the same element from the set twice".   If you wanted
to define

Seeing your comment about strictly increasing functions made me wonder
if the oracle client getStamp() function has good docs.  I looked at
it and it does not. It could use an improvement.  Specifically it
would be nice it defined how calls to the function relate to previous
calls.

https://github.com/apache/fluo/blob/master/modules/core/src/main/java/org/apache/fluo/core/oracle/OracleClient.java#L355

On Fri, Dec 22, 2017 at 1:35 AM, Kenneth Mcfarland
<kennethpaulmcfarland@gmail.com> wrote:
> Here is what the oracle server says right now as from OracleServer.java:
>
> /**
>  * Oracle server is the responsible for providing incrementing logical
> timestamps to clients. It
>  * should never give the same timestamp to two clients and it should always
> provide an incrementing
>  * timestamp.
>  *
>  * <p>
>  * If multiple oracle servers are run, they will choose a leader and
> clients will automatically
>  * connect to that leader. If the leader goes down, the client will
> automatically fail over to the
>  * next leader. In the case where an oracle fails over, the next oracle
> will begin a new block of
>  * timestamps.
>  */
>
> I'd like to add some information to the first paragraph, and this might be
> useful just because.
> The conditions in the first paragraph create what is known as a strict
> ordering [1].
> There are 3 conditions for a strict ordering on a set, let S be a set:
>
> 1) irreflexive:  a < a is false for all a the timestamp gives out, TFAE: a
> is unique, and a != a for any a in S
>
> 2) antisymmetric: if a < b then ! b < a, for all a,b in S. This is pretty
> obvious but fundamental.
>
> 3) transitive: a < b and b < c then a < c, for all a,b,c in S. Again this
> is intuitive. Note by 1 that a != b and b !=c (and to be silly a != c is
> obvious), there must be three unique time stamps.
>
> Another equivalent definition is 'strictly increasing' [3], 'monotonic
> increasing' [2].

I am not sure if this is the case but the term monotonic increasing
seems to imply increasing by one to me.  The oracle can skip time
stamps.  It reserves blocks of 1000 times stamps in zookeeper.  When
shutdown it picks up at the end of the last block.  If everything in
the prev block was not served it will skip some.  For this reason
'strictly increasing' seems like a better choice of words to me.  I
think it would be fine to use this terminology in the javadoc, w/o
explanation (could link for explanation if it seems useful).

>
> Calling the allocateTimestamp function strictly increasing or a strictly
> increasing function is also a pretty intuitive and mathematically sound
> statement. This would make precise what is being said in the first

Seeing this comment made me wonder if the oracle client getStamp()
function has good docs.  I looked at it and it does not. It could use
an improvement.

https://github.com/apache/fluo/blob/master/modules/core/src/main/java/org/apache/fluo/core/oracle/OracleClient.java#L355


> paragraph. Please give comments if this is too much geek/math or if its ok.

I am ok with improving the docs using more precise math terminology
and linking to definitions.  I don't think we need to provide the
definitions.  One caveat is that the integers are 64bit and can not
increase forever :P.


>
>
>
> [1] http://mathworld.wolfram.com/StrictOrder.html
> [2] http://mathworld.wolfram.com/MonotoneIncreasing.html
> [3] http://mathworld.wolfram.com/StrictlyIncreasingFunction.html

Mime
View raw message