Main Content

rateControl

Execute loop at fixed frequency

Description

The rateControl object enables you to run a loop at a fixed frequency. It also collects statistics about the timing of the loop iterations. Use waitfor in the loop to pause code execution until the next time step. The loop operates every DesiredPeriod seconds, unless the enclosed code takes longer to operate. The object uses the OverrunAction property to determine how it handles longer loop operation times. The default setting, 'slip', immediately executes the loop if LastPeriod is greater than DesiredPeriod. Using 'drop' causes the waitfor method to wait until the next multiple of DesiredPeriod is reached to execute the next loop.

Tip

The scheduling resolution of your operating system and the level of other system activity can affect rate execution accuracy. As a result, accurate rate timing is limited to 100 Hz for execution of MATLAB® code. To improve performance and execution speeds, use code generation.

Creation

Description

rateObj = rateControl(desiredRate) creates an object that operates loops at a fixed-rate based on your system time and directly sets the DesireRate property.

example

Properties

expand all

Desired execution rate of loop, specified as a scalar in Hz. When using waitfor, the loop operates every DesiredRate seconds, unless the loop takes longer. It then begins the next loop based on the specified OverrunAction.

Desired time period between executions, specified as a scalar in seconds. This property is equal to the inverse of DesiredRate.

Elapsed time since construction or reset, specified as a scalar in seconds.

Elapsed time between last two calls to waitfor, specified as a scalar. By default, LastPeriod is set to NaN until waitfor is called for the first time. After the first call, LastPeriod equals TotalElapsedTime.

Method for handling overruns, specified as one of these character vectors:

  • 'drop' — waits until the next time interval equal to a multiple of DesiredPeriod

  • 'slip' — immediately executes the loop again

Each code section calls waitfor at the end of execution.

Object Functions

waitforPause code execution to achieve desired execution rate
statisticsStatistics of past execution periods
resetReset Rate object

Examples

collapse all

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.001234
Iteration: 2 - Time Elapsed: 1.000570
Iteration: 3 - Time Elapsed: 2.001055
Iteration: 4 - Time Elapsed: 3.000756
Iteration: 5 - Time Elapsed: 4.001403
Iteration: 6 - Time Elapsed: 5.000534
Iteration: 7 - Time Elapsed: 6.000781
Iteration: 8 - Time Elapsed: 7.000148
Iteration: 9 - Time Elapsed: 8.000565
Iteration: 10 - Time Elapsed: 9.001009

Each iteration executes at a 1-second interval.

Create a rateControl object for running at 20 Hz.

r = rateControl(20);

Start a loop and control operation using the rateControl object.

for i = 1:30
    % Your code goes here
    waitfor(r);
end

Get Rate object statistics after loop operation.

stats = statistics(r)
stats = struct with fields:
              Periods: [0.0535 0.0476 0.0504 0.0498 0.0528 0.0461 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0507 0.0494 0.0499 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500 0.0500]
           NumPeriods: 30
        AveragePeriod: 0.0500
    StandardDeviation: 0.0012
          NumOverruns: 0

Create a rateControl object for running at 20 Hz.

r = rateControl(2);

Start a loop and control operation using the Rate object.

for i = 1:30
    % Your code goes here
    waitfor(r);
end

Display the rateControl object properties after loop operation.

disp(r)
  rateControl with properties:

         DesiredRate: 2
       DesiredPeriod: 0.5000
       OverrunAction: 'slip'
    TotalElapsedTime: 15.0047
          LastPeriod: 0.5000

Reset the object to restart the time statistics.

reset(r);
disp(r)
  rateControl with properties:

         DesiredRate: 2
       DesiredPeriod: 0.5000
       OverrunAction: 'slip'
    TotalElapsedTime: 0.0018
          LastPeriod: NaN

Version History

Introduced in R2016a

expand all