Hiva::CreateTimer

Description

Creates a timer.

Prototype

Hiva::Timer Hiva::CreateTimer(const Hiva::HivaDuration &timerPeriod, const TimerCallback &timerCb, const std::string &groupName, const bool oneshot = false, const bool autostart = true)

Parameters

Parameter

Input/Output

Description

timerPeriod

Input

Period for triggering the callback function. The value is of the standard Duration type for the framework.

timerCb

Input

Callback function used after a timer expires. The type is TimerCallback. TimerEvent is defined as follows:

using TimerCallback = std::function<void (const TimerEvent &)>;

struct TimerEvent
{
    Time last_expected;     // Time when the last callback should occur
    Time last_real;         // Time when the last callback occurs
    Time last_expired;      // Time when the last timer expires on the timer server and a notification is sent to the application
    Time current_expected;  // Time when the current callback should occur
    Time current_real;      // Actual time when the current callback occurs
    Time current_expired;   // Time when the current timer expires on the timer server and a notification is sent to the application
    struct{
    Hiva::WallDuration last_duration;  // Last callback execution duration
    } profile;
};

groupName

Input

Thread group created when OpenHiva::Init is invoked. For a deterministic group, the deterministic scheduling framework is used. For other groups, the OS scheduling framework is used.

oneshot

Input

Mode flag.

true indicates that the one-off oneshot mode is used and the timer is triggered only once.
false indicates that the periodic mode is used. The timer is triggered periodically until the process resources are cleared.

autostart

Input

Start flag.

true indicates that the timer is automatically started. When the interface returns a value, the timer is started.
false indicates that the timer is not automatically started. When the interface returns a value, the timer is not started and needs to be manually started through Hiva::Timer::Start.

Returns

The handle of Hiva::Timer is returned. The start and stop operations can be performed based on this handle.

Usage

A process invokes this interface to create and run a timer.

When creating a timer, an application subscribes to a timer event. The timer name is generated in the format of application name + timer + sequence number to ensure uniqueness.
The application sends the timer name and related information to the timer server through the topic communication mode of the server/client. After the time expires, the timer server publishes the topic, notifies the original application, and executes the user callback function.
Timer topics are in independent groups and do not conflict with service thread groups. Therefore, concurrency is allowed.

Precautions

This interface preferentially uses the Hiva clock source. If there is no Hiva clock, the system wall clock is used.
For deterministic timers, the input group will be used to subscribe to timer events, and the events subscribed to by this group will be canceled.
The timer created by invoking this interface uses the built-in scheduled wakeup mechanism of the OS and does not use the high-precision user-mode timer based on the hardware timer. If the Hiva clock is not used and a high-precision clock is required, invoke Hiva::CreateWallTimer and Hiva::CreateSteadyTimer.
You are advised to determine whether to use the simulation time (Hiva clock source) immediately when starting the timer to avoid switching to the wall clock. The timer is not notified of the clock source switchover. Therefore, the clock source may have been switched, but the timer is still using the clock source before the switchover.
If the simulation time is switched, you need to restart the node so that the node can work properly based on the new clock source.

Parent topic: Timer