On Fri, Dec 22, 2017 at 9:39 AM, Keith Turner <ke...@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 > <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
