time_interface.r2py

"""
<Program Name>
  time_interface.r2py

<Author>
  Eric Kimbrel

<Started>
  Jul 2, 2009

<Purpose>
  Provide a framework to run any implementation of a ntp time service that
  follows the interface provided here.

  Any implementation must provide update method that takes a localport 
  as an argument.

  Implementers will set a mapping to their functions by calling 
  time_register_method

  USE:
  
  To use this module, first make a call to time_updatetime(localport),where
  localport is a valid UDP port that you can send and receive on (note that
  this port may not be used depending on the implementation.)

  Then, to get the actual time, call time_gettime() which will return
  the current time (in seconds).

  time.r2py will attempt to use the update method of any impelemntor included.
  If none are included or if they all fail an exception is thrown

"""


# dictionary for time implementers to store their information
# the settime method is passed in for use by implementers
TIME_IMP_DICT = {}

time_query_times = []

class TimeError(Exception):
  pass


def time_register_method(imp_name,update_method):
  """
  <Purpose>
  Allow an implementation to register its update method with time.r2py

  <Arguments>
  imp_name, the name or unique abbreviation of the implementation
  update_method, a time update_method
  
  <Exceptions>
  None

   <Returns>
   None
  """
  TIME_IMP_DICT[imp_name] = update_method




def time_updatetime(localport):
  """
   <Purpose>
    Obtains and stores the local time from a subset of NTP servers.
    Attempts to update the time with each implementation provided
    until one succeeds or they all fail

   <Arguments>
    localport:
             The local port that MAY be used when contacting the NTP server(s).
             Consider this port a hint and not a rule.
   
   <Exceptions>
    Exception occurs when all methods fail to updatetime, or no such methods 
    are provided (no mehtods have registered)

   <Side Effects>
    time_settime(currenttime) is called as the sub process of a sub process,
    which adjusts the current time.

   <Returns>
    None.
  """
  exception_list = []
  # try the 'update' function for each implementation, storing exceptions in
  # case of total failure, and exiting the function when any of the 'update'
  # functions succeed.
  for implementation_name, update_function in TIME_IMP_DICT.items():
    try:
      update_function(localport)
    except Exception, e:
      exception_list.append((implementation_name, type(e), str(e)))
    else:
      # Exit when we succeed.
      # Be warned that any error messages are suppressed!
      return
  else:
    raise TimeError("time_updatetime called before time_register_method!")

  # we failed
  raise TimeError('Error(s) in time_updatetime: ' + str(exception_list))





def time_settime(currenttime):
  """
   <Purpose>
    Sets a remote time as the current time.

   <Arguments>
    currenttime:
               The remote time to be set as the current time.

   <Exceptions>
    None.

   <Side Effects>
    Adjusts the current time.

   <Returns>
    None.
  """

  time_query_times.append((getruntime(), currenttime))






def time_gettime():
  """
   <Purpose>
    Gives the current time in seconds by calculating how much time has elapsed
    since the local time was obtained from an NTP server via the
    time_updatetime(localport) function.

   <Arguments>
    None.

   <Exceptions>
    TimeError when time_updatetime(localport)has not previously been called or 
    when time_updatetime(localport) has any unresolved TimeError exceptions.

   <Side Effects>
    None.

   <Returns>
    Current time in seconds.
  """

  if time_query_times == []:
    raise TimeError("Error from time_gettime(): time has not been set yet!")

  # otherwise use the most recent data...
  latest_update = time_query_times[-1]

  # first item is the getruntime(), second is NTP time...
  elapsedtimesinceupdate = getruntime() - latest_update[0]

  return latest_update[1] + elapsedtimesinceupdate



def time_getunixtime():
  """
   <Purpose>
    Gives the current time since 1970-01-01 (``The Epoch''), 
    i.e. Unix time. The returned timestamp can be parsed by 
    utilities like date, e.g.

    date -d @THETIMESTAMP  # Linux
    date -r THETIMESTAMP  # the BSDs, Mac OS X

   <Arguments>
    None.

   <Exceptions>
    As with time_gettime()

   <Side Effects>
    None.

   <Returns>
    Current Unix time in seconds.
  """
  return time_gettime() - time_seconds_from_1900_to_1970




# in case you want to change to time since the 1970 (as is common)
time_seconds_from_1900_to_1970 = 2208988800