Main Content

timer

调度 MATLAB 命令的执行

说明

使用 timer 调度由 MATLAB® 回调函数组成的任务的一次或多次执行。如果您调度一个计时器多次执行命令,您可以通过调整该计时器的属性,指定各次执行之间的时间间隔以及如何处理排队冲突。

timer 对象使用回调函数执行命令。回调函数在出现某个事件时执行代码,对于 timer 来说就是历时。对于 timer 对象,您可以将回调函数指定为函数句柄或字符向量。如果回调函数是字符向量,MATLAB 将以可执行代码形式对其求值。当计时器启动 (StartFcn)、执行 (TimerFcn)、停止 (StopFcn) 或遇到错误 (ErrorFcn) 时,计时器对象支持回调函数。有关回调函数的详细信息,请参阅计时器回调函数

创建对象

描述

示例

t = timer 创建一个空的 timer 对象,以排定 MATLAB 命令的执行。启动计时器之前,必须为计时器对象设置 TimerFcn 属性。

计时器 t 具有控制其行为的属性。使用 p = t.Property 访问属性,并使用 t.Property = p 修改属性。要保存和还原 t 的所有属性,您可以分别使用 A = get(t)set(t,A)

示例

t = timer(Name,Value) 指定使用一个或多个 Name-Value 参数的其他选项。

属性

全部展开

回调函数属性

计时器回调函数,指定为字符向量、字符串标量、函数句柄或元胞数组。您必须定义此属性,才能启动计时器。

  • 如果您使用函数句柄指定此属性,当 MATLAB 执行回调时,它会将 timer 对象和事件结构体传递给回调函数。事件结构体的 Type 字段中包含事件的类型,Data 字段中包含事件的时间。

  • 如果您使用字符向量或字符串标量指定此属性,则当 MATLAB 执行回调时,它会对字符向量中包含的 MATLAB 代码求值。不建议将回调定义为字符向量。将函数指定为函数句柄的用法可以让 MATLAB 为回调函数提供重要信息。

  • 如果回调函数接受除 timer 对象和事件数据以外的参数,请将此属性指定为包含函数句柄和其他参数的元胞数组。

有关详细信息,请参阅计时器回调函数

示例: t = timer('TimerFcn',"MyTimerFunction(Input);")

计时器启动回调函数,指定为字符向量、字符串标量、函数句柄或元胞数组。

  • 如果您使用函数句柄指定此属性,当 MATLAB 执行回调时,它会将 timer 对象和事件结构体传递给回调函数。事件结构体的 Type 字段中包含事件的类型,Data 字段中包含事件的时间。

  • 如果您使用字符向量或字符串标量指定此属性,则当 MATLAB 执行回调时,它会对字符向量中包含的 MATLAB 代码求值。不建议将回调定义为字符向量。将函数指定为函数句柄的用法可以让 MATLAB 为回调函数提供重要信息。

  • 如果回调函数接受除 timer 对象和事件数据以外的参数,请将此属性指定为包含函数句柄和其他参数的元胞数组。

有关详细信息,请参阅计时器回调函数

示例: t = timer('StartFcn',@MyStartFunction(~,~))

计时器停止回调函数,指定为字符向量、字符串标量、函数句柄或元胞数组。

计时器会在以下情况下停止:

  • 调用计时器 stop 方法。

  • 计时器完成执行 TimerFcn。换句话说,TasksExecuted 的值达到 TasksToExecute 设置的限值。

  • 出现错误。首先调用 ErrorFcn 回调,然后调用 StopFcn 回调。

您可以使用 StopFcn 定义清理操作,例如删除内存中的计时器对象。

  • 如果您使用函数句柄指定此属性,当 MATLAB 执行回调时,它会将 timer 对象和事件结构体传递给回调函数。事件结构体的 Type 字段中包含事件的类型,Data 字段中包含事件的时间。

  • 如果您使用字符向量或字符串标量指定此属性,则当 MATLAB 执行回调时,它会对字符向量中包含的 MATLAB 代码求值。不建议将回调定义为字符向量。将函数指定为函数句柄的用法可以让 MATLAB 为回调函数提供重要信息。

  • 如果回调函数接受除 timer 对象和事件数据以外的参数,请将此属性指定为包含函数句柄和其他参数的元胞数组。

有关详细信息,请参阅计时器回调函数

示例: t = timer('StopFcn',@MyStopFunction(~,~))

计时器错误回调函数,指定为字符向量、字符串标量、函数句柄或元胞数组。如果出现错误,将会执行此函数,然后调用 StopFcn

  • 如果您使用字符向量或字符串标量指定此属性,则当 MATLAB 执行回调时,它会对字符向量中包含的 MATLAB 代码求值。

  • 如果您使用函数句柄指定此属性,当 MATLAB 执行回调时,它会将 timer 对象和事件结构体传递给回调函数。事件结构体的 Type 字段中包含事件的类型,Data 字段中包含事件的时间。

  • 如果回调函数接受除 timer 对象和事件数据以外的参数,请将此属性指定为包含函数句柄和其他参数的元胞数组。

有关详细信息,请参阅计时器回调函数

示例: t = timer('ErrorFcn','disp("An error has occured")')

计时属性

各次执行之间的延迟,以秒为单位,指定为大于 0.001 的数字。要使计时器使用 Period,您必须设置 ExecutionModeTasksToExecute 以排定多个计时器对象回调事件的执行。

示例: t = timer('Period',5)

计时器启动和第一次执行之间的延迟,以秒为单位,指定为大于或等于 0 的数字。如果 Running = 'on',则 StartDelay 是只读的。

示例: t = timer('StartDelay',2)

计时器回调函数执行的次数,指定为大于 0 的数字。使用 TasksToExecute 属性设置执行次数。要使用 TasksToExecute,您必须设置 ExecutionMode 以排定多个计时器回调事件的执行。根据计时器队列的状态,在计时器运行时更改 TasksToExecute 可能不会立即生效。有关计时器队列的详细信息,请参阅处理计时器队列冲突

示例: t = timer('TasksToExecute',5)

计时器函数回调排队,指定为下表中的值之一。使用此属性可以指定在计时器必须在上一次 TimerFcn 执行完毕之前再次执行 TimerFcn 时需采取的操作。当 Running 属性设置为 'on' 时,BusyMode 属性为只读。

仅当 ExecutionMode 属性设置为 FixedRate 时,BusyMode 属性才会影响行为。对于 ExecutionMode 的其他值,执行计时器回调函数的多次尝试之间不能存在重叠,因为各次执行之间的延迟始终是相对于前一次执行的完成而言的。

BusyMode

队列为空时的行为

队列不为空时的行为

注释

'drop'

将任务添加到队列中

放弃任务

可能跳过 TimerFcn 调用

'error'

将任务添加到队列中

完成任务;引发 ErrorFcn 指定的错误;停止计时器

完成当前正在执行的任务后停止计时器

'queue'

将任务添加到队列中

等待队列清除,然后使任务进入队列中

调整 Period 属性以管理执行队列中的任务

有关详细信息,请参阅处理计时器队列冲突

示例: t = timer('BusyMode','error')

计时器函数回调调度,指定为下表中的值之一。当 Running='on' 时,ExecutionMode 为只读。下表概述了执行模式。

执行模式

时间 Period 起点

'singleShot'

计时器回调函数只执行一次。因此,Period 属性没有任何作用。此模式是默认执行模式。

'fixedRate'

在将计时器回调函数添加到 MATLAB 执行队列中后立即启动。

'fixedDelay'

在计时器回调函数经过一段时滞(因 MATLAB 执行队列中出现延迟)后重新开始执行时启动。

'fixedSpacing'

在计时器回调函数完成执行时启动。

  • 'singleShot'timer 类的单次执行模式,并且是默认值。

    Schematic of timing of 'singleShot' execution mode.

  • 'fixedDelay''fixedRate''fixedSpacing' 是三个受支持的多次执行模式。这些模式定义 Period 属性的起点。Period 属性指定执行之间的间隔时间(保持不变)。只有执行起点是不同的。

    Schematic of timing of 'fixedDelay' execution mode.

示例: t = timer('ExecutionMode','fixedDelay')

标注属性

计时器名称,指定为字符向量或字符串标量。

默认值为 'timer-i',其中 i 是一个数字,指示第 i 个计时器对象创建了此会话。

示例: t = timer('Name','MyTimer')

对象标签,指定为字符向量或字符串标量。

示例: t = timer('Tag','TimerTag')

对象可见性,指定为 'on''off',您可以利用它来阻止最终用户访问应用程序所创建的计时器对象。timerfind 函数不会返回 ObjectVisibility 属性设置为 'off' 的对象。不可见的对象仍然有效。要检索内存中的所有计时器对象(包括不可见对象)的列表,请使用 timerfindall 函数。

示例: t = timer('ObjectVisibility','off')

要向对象添加的数据的一般字段。

示例: t = timer('UserData',"This is my first timer!")

只读属性

各次执行之间的平均时间,以秒为单位,指定为数值标量。在计时器执行完两次计时器回调之前,该值一直为 NaN

最后两次执行之间的时间,以秒为单位,指定为数值标量。在计时器执行完两次计时器回调之前,该值一直为 NaN

主动执行回调函数的指示符,指定为 'off''on'

计时器已执行的次数,指定为数值标量。

标识对象类型的字符向量。

对象函数

delete删除文件或对象
get查询图形对象属性
isvalid确定有效句柄
set设置图形对象属性
start启动计时器
startat排定计时器在指定时间触发回调
stop停止计时器
timerfind查找计时器对象
timerfindall查找所有计时器对象
wait阻止命令提示符直到计时器停止运行

示例

全部折叠

使用计时器对象在 3 秒的时滞后显示消息。

创建一个 timer 对象。通过设置 TimerFcn 属性来指定要显示的消息。通过将 StartDelay 属性设置为 3,指定 3 秒的时滞。

t = timer;
t.StartDelay = 3;
t.TimerFcn = @(~,~)disp('3 seconds have elapsed');

启动计时器。

start(t)

三秒后,显示消息。

3 seconds have elapsed

计时器启动时显示日期时间,2 秒后计时器停止时再次显示。

通过将 StartFcn 属性设置为回调函数来显示计时器启动时的日期时间。回调函数的前两个参数是 timer 对象和具有 TypeData 字段的事件结构体。同样,通过设置 StopFcn 属性来显示计时器停止时的日期时间。

t = timer;
t.StartFcn = @(~,thisEvent)disp([thisEvent.Type ' executed '...
    datestr(thisEvent.Data.time,'dd-mmm-yyyy HH:MM:SS.FFF')]);
t.StopFcn = @(~,thisEvent)disp([thisEvent.Type ' executed '...
    datestr(thisEvent.Data.time,'dd-mmm-yyyy HH:MM:SS.FFF')]);
t.Period = 2;
start(t)
StartFcn executed 14-Jan-2020 09:08:50.865
StopFcn executed 14-Jan-2020 09:08:52.869

在执行过程中显示日期时间三次,消息之间暂停两秒。通过设置 TimerFcn 属性来指定要显示的消息。然后,使用 TasksToExecutePeriod 属性指示显示消息的次数和每条消息之间的延迟。ExecutionMode 指定在调用 TimerFcn 时即启动周期计时器。。

t.TimerFcn = @(~,thisEvent)disp([thisEvent.Type ' executed '...
     datestr(thisEvent.Data.time,'dd-mmm-yyyy HH:MM:SS.FFF')]);
t.TasksToExecute = 3;
t.ExecutionMode = 'fixedRate';
start(t)
StartFcn executed 14-Jan-2020 09:08:50.865
TimerFcn executed 14-Jan-2020 09:08:50.865
TimerFcn executed 14-Jan-2020 09:08:52.865
TimerFcn executed 14-Jan-2020 09:08:54.866
StopFcn executed 14-Jan-2020 09:08:54.869

创建一个计时器对象,以提醒在 8 小时工作期间,每 10 分钟做一次时长 30 秒的人体工学运动休息。

创建一个返回 timer 对象的函数 createErgoTimer。包括三个局部函数,用于指定计时器启动、执行和停止时的任务。

使用 StartDelay 可以先启动计时器,而不提示您立即休息。将执行模式设置为 'fixedSpacing',使完成 TimerFcn 执行花费的时间为 1030 秒 (t.Period)。在下一个 10 分钟间隔开始之前,您可以留出 30 秒的休息时间。

function t = createErgoTimer()

t = timer;
t.StartFcn = @ergoTimerStart;
t.TimerFcn = @takeBreak;
t.StopFcn = @ergoTimerCleanup;

% 10 minutes between breaks + 30 second break
t.Period = 600+30;

% time till first break
t.StartDelay = t.Period-30; 

% Number of breaks during 8-hr period
t.TasksToExecute = ceil(8*60^2/t.Period);
t.ExecutionMode = 'fixedSpacing';
end 

添加一个与计时器启动相关联的局部函数回调。由 StartFcn 执行的任务显示消息,指示人体工学计时器已开始。默认情况下,timer 对象将其自身和事件数据传递给回调函数。该函数会忽略事件数据。

function ergoTimerStart(mTimer,~)
disp("Starting Ergonomic Break Timer." + newline +...
"For the next 8 hours you will be notified " +...
"to take a 30 second break every 10 minutes.")
end

添加一个局部回调函数,该函数显示一条提醒您休息 30 秒的消息。

function takeBreak(mTimer,~)
disp('Take a 30 second break.')
end

添加一个局部回调函数来处理与停止计时器关联的任务。

function ergoTimerCleanup(mTimer,~)
disp('Stopping Ergonomic Break Timer.')
delete(mTimer)
end

删除计时器对象会将其从内存中移除。

在命令行中,调用 createErgoTimer 函数以创建和启动计时器。

t = createErgoTimer;
start(t)
Starting Ergonomic Break Timer.
For the next 8 hours you will be notified to take a 30 second break every 10 minutes.

每隔 10 分钟,系统会提醒您休息 30 秒。

Take a break.

您可以使计时器在 8 小时内保持运行,或者将其手动停止。StopFcn 回调包括从内存中删除计时器的任务。

stop(t)
Stopping Ergonomic Break Timer.

局限性

  • timer 对象受到您的硬件、操作系统和软件的限制。应避免对实时应用程序使用 timer 对象。如果 MATLAB 正忙于处理另一个任务,计时器回调可能不会执行。

  • 不推荐在计时器回调函数中使用 wait

提示

  • 要强制执行事件队列中的回调函数,请包含对 drawnow 函数的调用。drawnow 函数会刷新事件队列。

版本历史记录

在 R2006a 之前推出