Source code

001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.reef.wake.time.runtime;
020
021import org.apache.reef.tang.annotations.DefaultImplementation;
022import org.apache.reef.wake.time.Time;
023
024/**
025 * An interface for Timer.
026 * Default implementation uses actual system time.
027 */
028@DefaultImplementation(RealTimer.class)
029public interface Timer {
030
031  /**
032   * Get current time in milliseconds since the beginning of the epoch (01/01/1970).
033   * Note that this time may not necessarily match the actual system time - e.g. in unit tests.
034   * @return Current system time in milliseconds since the start of the epoch.
035   */
036  long getCurrent();
037
038  /**
039   * Get the number of milliseconds between current time as tracked by the Timer implementation
040   * and the given event. Can return a negative number if the event is already in the past.
041   * @param time Timestamp in milliseconds.
042   * @return Difference in milliseconds between the given timestamp and the time tracked by the timer.
043   * The result is a negative number if the timestamp is in the past (according to the timer's time).
044   * @deprecated [REEF-1532] Prefer passing Time object instead of the numeric timestamp.
045   * Remove after release 0.16.
046   */
047  long getDuration(final long time);
048
049  /**
050   * Get the number of milliseconds between current time as tracked by the Timer implementation
051   * and the given event. Can return a negative number if the event is already in the past.
052   * @param time Timestamp object that wraps time in milliseconds.
053   * @return Difference in milliseconds between the given timestamp and the time tracked by the timer.
054   * The result is a negative number if the timestamp is in the past (according to the timer's time).
055   */
056  long getDuration(final Time time);
057
058  /**
059   * Check if the event with a given timestamp has occurred, according to the timer.
060   * Return true if the timestamp is equal or less than the timer's time, and false if
061   * it is still in the (timer's) future.
062   * @param time Timestamp in milliseconds.
063   * @return False if the given timestamp is still in the timer's time future.
064   * @deprecated [REEF-1532] Prefer passing Time object instead of the numeric timestamp.
065   * Remove after release 0.16.
066   */
067  boolean isReady(final long time);
068
069  /**
070   * Check if the event with a given timestamp has occurred, according to the timer.
071   * Return true if the timestamp is equal or less than the timer's time, and false if
072   * it is still in the (timer's) future.
073   * @param time Timestamp object that wraps time in milliseconds.
074   * @return False if the given timestamp is still in the timer's time future.
075   */
076  boolean isReady(final Time time);
077}