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