Timer Service

The TimerServiceProvider is used by components to schedule timed events.

Scheduling a Timed Event

To schedule a timed event a component uses one of two EMANE::TimerServiceProvider methods: scheduleTimedEvent or schedule.

TimerServiceProvider::scheduleTimedEvent results in a call to TimerServiceUser::processTimedEvent. An optional opaque data pointer and reschedule interval can be specified.

The TimerServiceProvider::schedule method is used to schedule an arbirtray callable. The callable will execute on the same functor queue as all the API messages. An optional reschedule interval can be specified.

The TimerServiceProvider is accessed via the PlatformServiceProvider. All components are given a reference to the PlatformServiceProvider when they are constructed.

Timer schedule example using a lamda:

  radioMetricTimedEventId_ =
    pPlatformService_->timerService().
    schedule([this](const TimePoint &,
                    const TimePoint &,
                    const TimePoint &)
             {
               if(!bRadioMetricEnable_)
                 {
                   neighborMetricManager_.updateNeighborStatus();
                 }
               else
                 {
                   ControlMessages msgs{
                     Controls::R2RISelfMetricControlMessage::create(u64DataRatebps_,
                                                                    u64DataRatebps_,
                                                                    radioMetricReportIntervalMicroseconds_),
                     Controls::R2RINeighborMetricControlMessage::create(neighborMetricManager_.getNeighborMetrics()),
                     Controls::R2RIQueueMetricControlMessage::create(queueMetricManager_.getQueueMetrics())};

                   sendUpstreamControl(msgs);
                 }
             },
             Clock::now() + radioMetricReportIntervalMicroseconds_,
             radioMetricReportIntervalMicroseconds_);

Timer schedule example using std::bind:

          downstreamQueueTimedEventId_ =
            pPlatformService_->timerService().
            schedule(std::bind(&MACLayer::handleDownstreamQueueEntry,
                               this,
                               currentEndOfTransmissionTime_,
                               u64TxSequenceNumber_),
                     currentEndOfTransmissionTime_);

An attempt to schedule a timed event will always succeed. If the requested expiration time is in the past it will be scheduled to immediately fire.

Handling a Timed Event

When a timed event expires it is pushed onto the NEM's functor queue as a TimerServiceUser::processTimedEvent method or callable depending on the interface used to scedule the timer.

The processTimedEvent method arguments contain:

• The Timer Id of the expired timer
• The requested expiration time of the timer
• The actual time the timer was scheduled by the framework
• The actual time the timer fired and was handled by the framework
• The opaque data pointer used when the timer was scheduled

A scheduled callable contains the following arguments:

• The requested expiration time of the timer
• The actual time the timer was scheduled by the framework
• The actual time the timer fired and was handled by the framework

Use std::placeholders to access these parameters when using std::bind.

The three time arguments are used by the framework to track timer service performance but may be of interest to the component.

Canceling a Timed Event

A scheduled timed event can be canceled using TimerServiceProvider::cancelTimedEvent. It is not an error to attempt to cancel a timed event that has already expired. The cancelTimedEvent method will return true if the event was canceled and false if the event has already expired prior to the cancel attempt.

  pPlatformService_->timerService().cancelTimedEvent(downstreamQueueTimedEventId_);

It is possible that an attempt to cancel a timed event will return false indicating the event expired prior to it being executed. This can occur when the timed event message is placed on the functor queue but has not yet been serviced.