timer

R2026b

MATLAB コマンドの実行のスケジュール

説明

timer を使用して、MATLAB^® コールバック関数で構成されたタスクの 1 つ以上の実行をスケジュールできます。複数回実行されるようにタイマーをスケジュールする場合は、タイマーのプロパティを調整して、実行間隔およびキューの競合の処理方法を指定できます。

timer オブジェクトはコールバック関数を使用してコマンドを実行します。コールバック関数は、何らかのイベント (timer の場合は時間の経過) の発生時にコードを実行します。timer オブジェクトでは、コールバック関数を関数ハンドルまたは文字ベクトルとして指定できます。コールバック関数が文字ベクトルの場合、MATLAB は実行可能コードとして評価します。timer オブジェクトでは、タイマーの開始時 (StartFcn)、実行時 (TimerFcn)、停止時 (StopFcn)、またはエラー発生時 (ErrorFcn) におけるコールバック関数がサポートされています。コールバック関数の関連情報の詳細については、タイマー コールバック関数を参照してください。

作成

構文

t = timer

t = timer(Name,Value)

説明

t = timer は、MATLAB コマンドの実行をスケジュールするための空の timer オブジェクトを作成します。タイマーを開始する前に、timer オブジェクトの TimerFcn プロパティを設定する必要があります。

タイマー t は、その動作を制御するプロパティをもっています。p = t.Property を使用してプロパティにアクセスし、t.Property = p を使用してプロパティを変更します。t のすべてのプロパティを保存するには A = get(t)、復元するには set(t,A) を使用できます。

t = timer(Name,Value) は、1 つ以上の Name-Value 引数を使用する追加のオプションを指定します。

プロパティ

コールバック関数のプロパティ

TimerFcn — タイマー コールバック関数

文字ベクトル | string スカラー | 関数ハンドル | cell 配列

タイマー コールバック関数。文字ベクトル、string スカラー、関数ハンドル、または cell 配列として指定します。タイマーを開始する前に、このプロパティを定義しなければなりません。

• 関数ハンドルを使用してこのプロパティを指定する場合、MATLAB がコールバックを実行すると、timer オブジェクトとイベント構造体をコールバック関数に渡します。イベント構造体には、Type フィールド内のイベントのタイプと Data フィールド内のイベントの時間が含まれます。

• 文字ベクトルまたは string スカラーを使用してこのプロパティを指定した場合、MATLAB は、コールバックの実行時にその文字ベクトルに含まれる MATLAB コードを評価します。コールバックを文字ベクトルとして定義することは推奨されていません。関数ハンドルとして指定された関数を使用すると、MATLAB でコールバック関数に重要な情報を渡すことができます。

• コールバック関数が、timer オブジェクトとイベント データに加えて引数を受け入れる場合、このプロパティを、関数ハンドルと追加引数が含まれる cell 配列として指定します。

詳細については、タイマー コールバック関数を参照してください。

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

StartFcn — タイマー開始コールバック関数

文字ベクトル | string スカラー | 関数ハンドル | cell 配列

タイマー開始コールバック関数。文字ベクトル、string スカラー、関数ハンドル、または cell 配列として指定します。

• 関数ハンドルを使用してこのプロパティを指定する場合、MATLAB がコールバックを実行すると、timer オブジェクトとイベント構造体をコールバック関数に渡します。イベント構造体には、Type フィールド内のイベントのタイプと Data フィールド内のイベントの時間が含まれます。

• 文字ベクトルまたは string スカラーを使用してこのプロパティを指定した場合、MATLAB は、コールバックの実行時にその文字ベクトルに含まれる MATLAB コードを評価します。コールバックを文字ベクトルとして定義することは推奨されていません。関数ハンドルとして指定された関数を使用すると、MATLAB でコールバック関数に重要な情報を渡すことができます。

• コールバック関数が、timer オブジェクトとイベント データに加えて引数を受け入れる場合、このプロパティを、関数ハンドルと追加引数が含まれる cell 配列として指定します。

詳細については、タイマー コールバック関数を参照してください。

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

StopFcn — タイマー停止コールバック関数

文字ベクトル | string スカラー | 関数ハンドル | cell 配列

タイマー停止コールバック関数。文字ベクトル、string スカラー、関数ハンドル、または cell 配列として指定します。

タイマーは、以下の状態のときに停止します。

• タイマーの stop メソッドを呼び出した場合。

• タイマーが TimerFcn の実行を終了した場合。つまり、TasksExecuted 値が TasksToExecute によって設定された制限に達した場合。

• エラーが発生します。ErrorFcn コールバックが最初に呼び出され、その後に StopFcn コールバックが呼び出されます。

StopFcn を使用して、メモリからの timer オブジェクトの削除などのクリーンアップ操作を定義できます。

• 関数ハンドルを使用してこのプロパティを指定する場合、MATLAB がコールバックを実行すると、timer オブジェクトとイベント構造体をコールバック関数に渡します。イベント構造体には、Type フィールド内のイベントのタイプと Data フィールド内のイベントの時間が含まれます。

• 文字ベクトルまたは string スカラーを使用してこのプロパティを指定した場合、MATLAB は、コールバックの実行時にその文字ベクトルに含まれる MATLAB コードを評価します。コールバックを文字ベクトルとして定義することは推奨されていません。関数ハンドルとして指定された関数を使用すると、MATLAB でコールバック関数に重要な情報を渡すことができます。

• コールバック関数が、timer オブジェクトとイベント データに加えて引数を受け入れる場合、このプロパティを、関数ハンドルと追加引数が含まれる cell 配列として指定します。

詳細については、タイマー コールバック関数を参照してください。

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

ErrorFcn — タイマー エラー コールバック関数

文字ベクトル | string スカラー | 関数ハンドル | cell 配列

タイマー エラー コールバック関数。文字ベクトル、string スカラー、関数ハンドル、または cell 配列として指定します。エラーが発生すると、この関数が実行され、StopFcn が呼び出されます。

• 文字ベクトルまたは string スカラーを使用してこのプロパティを指定した場合、MATLAB は、コールバックの実行時にその文字ベクトルに含まれる MATLAB コードを評価します。

• 関数ハンドルを使用してこのプロパティを指定する場合、MATLAB がコールバックを実行すると、timer オブジェクトとイベント構造体をコールバック関数に渡します。イベント構造体には、Type フィールド内のイベントのタイプと Data フィールド内のイベントの時間が含まれます。

• コールバック関数が、timer オブジェクトとイベント データに加えて引数を受け入れる場合、このプロパティを、関数ハンドルと追加引数が含まれる cell 配列として指定します。

詳細については、タイマー コールバック関数を参照してください。

例: t = timer("ErrorFcn","disp("An error has occurred")")

タイミング プロパティ

Period — 実行間の遅延

1 (既定値) | 数値スカラー

実行間の遅延。秒単位で 0.001 より大きい数値として指定します。タイマーで Period を使用するには、複数の timer オブジェクトのコールバック イベントのスケジュールを設定するように、ExecutionMode と TasksToExecute を設定しなければなりません。

例: t = timer("Period",5)

StartDelay — タイマーの開始と最初の実行との間の遅延

0 (既定値) | 数値スカラー

タイマーの開始と最初の実行との間の遅延。秒単位で 0 以上の数値として指定します。Running = "on" の場合、StartDelay は読み取り専用です。

例: t = timer("StartDelay",2)

TasksToExecute — タイマー コールバック関数の実行回数

数値スカラー

タイマー コールバック関数の実行回数。0 より大きい数値として指定します。TasksToExecute プロパティを使用して、実行回数を設定します。TasksToExecute を使用するには、複数のタイマー コールバック イベントのスケジュールを設定するように、ExecutionMode を設定しなければなりません。タイマーの実行中に TasksToExecute を変更しても、タイマー キューの状態によっては変更が即時に有効にならないことがあります。タイマー キューの関連情報の詳細については、タイマー キューの競合への対処を参照してください。

例: t = timer("TasksToExecute",5)

BusyMode — タイマー関数コールバックのキューイング

"drop" (既定値) | "error" | "queue"

タイマー関数コールバックのキューイング。次の表のいずれかの値として指定します。このプロパティを使用して、TimerFcn の前の実行が完了する前に、タイマーが TimerFcn を実行しなければならない場合に行う操作を指定します。Running プロパティが "on" に設定されている場合、BusyMode プロパティは読み取り専用です。

BusyMode プロパティが動作に影響するのは、ExecutionMode プロパティが FixedRate に設定されている場合のみです。ExecutionMode の他の値では、実行間の遅延が常に前の実行の完了を基準としているため、タイマー コールバック関数の実行がオーバーラップして試行されることはありません。

BusyMode 値	キューが空の場合の動作	キューが空でない場合の動作	メモ
"drop"	キューにタスクを追加	タスクを無視	場合によって、TimerFcn 呼び出しをスキップ
"error"	キューにタスクを追加	タスクを完了。ErrorFcn で指定されたエラーをスロー。タイマーを停止	現在実行されているタスクを完了した後、タイマーを停止
"queue"	キューにタスクを追加	キューが空になるまで待機してから、キューにタスクを格納	実行キューのタスクを管理するように、Period プロパティを調整

詳細については、タイマー キューの競合への対処を参照してください。

例: t = timer("BusyMode","error")

ExecutionMode — タイマー関数コールバックのスケジューリング

"singleShot" (既定値) | "fixedRate" | "fixedDelay" | "fixedSpacing"

タイマー関数コールバックのスケジューリング。次の表のいずれかの値として指定します。Running="on" の場合、ExecutionMode は読み取り専用です。次の表は、実行モードをまとめたものです。

実行モード	Period 時間の開始点
"singleShot"	タイマー コールバック関数は 1 回だけ実行されます。このため、Period プロパティは効果がありません。このモードは、既定の実行モードです。
"fixedRate"	タイマー コールバック関数を MATLAB 実行キューに追加した直後に開始します。
"fixedDelay"	MATLAB 実行キューの遅延に起因するタイム ラグ後、タイマー関数コールバックの実行が再開された後に開始します。
"fixedSpacing"	タイマー コールバック関数の実行が終了すると開始します。

• "singleShot" は、timer クラスに対する単一実行モードで、既定の値です。

  

• "fixedDelay"、"fixedRate" および "fixedSpacing" は、サポートされている 3 つのマルチ実行モードです。これらのモードは、Period プロパティの開始点を定義します。Period プロパティは、実行間の時間間隔 (実行間隔は同じ) を指定します。実行が始まる時点のみ異なります。

  

例: t = timer("ExecutionMode","fixedDelay")

ラベル付けプロパティ

Name — タイマーの名前

"timer-i" (既定値) | 文字ベクトル | string スカラー

タイマーの名前。文字ベクトルまたは string スカラーとして指定します。

既定では "timer-i" となります。ここで i はこのセッションで作成された i 番目の timer オブジェクトを示す番号です。

例: t = timer("Name","MyTimer")

Tag — オブジェクトのラベル

文字ベクトル | string スカラー

オブジェクトのラベル。文字ベクトルまたは string スカラーとして指定します。

例: t = timer("Tag","TimerTag")

ObjectVisibility — オブジェクトの可視性

"on" (既定値) | "off"

オブジェクトの可視性。"on" または "off" として指定します。アプリケーションによって作成された timer オブジェクトにエンドユーザーがアクセスすることを抑止できます。timerfind 関数は、ObjectVisibility プロパティが "off" に設定されているオブジェクトを返しません。オブジェクトは、表示されませんが有効です。表示されないものも含めて、メモリ内にあるすべての timer オブジェクトのリストを抽出するには、関数 timerfindall を使用します。

例: t = timer("ObjectVisibility","off")

UserData — ユーザー データ用のフィールド

任意の有効な MATLAB データ型

オブジェクトに追加するデータ用の汎用フィールド。

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

読み取り専用プロパティ

AveragePeriod — 実行間の平均時間

数値スカラー

実行間の平均時間。数値スカラーとして秒単位で指定します。タイマーが 2回、タイマー コールバックを実行するまで、値は NaN です。

InstantPeriod — 最新 2 回の実行の間隔

NaN (既定値) | 数値スカラー

最新 2 回の実行の間隔。数値スカラーとして秒単位で指定します。タイマーが 2回、タイマー コールバックを実行するまで、値は NaN です。

Running — コールバック関数のアクティブな実行を示すインジケーター

"off" | "on"

コールバック関数のアクティブな実行を示すインジケーター。"off" または "on" として指定します。

TasksExecuted — タイマーが実行された回数

数値スカラー

タイマーが実行された回数。数値スカラーとして指定します。

Type — オブジェクト タイプ

"timer" (既定値)

オブジェクト タイプを識別する文字ベクトル。

オブジェクト関数

delete	ファイルまたはオブジェクトを削除
get	グラフィックス オブジェクトのプロパティのクエリ
isvalid	有効なハンドルの判定
set	グラフィックス オブジェクトのプロパティの設定
start	タイマーの開始
startat	タイマーを指定時刻に始動するスケジュールの設定
stop	タイマーの停止
timerfind	timer オブジェクトの検索
timerfindall	すべての timer オブジェクトの検索
wait	タイマーが実行を停止するまでコマンド プロンプトをブロック

例

時間遅延後のメッセージの表示

timer オブジェクトを使用して、3 秒の時間遅延後にメッセージを表示します。

timer オブジェクトを作成します。TimerFcn プロパティを設定して、表示するメッセージを指定します。StartDelay プロパティを 3 に設定して、3 秒の時間遅延を指定します。

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

タイマーを開始します。

start(t)

3 秒後にメッセージが表示されます。

3 seconds have elapsed

コールバック関数の複数回の実行

タイマーが開始する日付と時刻を表示し、2 秒後にタイマーが停止する日付と時刻を表示します。

StartFcn プロパティをコールバック関数に設定して、タイマーが開始する日付と時刻を表示します。TimerFcn プロパティを設定して、タイマーの実行時に表示するメッセージを指定します。コールバック関数への最初の 2 つの引数は、timer オブジェクトと、Type および Data フィールドをもつイベント構造体です。同様に、StopFcn プロパティを設定して、タイマーが停止する日付と時刻を表示します。このタイマーは singleShot モードであるため、タイマーは 1 回実行されてから停止します。

t = timer;
t.StartFcn = @(~,thisEvent)disp(string(thisEvent.Type) + "Timer executed " + ...
    string(datetime(thisEvent.Data.time)));
t.StopFcn = @(~,thisEvent)disp(string(thisEvent.Type) + "Timer executed " + ...
    string(datetime(thisEvent.Data.time)));
t.TimerFcn = @(~,thisEvent)disp(string(thisEvent.Type) + "Timer executed " + ...
    string(datetime(thisEvent.Data.time)));
t.StartDelay = 2;
start(t)

StartFcnTimer executed 15-Oct-2025 15:23:07
TimerFcnTimer executed 15-Oct-2025 15:23:09
StopFcnTimer executed 15-Oct-2025 15:23:09

実行中は日付と時刻を 3 回表示します。メッセージ間に 2 秒一時停止します。次に、TasksToExecute および Period プロパティを使用して、メッセージを表示する回数および各メッセージ間の遅延を指定します。ExecutionMode では、TimerFcn が呼び出されたときに期間タイマーが開始することを指定します。

t.TasksToExecute = 3;
t.ExecutionMode = "fixedRate";
start(t)

StartFcnTimer executed 15-Oct-2025 15:27:54
TimerFcnTimer executed 15-Oct-2025 15:27:56
TimerFcnTimer executed 15-Oct-2025 15:27:57
TimerFcnTimer executed 15-Oct-2025 15:27:58
StopFcnTimer executed 15-Oct-2025 15:27:58

カスタム コールバック関数の定義

8 時間の期間にわたって 10 分ごとに 30 秒の人間工学的な休憩をとるように喚起する timer オブジェクトのリマインダーを作成します。

timer オブジェクトを返す関数 createErgoTimer を作成します。タイマーの開始時、実行中、停止時に行うタスクを指定する 3 つのローカル関数を含めます。

StartDelay を使用することで、すぐに休憩をとるように指示することなくタイマーを開始できます。実行モードを "fixedSpacing" に設定し、TimerFcn の実行の完了後に 10 分 30 秒 (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

timer オブジェクトを削除すると、timer オブジェクトはメモリから削除されます。

コマンド ラインで、関数 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 より前に導入

参考

delete | get | isvalid | set | start | startat | stop | timerfind | timerfindall | wait

トピック

• タイマー コールバック関数
• タイマー キューの競合への対処
• 関数出力の無視
• 関数ハンドルの作成
• プロパティの属性