Main Content

Handling Timer Queuing Conflicts

During busy times, in multiple-execution scenarios, the timer might need to add the timer callback function (TimerFcn) to the MATLAB® execution queue before the previously queued execution of the callback function has been completed. The BusyMode property affects behavior only when the ExecutionMode property is set to FixedRate. For other values of ExecutionMode, there cannot be overlapping attempts to execute the timer callback function because the delay between executions is always relative to the completion of the previous execution.

You can determine how the timer object handles this scenario by setting the BusyMode property to use one of these modes:

Drop Mode (Default)

If you specify 'drop' as the value of the BusyMode property, the timer object adds the timer callback function to the execution queue only when the queue is empty. If the execution queue is not empty, the timer object skips the execution of the callback.

For example, suppose you create a timer with a period of 1 second, but a callback that requires at least 1.6 seconds, as shown here for mytimer.m.

function mytimer()
    t = timer;

    t.Period         = 1;
    t.ExecutionMode  = 'fixedRate';
    t.TimerFcn       = @mytimer_cb;
    t.BusyMode       = 'drop';
    t.TasksToExecute = 5;
    t.UserData       = tic;

    start(t)
end


function mytimer_cb(h,~)
    timeStart = toc(h.UserData)
    pause(1.6);
    timeEnd = toc(h.UserData)
end

This table describes how the timer manages the execution queue.

Approximate Elapsed Time (Seconds)

Timer Action

Function Running
0 (timer start)Add TimerFcn to timer queueNone
0 + queue lagNo action taken.First call of TimerFcn
1Attempt to add 2nd call of TimerFcn to queue. 1st call of TimerFcn is still running so 2nd call is dropped
1.6Add 2nd call of TimerFcn to queuenone
1.6 + queue lagNo action taken.2nd call of TimerFcn
2Attempt to add 3rd call of TimerFcn to queue. 2nd call of TimerFcn is still running so 3rd call is dropped
3.2Add 3rd call of TimerFcn to queue. 4th call is droppednone
3.2 + queue lagAttempt to add 4th call of TimerFcn to queue. 3rd call of TimerFcn is still running so 4th call is dropped3rd call of TimerFcn
3.2
4.8Add 4th call of TimerFcn to queue. 5th call is droppednone
4.8 + queue lagAttempt to add 5th call of TimerFcn to queue. 4th call of TimerFcn is still running so 5th call is dropped4th call of TimerFcn
4.8
6.4Add 5th call of TimerFcn to queue.none
6.4 + queue lagTasksToExecute has a value of 5 so mytimer has no more callbacks to execute.5th call of TimerFcn
8

Error Mode

The 'error' mode for the BusyMode property is similar to the 'drop' mode: In both modes, the timer allows only one instance of the callback in the execution queue. In 'error' mode, when the queue is nonempty, the timer calls the function that you specify by using the ErrorFcn property, and then stops processing. The currently running callback function completes, but the callback in the queue does not execute.

For example, modify mytimer.m (described in the previous section) so that it includes an error handling function and sets BusyMode to 'error'.

function mytimer()
    t = timer;

    t.Period         = 1;
    t.ExecutionMode  = 'fixedRate';
    t.TimerFcn       = @mytimer_cb;
    t.ErrorFcn       = @myerror;
    t.BusyMode       = 'error';
    t.TasksToExecute = 5;
    t.UserData       = tic;

    start(t)
end


function mytimer_cb(h,~)
    timeStart = toc(h.UserData)
    pause(1.6);
    timeEnd = toc(h.UserData)
end

function myerror(h,~)
    disp('Reached the error function')
end

This table describes how the timer manages the execution queue.

Approximate Elapsed Time (Seconds)

Timer Action

Function Running
0 (timer start)Add TimerFcn to timer queueNone
0 + queue lagNo action taken.First call of TimerFcn
1Attempt to add 2nd call of TimerFcn to queue. 1st call of TimerFcn is still running so myerror will be queued at the completion of the first call of TimerFcn
1.6Add myerror to queuenone
1.6 + queue lagNo action taken.myerror is called

Queue Mode

If you specify 'queue', the timer object waits until the currently executing callback function finishes before queuing the next execution of the timer callback function.

In 'queue' mode, the timer object tries to make the average time between executions equal the amount of time specified in the Period property. If the timer object has to wait longer than the time specified in the Period property between executions of the timer function callback, it shortens the time period for subsequent executions to make up the time.

For example, modify mytimer.m (described in the previous section) so that BusyMode is set to 'queue'.

function mytimer()
    t = timer;

    t.Period         = 1;
    t.ExecutionMode  = 'fixedRate';
    t.TimerFcn       = @mytimer_cb;
    t.ErrorFcn       = @myerror;
    t.BusyMode       = 'queue';
    t.TasksToExecute = 5;
    t.UserData       = tic;

    start(t)
end


function mytimer_cb(h,~)
    timeStart = toc(h.UserData)
    pause(1.6);
    timeEnd = toc(h.UserData)
end

function myerror(h,~)
    disp('Reached the error function')
end

This table describes how the timer manages the execution queue.

Approximate Elapsed Time (Seconds)Timer ActionFunction Running
0Start the first execution of the callback.None
0 + queue lagNo action taken.First call of TimerFcn
1Attempt to start the 2nd execution of the callback. The 1st execution is not complete and the execution queue remains empty.
1.6The timer adds the 2nd callback to the queuenone
1.6 + queue lagNo action taken.2nd call of TimerFcn
2Attempt to add the 3rd execution of the callback. The 2nd execution is not complete and the execution queue remains empty.
3 Attempt to start the 4th execution of the callback. The 2nd execution is not complete and the execution queue remains empty.
3.2Finish the 2nd callback execution. The timer adds the 3rd and 4th callbacks to the queue and executes the 3rd. The execution queue contains the 4th callback.none
3.2 + queue lagNo action taken.3rd call of TimerFcn
4Attempt to start 5th and final execution of the callback. The 3rd execution is not complete. The execution queue contains the 4th callback.
4.8Finish the 3rd callback execution. The timer adds the 5th execution to the queue and executes the 4th. The execution queue contains the 5th callback.None
4.8 + queue lagTasksToExecute has a value of 5 so mytimer has no more callbacks to execute.4th call of TimerFcn
6.4none
6.4 + queue lag5th call of TimerFcn
8

See Also

Related Topics