タイマーとアラーム

[アーティクル]
08/01/2024

Orleans ランタイムには、タイマーおよびアラームと呼ばれる 2 つのメカニズムが用意されており、開発者はグレインの定期的な動作を指定できます。

タイマー

タイマーは、複数のアクティブ化 (グレインのインスタンス化) にまたがる必要のないグレインの定期的な動作を作成するために使われます。タイマーは、標準的な .NET System.Threading.Timer クラスと同じです。さらに、タイマーは、それが動作するグレインアクティブ化内でのシングルスレッド実行保証の対象になります。また、その実行は、タイマーコールバックが AlwaysInterleaveAttribute でマークされたグレインメソッドであるかのように、他の要求とインターリーブされます。

各アクティブ化に、0 個以上のタイマーを関連付けることができます。ランタイムにより、各タイマールーチンが、それと関連付けられているアクティブ化のランタイムコンテキスト内で実行されます。

タイマーの使用方法

タイマーを開始するには、IDisposable の参照を返す RegisterGrainTimer メソッドを使います。

protected IDisposable RegisterGrainTimer(
    Func<object, Task> callback,        // function invoked when the timer ticks
    object state,                       // object to pass to callback
    GrainTimerCreationOptions options)  // timer creation options

タイマーをキャンセルするには、それを破棄します。

グレインが非アクティブ化された場合、または障害が発生してそのサイロがクラッシュした場合、タイマーはトリガーを停止します。

重要な考慮事項:

アクティブ化コレクションが有効になっている場合、タイマーコールバックの実行によってアクティブ化の状態がアイドルから使用中に変更されることはありません。つまり、タイマーを使って、それ以外の場合はアイドル状態のアクティブ化の非アクティブ化を延期することはできません。
Grain.RegisterGrainTimer に渡す期間は、callback によって返された Task が解決された時点から、callback の次の呼び出しを実行する必要がある時点までの経過時間です。これにより、callback の連続する呼び出しが重複できなくなるだけでなく、callback が完了するまでの時間の長さによって callback の呼び出し頻度が影響を受けるようになります。これは、System.Threading.Timer のセマンティクスからの重要な逸脱です。
callback の各呼び出しは個別のターンでアクティブ化に配信され、同じアクティブ化の他のターンと同時に実行されることはありません。ただし、callback の呼び出しはメッセージとして配信されないため、メッセージインターリーブセマンティクスの対象にはなりません。つまり、callback の呼び出しは、グレインが再入可能であるかのように動作し、他のグレイン要求と同時に実行されます。グレインの要求スケジューリングセマンティクスを使用するには、グレインメソッドを呼び出して、callback 内で行っていた作業を実行します。もう 1 つの方法は、AsyncLock または SemaphoreSlim を使うことです。詳しくは、Orleans GitHub issue #2574 をご覧ください。

リマインダー

アラームはタイマーに似ていますが、いくつかの重要な違いがあります。

アラームは永続的であり、明示的に取り消されない限り、ほぼすべての状況 (部分的または完全なクラスターの再起動を含む) でトリガーされ続けます。
アラームの "定義" は、ストレージに書き込まれます。ただし、特定の日時が指定された個々の特定の実行はそうではありません。これにより、特定のアラームティックの時点でクラスターがダウンした場合、そのアラームは実行されず、アラームの次のティックのみが実行されるという副作用があります。
アラームは、特定のアクティブ化ではなく、グレインに関連付けられます。
アラームのティックの時点でグレインにアクティブ化が関連付けられていない場合は、グレインが作成されます。アクティブ化がアイドル状態になり、非アクティブ化された場合、同じグレインに関連付けられているアラームにより、次のティックの時点で、グレインが再アクティブ化されます。
アラームの配信はメッセージを介して行われ、他のすべてのグレインメソッドと同じインターリーブセマンティクスの対象となります。
高頻度のタイマーには、アラームを使わないでください。アラームの期間は、分、時間、または日の単位で測定する必要があります。

構成

アラームは永続的であり、機能するためにストレージに依存します。アラームサブシステムが機能する前に、使用するストレージバッキングを指定する必要があります。これは、Use{X}ReminderService 拡張メソッドを使ってアラームプロバイダーの 1 つを構成することによって行います。X はプロバイダーの名前です (例: UseAzureTableReminderService)。

Azure Table の構成:

// TODO replace with your connection string
const string connectionString = "YOUR_CONNECTION_STRING_HERE";
var silo = new HostBuilder()
    .UseOrleans(builder =>
    {
        builder.UseAzureTableReminderService(connectionString)
    })
    .Build();

SQL:

const string connectionString = "YOUR_CONNECTION_STRING_HERE";
const string invariant = "YOUR_INVARIANT";
var silo = new HostBuilder()
    .UseOrleans(builder =>
    {
        builder.UseAdoNetReminderService(options =>
        {
            options.ConnectionString = connectionString; // Redacted
            options.Invariant = invariant;
        });
    })
    .Build();

Azure アカウントまたは SQL データベースを設定する必要なしに、アラームのプレースホルダー実装だけを機能させたい場合は、これによりアラームシステムの開発専用の実装が提供されます。

var silo = new HostBuilder()
    .UseOrleans(builder =>
    {
        builder.UseInMemoryReminderService();
    })
    .Build();

重要

サイロで複数の異なる種類の粒度を処理する (異なるインターフェイスを実装する) 異種クラスターを使用している場合、サイロ自体がアラームを処理しない場合でも、すべてのサイロでアラームの構成を追加する必要があります。

アラームの使用方法

アラームを使用するグレインは、IRemindable.ReceiveReminder メソッドを実装する必要があります。

Task IRemindable.ReceiveReminder(string reminderName, TickStatus status)
{
    Console.WriteLine("Thanks for reminding me-- I almost forgot!");
    return Task.CompletedTask;
}

アラームを開始するには、IGrainReminder オブジェクトを返す Grain.RegisterOrUpdateReminder メソッドを使います。

protected Task<IGrainReminder> RegisterOrUpdateReminder(
    string reminderName,
    TimeSpan dueTime,
    TimeSpan period)

reminderName: コンテキストグレインのスコープ内でアラームを一意に識別する必要がある文字列です。
dueTime: 最初のタイマーティックを発行するまでの待機時間を指定します。
period: タイマーの期間を指定します。

アラームは単一のアクティブ化の有効期間の間は存在し続けるため、(破棄されるのではなく) 明示的に取り消す必要があります。アラームをキャンセルするには、Grain.UnregisterReminder を呼び出します。

protected Task UnregisterReminder(IGrainReminder reminder)

reminder は、Grain.RegisterOrUpdateReminder によって返されるハンドルオブジェクトです。

IGrainReminder のインスタンスがアクティブ化の有効期間を超えて有効であることは保証されません。保持される方法でアラームを識別する場合は、アラームの名前を含む文字列を使用します。

アラームの名前のみがあり、IGrainReminder の対応するインスタンスが必要な場合は、Grain.GetReminder メソッドを呼び出します。

protected Task<IGrainReminder> GetReminder(string reminderName)

どちらを使用するか判断する

次の状況では、タイマーを使うことをお勧めします。

アクティブ化が非アクティブ化されたり、エラーが発生した場合に、タイマーが機能しなくなっても問題ない (またはそれが望ましい) 場合。
タイマーの最小単位が小さい (たとえば、秒または分単位で十分に表現できる)。
タイマーコールバックを、Grain.OnActivateAsync() から、またはグレインメソッドが呼び出されるときに、開始できる。

次の状況では、アラームを使うことをお勧めします。

アクティブ化やエラーが発生しても、定期的な動作が継続する必要がある場合。
頻度の低いタスクの実行 (分、時間、日単位で十分に表現できる)。