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 17:33:09 GMT
On Fri, Dec 22, 2017 at 9:39 AM, Keith Turner <keith@deenlo.com> wrote:
> 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

Please forgive the duplicate content in my reply.  I started to
respond at the top of the email and then decided to respond inline.  I
forgot I had the above, I meant to delete it.   So the content above
was not fully baked.

> 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

View raw message