名称

zmq_timers - 跨平台定时器回调的辅助函数

概要

typedef void(zmq_timer_fn) (int 'timer_id', void *'arg');

void *zmq_timers_new (void);

int zmq_timers_destroy (void **'timers_p');*

int zmq_timers_add (void *'timers', size_t 'interval', zmq_timer_fn 'handler', void *'arg');

int zmq_timers_cancel (void *'timers', int 'timer_id');

int zmq_timers_set_interval (void *'timers', int 'timer_id', size_t 'interval');

int zmq_timers_reset (void *'timers', int 'timer_id');

long zmq_timers_timeout (void *'timers');

int zmq_timers_execute (void *'timers');

描述

zmq_timers 系列函数提供跨平台访问定时器回调的功能。定时器注册后，会按指定的间隔重复触发，直到被手动取消。要运行回调，必须调用 zmq_timers_execute。

zmq_timers_new 和 zmq_timers_destroy 管理定时器实例的生命周期。zmq_timers_new 创建并返回一个新的定时器实例，而 zmq_timers_destroy 销毁它。必须将指向有效定时器的指针作为 zmq_timers_destroy 的 timers_p 参数传入。特别地，对于同一个定时器实例，zmq_timers_destroy 不可以被多次调用。成功执行时，zmq_timers_destroy 会将传入的指针设置为 NULL。

zmq_timers_add 和 zmq_timers_cancel 管理已注册的定时器。

zmq_timers_add 为给定实例注册一个新的*定时器*。*timers* 必须指向一个有效的 *timers* 对象。*interval* 参数指定定时器的过期时间，单位为毫秒。*handler* 和 *arg* 指定过期时将调用的回调函数以及可选的透传参数。回调必须是实现 zmq_timer_fn 原型的有效函数。函数将返回一个 ID，可用于修改或取消定时器。

zmq_timers_cancel 将取消实例 timers 中与 timer_id 关联的定时器。

zmq_timers_set_interval 将实例 timers 中与 timer_id 关联的定时器的过期时间设置为从现在起 interval 毫秒之后。

zmq_timers_reset 将重新启动实例 timers 中与 timer_id 关联的定时器。

zmq_timers_timeout 将返回注册到 timers 中的下一个即将过期的定时器剩余的时间，单位为毫秒。

zmq_timers_execute 将运行实例 timers 中所有已过期定时器的回调函数。

线程安全

与大多数其他 0MQ 对象一样，定时器不是线程安全的。所有操作必须从同一线程调用。否则，行为是未定义的。

返回值

zmq_timers_new 总是返回指向一个定时器的有效指针。

所有返回 int 类型的函数在失败时返回 -1。在这种情况下，可以使用 zmq_errno() 查询错误类型，如下所述。

zmq_timers_timeout 返回注册到 timers 中的下一个即将过期的定时器剩余的时间，单位为毫秒；如果没有剩余的定时器，则返回 -1。

所有其他函数在成功执行时返回 0。

错误

对于 zmq_timers_destroy、zmq_timers_cancel、zmq_timers_set_interval、zmq_timers_reset、zmq_timers_timeout 和 zmq_timers_execute：EFAULT:: timers 没有指向有效的定时器。请注意，传递无效指针（例如，指向已释放内存的指针）可能导致未定义的行为（例如，访问冲突）。

对于 zmq_timers_add：EFAULT:: timers 没有指向有效的定时器，或者 handler 没有指向有效的函数。

对于 zmq_timers_cancel、zmq_timers_set_interval 和 zmq_timers_timeout：EINVAL:: timer_id 不存在或已被取消。

示例

添加一个带简单回调函数的定时器，该回调函数改变一个布尔值。
    void handler (int timer_id_, void *arg_)
    {
        (void) timer_id_; //  Stop 'unused' compiler warnings
        *((bool *) arg_) = true;
    }

    ...

    void *timers = zmq_timers_new ();
    assert (timers);

    bool timer_invoked = false;

    const unsigned long full_timeout = 100;

    int timer_id =
      zmq_timers_add (timers, full_timeout, handler, &timer_invoked);
    assert (timer_id);

    //  Timer should not have been invoked yet
    int rc = zmq_timers_execute (timers);
    assert (rc == 0);

    //  Wait half the time and check again
    long timeout = zmq_timers_timeout (timers);
    assert (rc != -1);
    msleep (timeout / 2);
    rc = zmq_timers_execute (timers);
    assert (rc == 0);

    // Wait until the end
    rc = msleep (zmq_timers_timeout (timers));
    assert (rc == 0);

    // The handler will be executed
    rc = zmq_timers_execute (timers);
    assert (rc == 0);
    assert (timer_invoked);

    rc = zmq_timers_destroy (&timers);
    assert (rc == 0);

另请参阅

作者

此页面由 0MQ 社区编写。要做出修改，请阅读 0MQ 贡献政策：https://zeromq.cn/how-to-contribute/。