Grain Timers and Reminders

Orleans 提供了 Timers 和 Reminders两种机制。

Timers

计时器与 .NET 里提供的 System.Threading.Timer 类基本相同。此外，计时器在单独的线程上执行。如果有多个与之关联的计时器，在运行时会进行上下文切换去执行每个计时器。

用法：

要启动计时器，直接使用 RegisterTimer 方法就可以，该方法在 Grain 类中实现，方法参数说明：

Func<object, Task> asyncCallback // 计时器开始计时调用的函数
object state                     // asyncCallback 函数所需参数
TimeSpan dueTime                 // 启动到第一次执行间隔的时间量
TimeSpan period                  // 等行为下一次执行间隔的时间量

方法返回一个 IDisposable 句柄，通过 Dispose 方法来停止计时器。

另外，一旦 Grain 被停用或者 Silo 崩坏，计时器将停止触发。

接下来我们看下使用的代码：

public interface ITimerGrain : IGrainWithIntegerKey
{
    Task Start();
    Task Finish();
}
public class TimerGrain : Grain, ITimerGrain
{
    private readonly ILogger logger;

    private IDisposable? disposable;

    public TimerGrain(ILogger<HelloGrain> logger)
    {
        this.logger = logger;
    }

    public Task Start()
    {
        disposable = RegisterTimer(o =>
                                   {
                                       logger.LogInformation($"time tick = {DateTime.Now}\n ");
                                       return Task.CompletedTask;
                                   }, null, TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(5));

        return Task.CompletedTask;
    }

    public Task Finish()
    {
        if (disposable != null)
        {
            logger.LogInformation($"计时器停止--{DateTime.Now}\n");
            disposable.Dispose();
            disposable = null;
        }

        return Task.CompletedTask;
    }
}

client 调用

var timerGrain = client.GetGrain<ITimerGrain>(1);
await timerGrain.Start();

//休息个10秒钟再来取消计时器
Thread.Sleep(10000);

await timerGrain.Finish();

计时器的用法比较简单，但我们也要注意如下事项：

• 启用收集 Grain 时，计时器不会将 Grain 激活的状态从空闲更改为使用中。不会因计时器在执行回调函数而推迟取消激活原本空闲的 Grain 。Grain 一旦被停用，那么定时器也将被丢弃。

• 从 asyncCallback 返回的 Task 被解析之前，不会执行下一次 asyncCallback 。 计时器永远不会重叠调用 asyncCallback。而且 asyncCallback 所需要的执行时间会影响到调用 asyncCallback 的频率。这与 System.Threading.Timer 一个很重要的不同点。

• 任何由 asyncCallback 返回的异常或错误的 Task 都会被记录，但不会阻止下一次 asyncCallback 进入队列。

• asyncCallback 调用不会作为消息传递，因此它不会受消息交互场景的影响。

以上就是 Timers 的用法。接下来看下 Reminders 。

Reminders

Reminders 翻译过来为提醒，但我觉得这不太贴切，所以就保留英文。Reminders 与计时器有类似的地方，我们先看它的用法，最后再来说它们之间的区别。

Reminders 要依赖存储，所以在使用之前要指定存储方式。存储方式可以在 Silo 配置，创建 SiloHostBuilder 对象时调用 UseXReminderService 扩展方法进行配置，其中 X 是存储方式名称。例如：我使用 MySql 数据库，在配置之前先添加 NuGet 引用 Microsoft.Orleans.Reminders.AdoNet 和 MySql.Data ，具体的配置如下：

.UseAdoNetReminderService(options => 
    {
        options.ConnectionString = "Server=localhost;Port=3306;Database=yld;Uid=root;Pwd=mysql;";
        options.Invariant = "MySql.Data.MySqlClient";
    })

除了 SQL 数据库，还支持如下图：

每个具体的配置方案这里就不介绍，相信都会。另外，Orleans 还提供了一个开发环境下使用的内存存储方式，其配置比较简单直接使用 UseInMemoryReminderService 方法即可。

这里我就使用 MySql 来做示例。

先做些准备工作，创建一个数据，这里数据库名称就叫 yld 。然后到 Github 上下载 MySQL-Reminders.sql 的数据库脚本 。执行脚本，准备工作完成。 接下来按下面步骤启动一个 Reminders 。

1、定义一个 IReminderGrain 接口如下：

public interface IReminderGrain : IGrainWithIntegerKey
{
    Task Execute();
    Task Cancel();
}

2、定义一个 ReminderGrain 类，该类继承 Grain 和 IReminderGrain 、IRemindable 接口。

3、实现 IRemindable 接口里的 ReceiveReminder 方法。

4、在 Execute 方法调用 Grain 类的 RegisterOrUpdateReminder 方法，进行注册。该方法参数说明如下：

string reminderName     // 设置名称，该名称必须唯一
TimeSpan dueTime        // 启动到第一次执行间隔的时间量
TimeSpan period         // 等行为下一次执行间隔的时间量

该方法返回一个 IGrainReminder 。

5、通过 Grain 类的 UnregisterReminder 方法可以取消 Reminders ，该方法接收一个 IGrainReminder 参数。IGrainReminder 可以通过 Grain 类的 GetReminder 方法获取，GetReminder 方法是通过名称来获取 IGrainReminder 。

完整代码如下：

public class ReminderGrain : Grain, IReminderGrain, IRemindable
{
    private IGrainReminder? reminder;
    private readonly ILogger logger;

    public ReminderGrain(ILogger<HelloGrain> logger)
    {
        this.logger = logger;
    }
    public Task Cancel()
    {
        if (reminder != null)
        {
            logger.LogInformation($"结束 Reminider --{DateTime.Now}\n");
            UnregisterReminder(reminder);
        }

        return Task.CompletedTask;
    }

    public async Task Execute()
    {
        reminder = await RegisterOrUpdateReminder("Reminder Demo", TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(60));
    }

    public Task ReceiveReminder(string reminderName, TickStatus status)
    {
        logger.LogInformation($"执行 Reminider --{DateTime.Now}\n");
        return Task.CompletedTask;
    }
}

client 调用

var reminderGrain = client.GetGrain<IReminderGrain>(1);
await reminderGrain.Execute();

Console.WriteLine("待待 120 秒 ...");
Thread.Sleep(120000);

Console.WriteLine("Reminder 停止--" + DateTime.Now);
await reminderGrain.Cancel();

Reminders 启动时会在数据库表 orleansreminderstable 中新增一条记录。暂停 Reminder 时会把该条记录删除。

完整代码，放在 github 上。

Timers 与 Reminders 区别

• Reminders 是持久的，因为它通过存储，保证在部分或全部集群重启时可以继承触发，除非明确取消

• Reminders 不会特定的时间去执行特定的任务，这样会错过时间执行任务，只能执行下一次任务。

• Reminders 与 Grain 是相互关联，无需单独激活。

• 如果 Reminders 还在执行中，而没有 Grain 可以关联，则会自动创建一个 Grain 。如果 Grain 状态变为空闲且被停用，则将会在下一次执行时激活该 Grain。

• Reminders 可以通过消息传递，并受制于其它 grain 方法的交互场景。

• Reminders 不是一个高频计时器，最小单位为 1 分钟。它的周期以分钟，小时或天为单位。不能以秒为单位会报错。

如何选择

• grain 停用或 silo 崩掉，计时器会停止作业从而影响任务的执行，而 Reminders 不会。如果对任务执行比较重要，要求比较高，集群重启不影响任务执行，那就选 Reminders 。否则，就选择 Timers 。

• 计时器的作业频率快，以秒或分钟为单元。而 Reminders 执行一些频率比较慢的任务，例如：以分钟、小时或天为单位。

• 计时器可以在调用 grain 方法启动或在 Grain 类的 OnActivateAsync 方法启动。

Timers 和 Reminders 的 dueTime 参数尽量不设置为 0 。

 最后，祝大家学习愉快！