com.datastax.driver.core.AbstractMonotonicTimestampGenerator Maven / Gradle / Ivy

/*
 * Copyright DataStax, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.datastax.driver.core;

import com.google.common.annotations.VisibleForTesting;

/**
 * Base implementation for monotonic timestamp generators.
 *
 * The accuracy of the generated timestamps is largely dependent on the granularity of the
 * underlying operating system's clock.
 *
 * 
Generally speaking, this granularity is millisecond, and the sub-millisecond part is simply a
 * counter that gets incremented until the next clock tick, as provided by {@link
 * System#currentTimeMillis()}.
 *
 * 
On some systems, however, it is possible to have a better granularity by using a JNR call to
 * {@code gettimeofday}. The driver will use this system call automatically whenever available,
 * unless the system property {@code com.datastax.driver.USE_NATIVE_CLOCK} is explicitly set to
 * {@code false}.
 *
 * 
Beware that to guarantee monotonicity, if more than one call to {@link #next()} is made within
 * the same microsecond, or in the event of a system clock skew, this generator might return
 * timestamps that drift out in the future. Whe this happens, {@link #onDrift(long, long)} is
 * invoked.
 */
public abstract class AbstractMonotonicTimestampGenerator implements TimestampGenerator {

  @VisibleForTesting volatile Clock clock = ClockFactory.newInstance();

  /**
   * Compute the next timestamp, given the last timestamp previously generated.
   *
   * 
To guarantee monotonicity, the next timestamp should be strictly greater than the last one.
   * If the underlying clock fails to generate monotonically increasing timestamps, the generator
   * will simply increment the previous timestamp, and {@link #onDrift(long, long)} will be invoked.
   *
   * 
This implementation is inspired by {@code
   * org.apache.cassandra.service.ClientState#getTimestamp()}.
   *
   * @param last the last timestamp generated by this generator, in microseconds.
   * @return the next timestamp to use, in microseconds.
   */
  protected long computeNext(long last) {
    long currentTick = clock.currentTimeMicros();
    if (last >= currentTick) {
      onDrift(currentTick, last);
      return last + 1;
    }
    return currentTick;
  }

  /**
   * Called when generated timestamps drift into the future compared to the underlying clock (in
   * other words, if {@code lastTimestamp >= currentTick}).
   *
   * This could happen if timestamps are requested faster than the clock granularity, or on a
   * clock skew (for example because of a leap second).
   *
   * @param currentTick the current clock tick, in microseconds.
   * @param lastTimestamp the last timestamp that was generated, in microseconds.
   */
  protected abstract void onDrift(long currentTick, long lastTimestamp);
}