Main Content

Execute Code at a Fixed-Rate

Introduction

By executing code at constant intervals, you can accurately time and schedule tasks. Using a rateControl object allows you to control the rate of your code execution. These examples show different applications for the rateControl object including its uses with ROS and sending commands for robot control.

Run Loop at Fixed Rate

Create a rate object that runs at 1 Hz.

r = rateControl(1);

Start a loop using the rateControl object inside to control the loop execution. Reset the object prior to the loop execution to reset timer. Print the iteration and time elapsed.

reset(r)
for i = 1:10
	time = r.TotalElapsedTime;
	fprintf('Iteration: %d - Time Elapsed: %f\n',i,time)
	waitfor(r);
end
Iteration: 1 - Time Elapsed: 0.001113
Iteration: 2 - Time Elapsed: 1.001346
Iteration: 3 - Time Elapsed: 2.001142
Iteration: 4 - Time Elapsed: 3.001549
Iteration: 5 - Time Elapsed: 4.001334
Iteration: 6 - Time Elapsed: 5.001127
Iteration: 7 - Time Elapsed: 6.000532
Iteration: 8 - Time Elapsed: 7.001179
Iteration: 9 - Time Elapsed: 8.000507
Iteration: 10 - Time Elapsed: 9.000453

Each iteration executes at a 1-second interval.

Overrun Actions for Fixed Rate Execution

The rateControl object uses the OverrunAction property to decide how to handle code that takes longer than the desired period to operate. The options are 'slip' (default) or 'drop'. This example shows how the OverrunAction affects code execution.

Setup desired rate and loop time. slowFrames is an array of times when the loop should be stalled longer than the desired rate.

desiredRate = 1;
loopTime = 20;
slowFrames = [3 7 12 18];

Create the Rate object and specify the OverrunAction property. 'slip' indicates that the waitfor function will return immediately if the time for LastPeriod is greater than the DesiredRate property.

rate = rateControl(desiredRate);
rate.OverrunAction = 'slip';

Reset Rate object and begin loop. This loop will execute at the desired rate until the loop time is reached. When the TotalElapsedTime reaches a slow frame time, it will stall for longer than the desired period.

reset(rate);

while rate.TotalElapsedTime < loopTime
    if ~isempty(find(slowFrames == floor(rate.TotalElapsedTime)))
        pause(desiredRate + 0.1)
    end
    waitfor(rate);
end

View statistics on the Rate object. Notice the number of periods.

stats = statistics(rate)
stats = struct with fields:
              Periods: [1.0005 0.9996 1.0002 1.1028 0.9987 1.0009 0.9994 1.1023 1.0003 0.9994 0.9999 1.0003 1.1013 0.9994 1.0005 0.9996 1.0003 1.0004 1.1019 0.9994]
           NumPeriods: 20
        AveragePeriod: 1.0204
    StandardDeviation: 0.0419
          NumOverruns: 4

Change the OverrunAction to 'drop'. 'drop' indicates that the waitfor function will return at the next time step, even if the LastPeriod is greater than the DesiredRate property. This effectively drops the iteration that was missed by the slower code execution.

rate.OverrunAction = 'drop';

Reset Rate object and begin loop.

reset(rate);

while rate.TotalElapsedTime < loopTime
    if ~isempty(find(slowFrames == floor(rate.TotalElapsedTime)))
        pause(1.1)
    end
    waitfor(rate);
end
stats2 = statistics(rate)
stats2 = struct with fields:
              Periods: [1.0003 0.9999 1.0009 2.0031 0.9959 1.0009 2.0002 0.9994 1.0003 0.9994 2.0003 1.0004 0.9994 1.0004 1.0003 2.0003]
           NumPeriods: 16
        AveragePeriod: 1.2501
    StandardDeviation: 0.4477
          NumOverruns: 4

Using the 'drop' over run action resulted in 16 periods when the 'slip' resulted in 20 periods. This difference is because the 'slip' did not wait until the next interval based on the desired rate. Essentially, using 'slip' tries to keep the AveragePeriod property as close to the desired rate. Using 'drop' ensures the code will execute at an even interval relative to DesiredRate with some iterations being skipped.

See Also

| (ROS Toolbox) | (Robotics System Toolbox)