Clock Class Reference

A clock allows us to compute time-based metrics by generating events at pre-set time intervals wrt the trace being generated. More...

#include <Clock.h>

List of all members.

Public Member Functions
	Clock (void)
	create a clock
	Clock (const Timeval &delta)
	create a clock that ticks at the given interval
	Clock (const Clock &toCopy)
Clock *	clone (const Clock &toCopy)
Clock &	operator= (const Clock &rhs)
Alarm &	addAlarm (AlarmListener &l, const Timeval &s, const Timeval &i)
	Add a repeating alarm initiated at a given time, occurring at a given interval.
void	addAlarmEvent (Alarm &alarm, const Timeval &when)
	Method for Alarm objects to add AlarmEvents.
void	updateClock (const Timeval &time)
	global clock update, called before a packet is processed
const Timeval &	getTime (void) const
	get the current time
int	getPhase (void) const
	get the current phase of the timeval
Static Public Member Functions
static Clock &	getClock (void)
Static Public Attributes
static const int	PHASE_PRETIME = 0
static const int	PHASE_INTIME = 1
static const int	PHASE_POSTTIME = 2
Protected Attributes
std::vector< Alarm * >	alarms
std::priority_queue< AlarmEvent, std::vector< AlarmEvent >, std::greater< AlarmEvent > >	q
Timeval	currTime
int	phase
bool	started
Static Protected Attributes
static Clock	theClock

---

Detailed Description

A clock allows us to compute time-based metrics by generating events at pre-set time intervals wrt the trace being generated.

Time is a major issue for this toolkit, in more ways than one. We wish to be able to support two types of time-driven attributes; those with a time-based window, and alarm-driven attributes. The former need to be able to update their windows appropriately, and the latter need to receive alarms at a pre-set interval in order to update. An example of windowed attributes is a buffer that maintains the packet length of every packet for a flow in the past 30 seconds; an example of an alarm-driven attribute is one that maintains a list of data volumes over discrete 30-second windows, and another example is one that computes the minimum 30-second data volume (over non-discrete intervals). This documentation discusses the motivation behind the time handling for the toolkit, as there are a number of very significant design decisions taken here based on many interacting factors - put simply, I think these things are VERY hazardous to muck with, so I'm trying to flag all the landmines.

Windowed attributes must be able to update their windows so that they contain all packets in a certain time window, without double-counting (unless it's a sliding window). That is, for a 30s window, the window starting at time 0s and the one starting at time 30s should not share any packets. They must also be able to ensure that their window is up-to-date at any given time.

Alarm-driven attributes must be able to tell the toolkit to poll them at a set frequency from a given start time, and the toolkit must ensure that these alarms are triggered. An alarm being triggered means a handler function being called in the attribute which set the alarm. It also must be able to ensure that an alarm set for the current time has gone off, due to the possibility of simultaneous alarms for multiple attributes with some interdependency (i.e. if A and B both have an alarm set for time t, and B depends on A, but B's alarm goes off first, then when A is queried by B, it has to be able to trigger its own alarm if appropriate).

To deal with the boundary problems that arise, we imagine three phases to each timeval: pretime, intime, and posttime. Pretime is an imaginary time before the timeval, and posttime an imaginary time after the timeval, wheras intime is the period of real time represented by the timeval. Pretime and posttime give us time to evalutate alarms when windows are in a consistent state. By this, we mean that in pretime for a timeval t, a window of time length w will include all packets in the interval [t-w,t), and in posttime for that timeval, it will include all packets in the interval (t-w,t]. During intime, no guarantees can be made, as we could be between processing two packets, both with a timestamp of t. Alarms for a specific timeval are handled in pretime for that timeval; the posttime is for a (to-be-implemented) `anytime' alarm functionality. That latter type of alarm is for min/max attributes that need to run computations before and after each timeval is handled. These phases spare us the metaphysical and pragmatic distresses inherent in `incrementing' a real valued timeval. :p

These mechanisms have consequences for purging flows with alarm-driven attributes; if a flow has a pending alarm, it should not be purged. For example, if a flow has a 30s data rate attribute, purging it while the alarm is still active would result in the packets between the end of the last full 30s segment and the end of the flow not being counted. Currently this is handled by leaving a flow in a `garbage bin' state and setting its alarms to go inactive after the next time they fire, then once all of the flow's alarms have gone inactive, it can be purged. >> On second thought, what we'll do for now is not leave the alarms on, but force alarm-driven attributes to have a `finalCalc' method that does whatever it has to to munge up the last value when the attribute is being deallocated.

Several design choices were made to accomodate all this messiness:

• Alarms are handled as independent objects, registered with the global clock, which pings them to go off when appropriate
• The global clock keeps track not only of the current timeval, but also the phase of the timeval: pretime, intime, or posttime
• Windowed attributes should not be used during intime, due to the possibility of there being unprocessed packets for the current timeval (which could lead to invalid computations)
• Most set alarms are triggered during pretime; this is a bit easier to deal with (we know that it's pretime as soon as a packet for that new timeval is received, rather than having to wait for all the packets for a timeval to roll around), and it means that any periodic metrics will include the first packet in the flow (this is significant, because alarms will often be created with a timeval based on that of the first packet in the flow)
• Alarms know the last timeval for which they triggered and the interval at which they go off, and can be polled by the attribute that `owns' them when that attribute updates; this addresses the issue of simultaneous alarms for interdependent attributes
• Alarms are idempotent for a given timeval; that is, an alarm must not go off twice for one timeval
• Alarms can be in one of three states: active, final, or inactive
• A flow to be purged must be checked for active (rather, non-inactive) alarms before the purging continues; if there are any, they are put into the final state, where they trigger once more then go inactive
• (TBD) An attribute can use an `anytime' alarm that triggers both before and after a timeval worth of packets are processed; these would be things like `maximum 5s (burst) datarate' or `minimum 5s datarate'
• An alarm-driven attribute will have a handlePacket method that sets up the alarm when it sees its first packet, and that is dormant thereafter
• Alarms themselves are not polled by the clock; the clock holds on to them so that they're not drifting off in the ether, but the polling is accomplished via AlarmEvents. For an alarm to get set off by the clock, it must register an AlarmEvent (and thus for it to recur, it must re-register an AlarmEvent after one triggers)

Todo:

We can probably build a better system to handle time-based events. One option would be to implement multiple event channels, e.g. global, per flow, per attribute, etc., then have attributes subscribe to the appropriate channels. For example, a 'max datarate' attribute would have to subscribe to the appropriate packet length window, which would notify the former before and after any value was added or removed from the window. This route would require a lot of careful design to be sure that everything would work properly, without incurring excessive amounts of overhead.

make certain that all attributes update when their values are accessed, otherwise bad things _will_ happen. This would be best to do by changing the getAttrib handling so that the superclass was more involved, possibly by replacing the per-attribute function with an initialization that populates a member which could be accessed by Attribute::getAttrib.

Examples:

profile_streams_thesis.cc.

---

Constructor & Destructor Documentation

Clock::Clock (  void   )

create a clock Defaults to a 1s interval

---

Member Function Documentation

Alarm & Clock::addAlarm (  AlarmListener &  l, const Timeval &  s, const Timeval &  i )

Add a repeating alarm initiated at a given time, occurring at a given interval. Parameters: s  start time - not the first alarm, usually the time at which the alarm is set i  interval l  AlarmListener to be alerted Note: First alarm will be at time s + i; reason is that this will normally be used to specify "Send me an alarm in x seconds and every x seconds thereafter".

void Clock::addAlarmEvent (  Alarm &  alarm, const Timeval &  when )

Method for Alarm objects to add AlarmEvents. Parameters: alarm  Alarm object registering alarm event when  time to set off alarm

void Clock::updateClock (  const Timeval &  time  )

global clock update, called before a packet is processed Parameters: time  The time value of the packet about to be processed

---

The documentation for this class was generated from the following files:

• data_structures/Clock.h
• data_structures/Clock.cc

---