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; 020 021 022import org.apache.reef.tang.annotations.DefaultImplementation; 023import org.apache.reef.tang.annotations.Name; 024import org.apache.reef.tang.annotations.NamedParameter; 025import org.apache.reef.wake.EventHandler; 026import org.apache.reef.wake.impl.LoggingEventHandler; 027import org.apache.reef.wake.impl.MissingStartHandlerHandler; 028import org.apache.reef.wake.time.event.Alarm; 029import org.apache.reef.wake.time.event.StartTime; 030import org.apache.reef.wake.time.event.StopTime; 031import org.apache.reef.wake.time.runtime.RuntimeClock; 032import org.apache.reef.wake.time.runtime.event.IdleClock; 033import org.apache.reef.wake.time.runtime.event.RuntimeStart; 034import org.apache.reef.wake.time.runtime.event.RuntimeStop; 035 036import java.util.Set; 037 038/** 039 * Represents a clock. 040 */ 041@DefaultImplementation(RuntimeClock.class) 042public interface Clock extends Runnable, AutoCloseable { 043 044 /** 045 * Schedule a TimerEvent at the given future offset. 046 * @param handler Event handler to be called on alarm. 047 * @param offset Offset into the future in milliseconds. 048 * @return Newly scheduled alarm. 049 * @throws IllegalStateException When the clock has been already closed. 050 */ 051 Time scheduleAlarm(final int offset, final EventHandler<Alarm> handler); 052 053 /** 054 * This will stop the clock after all client alarms 055 * finish executing. 056 */ 057 @Override 058 void close(); 059 060 /** 061 * This stops the clock immediately, without waiting for 062 * client alarms to finish. 063 */ 064 void stop(); 065 066 /** 067 * This stops the clock immediately, without waiting for 068 * client alarms to finish. Stops with an exception that 069 * is propagated to RuntimeStopHandlers. 070 */ 071 void stop(final Throwable exception); 072 073 /** 074 * Clock is idle if it has no future Alarms set. 075 * 076 * @return true if idle, otherwise false 077 */ 078 boolean isIdle(); 079 080 /** 081 * Clock is closed after a call to stop() or close(). 082 * A closed clock cannot add new alarms to the schedule, but, in case of the 083 * graceful shutdown, can still invoke previously scheduled ones. 084 * @return true if closed, false otherwise. 085 */ 086 boolean isClosed(); 087 088 /** 089 * Bind this to an event handler to statically subscribe to the StartTime Event. 090 */ 091 @NamedParameter(default_class = MissingStartHandlerHandler.class, doc = "Will be called upon the start event") 092 class StartHandler implements Name<Set<EventHandler<StartTime>>> { 093 } 094 095 /** 096 * Bind this to an event handler to statically subscribe to the StopTime Event. 097 */ 098 @NamedParameter(default_class = LoggingEventHandler.class, doc = "Will be called upon the stop event") 099 class StopHandler implements Name<Set<EventHandler<StopTime>>> { 100 } 101 102 /** 103 * Bind this to an event handler to statically subscribe to the RuntimeStart Event. 104 */ 105 @NamedParameter(default_class = LoggingEventHandler.class, doc = "Will be called upon the runtime start event") 106 class RuntimeStartHandler implements Name<Set<EventHandler<RuntimeStart>>> { 107 } 108 109 /** 110 * Bind this to an event handler to statically subscribe to the RuntimeStart Event. 111 */ 112 @NamedParameter(default_class = LoggingEventHandler.class, doc = "Will be called upon the runtime stop event") 113 class RuntimeStopHandler implements Name<Set<EventHandler<RuntimeStop>>> { 114 } 115 116 /** 117 * Bind this to an event handler to statically subscribe to the IdleClock Event. 118 */ 119 @NamedParameter(default_class = LoggingEventHandler.class, doc = "Will be called upon the Idle event") 120 class IdleHandler implements Name<Set<EventHandler<IdleClock>>> { 121 } 122}