timerfindall

Find all timer objects

Syntax

out = timerfindall

out = timerfindall(Name,Value)

out = timerfindall(t,Name,Value)

out = timerfindall(S)

Description

out = timerfindall finds timer objects existing in memory, regardless of visibility, and returns an array, out. Use the ObjectVisibility property to set the object’s visibility.

out = timerfindall(Name,Value) finds timer objects existing in memory, regardless of visibility, with property values matching those passed as Name,Value arguments and returns an array, out. Value can be an empty array. In this case, timerfindall finds timers that have empty values for the property specified by Name.

out = timerfindall(t,Name,Value) matches Name,Value arguments to the timer objects listed in t, where t can be an array of timer objects, and returns an array out.

out = timerfindall(S) matches property values defined in the structure S and returns an array, out. The field names of S are timer object property names. The field values are the corresponding property values.

Examples

Stop all Timers

Use the timerfindall function to stop multiple timers at the same time even when the timer variables have been removed from the workspace.

Create two timer objects that generates 100 random numbers and executes 1,000,000 times. Define a StopFcn callback that displays the message 'Timer has stopped.' Start the timers and verify that the timer is running

t1 = timer('TimerFcn','rand(100,1);',...
    'ExecutionMode','fixedSpacing','TasksToExecute',1e6,...
    'StopFcn','disp(''Timer1 has stopped.'')');
t2 = timer('TimerFcn','rand(100,1);',...
    'ExecutionMode','fixedSpacing','TasksToExecute',1e6,...
    'StopFcn','disp(''Timer2 has stopped.'')');
start([t1 t2])

Clear the timer variables from the workspace.

clear

Use timerfindall to manually stop the timers and verify that they are no longer running.

stop(timerfindall)
t1.Running

ans = 
'off'

t2.Running

ans = 
'off'

Delete the timers.

delete(timerfindall)

Find and Delete All Timers From Memory

Create four timer objects.

t1 = timer('TimerFcn',@(~,~)disp('Timer 1 Fired!'));
t2 = timer('TimerFcn',@(~,~)disp('Timer 2 Fired!'));
t3 = timer('TimerFcn',@(~,~)disp('Timer 3 Fired!'));
t4 = timer('TimerFcn',@(~,~)disp('Timer 4 Fired!'));

Set timers t2 and t4 to be invisible.

t2.ObjectVisibility = 'off';
t4.ObjectVisibility = 'off';

Clear timers t1 and t2 from the workspace.

clear t1 t2
whos

  Name      Size            Bytes  Class    Attributes

  t3        1x1               104  timer              
  t4        1x1               104  timer              

Find all visible timers in memory.

timerfind

Timer Object Array

   Index:  ExecutionMode:  Period:  TimerFcn:               Name:
   1       singleShot      1        1x1 function_handle arraytimer-1
   2       singleShot      1        1x1 function_handle arraytimer-3

timerfind finds only timers t1 and t2 because they are visible. Timer t2 is still valid and in memory even though it was cleared from the workspace

Find all timers in memory.

timerfindall

Timer Object Array

   Index:  ExecutionMode:  Period:  TimerFcn:               Name:
   1       singleShot      1        1x1 function_handle arraytimer-1
   2       singleShot      1        1x1 function_handle arraytimer-2
   3       singleShot      1        1x1 function_handle arraytimer-3
   4       singleShot      1        1x1 function_handle arraytimer-4

timerfindall finds all four valid timers in memory even though t2 and t4 are invisible and t1 and t2 were cleared from the workspace.

Delete all timers from memory.

delete(timerfindall)

Find Invisible Timers

Create four timer objects.

t1 = timer('TimerFcn',@(~,~)disp('Timer 1 Fired!'));
t2 = timer('TimerFcn',@(~,~)disp('Timer 2 Fired!'));
t3 = timer('TimerFcn',@(~,~)disp('Timer 3 Fired!'));
t4 = timer('TimerFcn',@(~,~)disp('Timer 4 Fired!'));

Set timers t2 and t4 to be invisible. Clear timers t1 and t2 from the workspace.

t2.ObjectVisibility = 'off';
t4.ObjectVisibility = 'off';
clear t1 t2; 
whos

  Name      Size            Bytes  Class    Attributes

  t3        1x1               104  timer              
  t4        1x1               104  timer              

Find all valid invisible timers.

out = timerfindall('ObjectVisibility','off')

Timer Object Array

   Index:  ExecutionMode:  Period:  TimerFcn:               Name:
   1       singleShot      1        1x1 function_handle arraytimer-2
   2       singleShot      1        1x1 function_handle arraytimer-4

Both valid invisible timers were found by timerfindall, regardless of whether they were in the workspace.

Find Specific Timer Objects Existing in Memory

Create several individual timers and an array of timers.

t1 = timer('Tag', 'broadcastProgress','UserData','Monday');
t2 = timer('Tag', 'displayProgress','UserData','Monday');
timerArr = [timer('Tag', 'broadcastProgress','UserData','Tuesday');
    timer('Tag', 'displayProgress','UserData','Tuesday');
    timer('Tag', 'displayProgress','UserData','Wednesday');];

Make timer t1 and timerArr(2) invisible.

t1.ObjectVisibility = 'off';
timerArr(2).ObjectVisibility = 'off';

Find all the timers in memory by using timerfind.

out1 = timerfind

Timer Object Array

   Index:  ExecutionMode:  Period:  TimerFcn:               Name:
   1       singleShot      1        ''                      timer-2
   2       singleShot      1        ''                      timer-3
   3       singleShot      1        ''                      timer-5

timerfind does not find the hidden timers.

Find all the timers in memory by using timerfindall.

out2 = timerfindall

Timer Object Array

   Index:  ExecutionMode:  Period:  TimerFcn:               Name:
   1       singleShot      1        ''                      timer-1
   2       singleShot      1        ''                      timer-2
   3       singleShot      1        ''                      timer-3
   4       singleShot      1        ''                      timer-4
   5       singleShot      1        ''                      timer-5

timerfindall finds all timers, even the invisible ones.

Find only those timers in memory that have the value 'displayProgress' as the Tag property.

out3 = timerfindall('Tag','displayProgress')

Timer Object Array

   Index:  ExecutionMode:  Period:  TimerFcn:               Name:
   1       singleShot      1        ''                      timer-2
   2       singleShot      1        ''                      timer-4
   3       singleShot      1        ''                      timer-5

Limit the search for timers that have the value 'displayProgress' as the Tag property to timer objects in timerArr.

out4 = timerfindall(timerArr,'Tag','displayProgress')

Timer Object Array

   Index:  ExecutionMode:  Period:  TimerFcn:               Name:
   1       singleShot      1        ''                      timer-4
   2       singleShot      1        ''                      timer-5

Define a struct containing the Tag and UserData properties of interest.

searchStruct = struct('Tag','broadcastProgress','UserData','Monday')

searchStruct = 

         Tag: 'broadcastProgress'
    UserData: 'Monday'

Use the struct as the search criteria to find timer objects in memory.

out5 = timerfindall(searchStruct)

   Timer Object: timer-1

   Timer Settings
      ExecutionMode: singleShot
             Period: 1
           BusyMode: drop
            Running: off

   Callbacks
           TimerFcn: ''
           ErrorFcn: ''
           StartFcn: ''
            StopFcn: ''

Delete the timer objects.

delete(timerfindall)

Input Arguments

t — Timer object

timer object | array of timer objects

Timer to be found, specified as a timer object or array of timer objects

Example: out = timerfindall(t)

S — Field names

structure with field names corresponding to timer property names

Properties of timers to be found, specified as a structure that has field names corresponding to timer property names. Field values are the corresponding property values.

Example: out = timerfindall(S)

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: out = timerfind('BusyMode','drop')

Callback Function Properties

TimerFcn — Timer callback function

character vector | string scalar | function handle | cell array

Timer callback function, specified as a character vector, string scalar, function handle, or cell array. You must define this property before you can start the timer. To force the execution of the callback functions in the event queue, include a call to the drawnow function in your code. The drawnow function flushes the event queue.

• If you specify this property by using a function handle, when MATLAB^® executes the callback, it passes the timer object and an event structure to the callback function. The event structure contains the type of event in the Type field and the time of the event in the Data field.

• If you specify this property by using a character vector or string scalar, when MATLAB executes the callback, it evaluates the MATLAB code contained in the character vector. Defining a callback as a character vector is not recommended. The use of a function specified as function handle enables MATLAB to provide important information to your callback function.

• If your callback function accepts arguments in addition to the timer object and event data, specify this property as a cell array containing the function handle and the additional arguments.

For more information, see Timer Callback Functions.

Example: out = timerfind('TimerFcn',"MyTimerFunction(Input);")

StartFcn — Timer start callback function

character vector | string scalar | function handle | cell array

Timer start callback function, specified as a character vector, string scalar, function handle, or cell array.

• If you specify this property by using a function handle, when MATLAB executes the callback, it passes the timer object and an event structure to the callback function. The event structure contains the type of event in the Type field and the time of the event in the Data field.

• If you specify this property by using a character vector or string scalar, when MATLAB executes the callback, it evaluates the MATLAB code contained in the character vector. Defining a callback as a character vector is not recommended. The use of a function specified as function handle enables MATLAB to provide important information to your callback function.

• If your callback function accepts arguments in addition to the timer object and event data, specify this property as a cell array containing the function handle and the additional arguments.

For more information, see Timer Callback Functions.

Example: out = timerfind('StartFcn',@MyStartFunction(~,~))

StopFcn — Timer stop callback function

character vector | string scalar | function handle | cell array

Timer stop callback function, specified as a character vector, string scalar, function handle, or cell array.

• If you specify this property by using a function handle, when MATLAB executes the callback, it passes the timer object and an event structure to the callback function. The event structure contains the type of event in the Type field and the time of the event in the Data field.

• If you specify this property by using a character vector or string scalar, when MATLAB executes the callback, it evaluates the MATLAB code contained in the character vector. Defining a callback as a character vector is not recommended. The use of a function specified as function handle enables MATLAB to provide important information to your callback function.

• If your callback function accepts arguments in addition to the timer object and event data, specify this property as a cell array containing the function handle and the additional arguments.

For more information, see Timer Callback Functions.

The timer stops when:

• You call the timer stop method.

• The timer finishes executing TimerFcn. In other words, the value of TasksExecuted reaches the limit set by TasksToExecute.

• An error occurs. The ErrorFcn callback is called first, followed by the StopFcn callback.

You can use StopFcn to define cleanup actions, such as deleting the timer object from memory.

Example: out = timerfind('StopFcn',@MyStopFunction(~,~))

ErrorFcn — Timer error callback function

character vector | string scalar | function handle | cell array

Timer error callback function, specified as a character vector, string scalar, function handle, or cell array. If there is an error, this function executes, and then calls StopFcn.

• If you specify this property using a character vector or string scalar, when MATLAB executes the callback it evaluates the MATLAB code contained in the character vector.

• If you specify this property using a function handle, when MATLAB executes the callback it passes the timer object and an event structure to the callback function. The event structure contains the type of event in the Type field and the time of the event in the Data field.

• If your callback function accepts arguments in addition to the timer object and event data, specify this property as a cell array containing the function handle and the additional arguments.

For more information, see Timer Callback Functions.

Example: out = timerfind('ErrorFcn','disp("An error has occurred")')

Timing Properties

Period — Delay between executions

1 (default) | numeric scalar

Delay between executions, specified, in seconds, as a number greater than 0.001. For the timer to use Period, you must set ExecutionMode and TasksToExecute to schedule multiple timer object callback events.

Example: out = timerfind('Period',5)

StartDelay — Delay between start of timer and first execution

0 (default) | numeric scalar

Delay between start of timer and first execution, specified, in seconds, as a number greater than or equal to zero. When Running = 'on', StartDelay is read only.

Example: out = timerfind('StartDelay',2)

TasksToExecute — Times timer callback function is executed

numeric scalar

Times timer callback function is executed, specified as a number greater than zero. Use the TasksToExecute property to set the number of executions. To use TasksToExecute, you must set ExecutionMode to schedule multiple timer callback events.

Example: out = timerfind('TasksToExecute',5)

BusyMode — Timer function callback queueing

'drop' (default) | 'error' | 'queue'

Timer function callback queueing, specified as one of the values in the table. Use this property to specify the action taken when a timer has to execute TimerFcn before the completion of previous execution of the TimerFcn. When Running property is set to 'on', BusyMode property is read-only.

BusyMode Values	Behavior if Queue Empty	Behavior if Queue Not Empty	Notes
'drop'	Add task to queue	Drop task	Possible skipping of TimerFcn calls
'error'	Add task to queue	Complete task; throw error specified by ErrorFcn; stops timer	Stops timer after completing task in execution queue
'queue'	Add task to queue	Wait for queue to clear, and then enter task in queue	Adjusts Period property to manage tasks in execution queue

See Handling Timer Queuing Conflicts for more information.

Example: out = timerfind('BusyMode','error')

ExecutionMode — Timer function callback scheduling

'singleShot' (default) | 'fixedRate' | 'fixedDelay' | 'fixedSpacing'

Timer function callback scheduling, specified as one of the values in the table. When Running='on', ExecutionMode is read-only. This table summarizes the execution modes.

Execution Mode	Time Period Start Point
'singleShot'	The timer callback function is only executed once. Therefore, the Period property has no effect. This mode is the default execution mode.
'fixedRate'	Start immediately after the timer callback function is added to the MATLAB execution queue
'fixedDelay'	Start when the timer function callback restarts execution after a time lag due to delays in the MATLAB execution queue.
'fixedSpacing'	Start when the timer callback function finishes executing.

• 'singleShot' is the single execution mode for the timer class, and is the default value.

  

• 'fixedDelay', 'fixedRate', and 'fixedSpacing' are the three supported multiexecution modes. These modes define the starting point of the Period property. The Period property specifies the amount of time between executions, which remains the same. Only the point at which execution begins is different.

  

Example: out = timerfind('ExecutionMode','fixedDelay')

Labeling properties

Name — Timer name

'timer-i' (default) | character vector | string scalar

Timer name, specified as a character vector or string scalar.

Defaults to 'timer-i', where i is a number indicating the ith timer object created this session. To reset i to 1, execute the clear classes command.

Example: out = timerfind('Name','MyTimer')

Tag — Object label

character vector | string scalar

Object label, specified as character vector or string scalar.

Example: out = timerfind('Tag','TimerTag')

ObjectVisibility — Object visibility

'on' (default) | 'off'

Object visibility, specified as 'on' or 'off', so that you can discourage end-user access to the timer objects your application creates. The timerfind function does not return an object whose ObjectVisibility property is set to 'off'. Objects that are not visible are still valid. To retrieve a list of all the timer objects in memory, including the invisible ones, use the timerfindall function.

Example: out = timerfind('ObjectVisibility','off')

UserData — Field for user data

any valid MATLAB data type

Generic field for data that you want to add to the object.

Example: out = timerfind('UserData',"This is my first timer!")

Read-Only Properties

AveragePeriod — Average time between executions

numeric scalar

Average time between executions, specified, in seconds, as a numeric scalar. Value is NaN until timer executes two timer callbacks.

InstantPeriod — Time between the last two executions

NaN (default) | numeric scalar

Time between the last two executions, specified, in seconds, as a numeric scalar. Value is NaN until timer executes two timer callbacks.

Running — Indicator of actively executing callback functions

'off' | 'on'

Indicator of actively executing callback functions, specified as 'off' or 'on'.

TasksExecuted — Number of times timer has executed

numeric scalar

Number of times timer has executed, specified as a numeric scalar.

Type — object type

'timer' (default)

Character vector that identifies the object type.

Output Arguments

out — Found timer objects

array of timer objects

Found timer objects, returned as an array of timer objects.

More About

visible timer objects

Visible timer objects are timer objects that are in memory and have the ObjectVisibility property set to 'on'.

Version History

Introduced before R2006a