timerfind

Class: timer

Find timer object

expand all in page

Syntax

out = timerfind
out = timerfind(Name,Value)
out = timerfind(t,Name,Value)
out = timerfind(S)

Description

example

out = timerfind finds the visible timer objectsand returns an array, out.

example

out = timerfind(Name,Value) finds visible timer objects with property values matching those passed as Name,Value pair arguments and returns an array, out.

example

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

example

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

Input Arguments

t

Array of objects of class timer

S

Structure with field names corresponding to timer object property names. Field values are the corresponding property values.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

'BusyMode'

Character vector or string scalar that indicates action taken when a timer has to execute TimerFcn before the completion of previous execution of the TimerFcn. When Running='on', BusyMode is read only. This table summarizes the busy modes.

BusyMode Values

Behavior if Queue Empty

Behavior if Queue Not Empty

Notes

'drop'

Adds task to queue

Drops task

Possible skipping of TimerFcn calls

'error'

Adds task to queue

Completes task; throws error specified by ErrorFcn; stops timer

Stops timer after completing task in execution queue

'queue'

Adds task to queue

Waits for queue to clear, and then enters task in queue

Adjusts Period property to manage tasks in execution queue

See Handling Timer Queuing Conflicts for more information.

Default: 'drop'

'ErrorFcn'

Character vector, string scalar, function handle, or cell array defining the function that the timer executes when an error occurs. 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.

'ExecutionMode'

Character vector or string scalar that defines how the timer object schedules timer events. When Running='on', ExecutionMode is read only. This table summarizes the execution modes.

Execution Mode

Time Period Start Point

'singleShot'

In this mode, the timer callback function is only executed once. Therefore, the Period property has no effect. This is the default execution mode.

'fixedRate'

Starts immediately after the timer callback function is added to the MATLAB execution queue

'fixedDelay'

Starts when the timer function callback restarts execution after a time lag due to delays in the MATLAB execution queue

'fixedSpacing'

Starts 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.

Default: 'singleShot'

'Name'

Character vector or string scalar representing the timer name.

Default: '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.

'ObjectVisibility'

Character vector or string scalar with possible values of 'on' or 'off', that provides a way for you to 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.

Default: 'on'

'Period'

Number greater than 0.001 that specifies the delay, in seconds, between executions of TimerFcn. For the timer to use Period, you must set ExecutionMode and TasksToExecute to schedule multiple timer object callback events.

Default: 1.0

'StartDelay'

Number greater than or equal to 0 that specifies the delay, in seconds, between the start of the timer and the first execution of the function specified in TimerFcn. When Running = 'on', StartDelay is read only.

Default: 0

'StartFcn'

Character vector, string scalar, function handle, or cell array defining the function that executes when the timer starts.

  • 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.

'StopFcn'

Character vector, string scalar, function handle, or cell array defining the function that executes when the timer stops.

  • 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.

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 clean up actions, such as deleting the timer object from memory.

'Tag'

Character vector or string scalar that represents a label for the object.

'TasksToExecute'

Number greater than 0, indicating the number of times the timer object is to execute the TimerFcn callback. Use the TasksToExecute property to set the number of executions. To use TasksToExecute, you must set ExecutionMode to schedule multiple timer callback events.

Default: Inf

'TimerFcn'

Character vector, string scalar, function handle, or cell array defining the timer callback function. You must define this property before you can start the timer.

  • 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.

'UserData'

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

Read Only Name-Value Pair Arguments

AveragePeriod

Average time in seconds between TimerFcn executions since the timer started. Value is NaN until timer executes two timer callbacks.

InstantPeriod

The time in seconds between the last two executions of TimerFcn. Value is NaN until timer executes two timer callbacks.

Running

Character vector defined as 'off' or 'on', indicating whether the timer is currently executing callback functions.

TasksExecuted

The number of times the timer called TimerFcn since the timer started.

Type

Character vector that identifies the object type.

Examples

expand all

Open Live Script

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');];

Find all the timers in memory. 

out1 = timerfind
out1=1×6 object
Timer Object Array

   Index:  ExecutionMode:  Period:  TimerFcn:               Name:
   1       fixedSpacing    30       @(~,~)logStack()        timer-1
   2       singleShot      1        ''                      timer-2
   3       singleShot      1        ''                      timer-3
   4       singleShot      1        ''                      timer-4
   5       singleShot      1        ''                      timer-5
   6       singleShot      1        ''                      timer-6

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

out2 = timerfind('Tag','displayProgress')
out2=1×3 object
Timer Object Array

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

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

out3 = timerfind(timerArr,'Tag','displayProgress')
out3=2×1 object
Timer Object Array

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

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

searchStruct = struct('Tag','broadcastProgress','UserData','Monday')
searchStruct = struct with fields:
         Tag: 'broadcastProgress'
    UserData: 'Monday'

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

out4 = timerfind(searchStruct)
out4 = 
   Timer Object: timer-2

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

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

Delete the timer objects. 

delete(t1)
delete(t2)
delete(timerArr)

Simulate having existing timers in memory by creating an array of timers. Create a new timer with a custom name. List all visible timers.

existingTimers = [timer timer timer];

myTimerName = 'myTimer';
anotherTimer = timer('Name',myTimerName);

timerfind
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        ''                      myTimer

Delete the specified timer and list all visible timers.

delete(timerfind('Name',myTimerName));
timerfind
Timer Object Array

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

Delete all visible timers from memory.

delete(timerfind)

Use timerfind to find ‘lost' timer object references. References are lost when you clear the timer object from the workspace, but do not delete it from memory.

Create two timer objects. Since the callback function does not require the timer or event object, you can use the tilde (~) operator to ignore the inputs in the function handle.

t1 = timer('TimerFcn',@(~,~)disp('Timer 1 Fired!'));
t2 = timer('TimerFcn',@(~,~)disp('Timer 2 Fired!'));
whos
  Name      Size            Bytes  Class    Attributes

  t1        1x1               104  timer              
  t2        1x1               104  timer

Clear one of the timer objects from the workspace. To actually remove the timer from memory, you need to both clear it and delete it. 

clear t1
whos
  Name      Size            Bytes  Class    Attributes

  t2        1x1               104  timer

Try to delete the timer, t1. 

delete(t1)
Undefined function or variable 't1'.

The timer, t1, cannot be removed from memory using delete because its reference has been cleared.

Find valid timer objects in memory.

out = timerfind
Timer Object Array

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

Since two timers were found, determine which timer does not exist in the workspace.

out ~= t2
ans =

     1     0

The first timer object in out is not equal to t2. This was previously t1. It is reassigned to t1. Since it is still valid, the timer can be started.

t1 = out(1);
start(t1)

Timer 1 Fired!

Delete timer objects. timerfind provides a way of accessing timer objects in memory. It does not copy the objects; therefore you do not need to delete out from memory. To verify, use timerfind.

delete(t1)
delete(t2)
timerfind
ans =

     []

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!'));

Clear two timers from the workspace.

clear t2 t3

Pass timerfind to delete to remove all timer objects from memory, whether or not they exist in the workspace.

delete(timerfind)
timerfind
ans =

     []

More About

expand all

Tips

  • timerfind only finds visible timer objects. Visible timer objects are those that are in memory and have the ObjectVisibility property set to 'on'. To find objects that are hidden, but still valid, use timerfindall.

See Also

| |

Introduced before R2006a

MATLAB Documentation

Support