Seastar
High performance C++ framework for concurrent servers
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
Public Types | Public Member Functions | List of all members
seastar::timer< Clock > Class Template Reference

Detailed Description

template<typename Clock = steady_clock_type>
class seastar::timer< Clock >

Timer - run a callback at a certain time point in the future.

Timer callbacks should execute quickly. If more involved computation is required, the timer should launch it as a fiber (or signal an existing fiber to continue execution). Fibers launched from a timer callback are executed under the scheduling group that was current when the timer was created (see current_scheduling_group()), or the scheduling that was given explicitly by the caller when the callback was specified.

Expiration of a timer<std::chrono::steady_clock> is independent of task_quota, so it has relatively high accuracy, but as a result this is a relatively expensive timer. It is recommended to use timer<lowres_clock> instead, which has very coarse resolution (~10ms) but is quite efficient. It is suitable for most user timeouts.

Template Parameters
Clocktype of clock used to denote time points; can be std::chrono::steady_clock_type (default), lowres_clock (more efficient but with less resolution) and manual_clock_type (fine-grained control for testing.

#include <seastar/core/timer.hh>

Public Types

typedef Clock::time_point time_point
 
typedef Clock::duration duration
 
typedef Clock clock
 
using set_t = timer_set< timer, &timer::_link >
 

Public Member Functions

 timer () noexcept
 Constructs a timer with no callback set and no expiration time.
 
 timer (timer &&t) noexcept
 
 timer (scheduling_group sg, noncopyable_function< void()> &&callback) noexcept
 
 timer (noncopyable_function< void()> &&callback) noexcept
 
 ~timer ()
 Destroys the timer. The timer is cancelled if armed.
 
void set_callback (scheduling_group sg, noncopyable_function< void()> &&callback) noexcept
 
void set_callback (noncopyable_function< void()> &&callback) noexcept
 
void arm (time_point until, std::optional< duration > period={}) noexcept
 
void rearm (time_point until, std::optional< duration > period={}) noexcept
 
void arm (duration delta) noexcept
 
void arm_periodic (duration delta) noexcept
 
void rearm_periodic (duration delta) noexcept
 
bool armed () const noexcept
 
bool cancel () noexcept
 
time_point get_timeout () const noexcept
 

Constructor & Destructor Documentation

◆ timer() [1/3]

template<typename Clock = steady_clock_type>
seastar::timer< Clock >::timer ( timer< Clock > &&  t)
inlinenoexcept

Constructs a timer from another timer that is moved from.

Note
care should be taken when moving a timer whose callback captures this, since the object pointed to by this may have been moved as well.

◆ timer() [2/3]

template<typename Clock = steady_clock_type>
seastar::timer< Clock >::timer ( scheduling_group  sg,
noncopyable_function< void()> &&  callback 
)
inlinenoexcept

Constructs a timer with a callback. The timer is not armed.

Parameters
sgScheduling group to run the callback under.
callbackfunction (with signature void ()) to execute after the timer is armed and expired.

◆ timer() [3/3]

template<typename Clock = steady_clock_type>
seastar::timer< Clock >::timer ( noncopyable_function< void()> &&  callback)
inlineexplicitnoexcept

Constructs a timer with a callback. The timer is not armed.

Parameters
callbackfunction (with signature void ()) to execute after the timer is armed and expired.

Member Function Documentation

◆ arm() [1/2]

template<typename Clock = steady_clock_type>
void seastar::timer< Clock >::arm ( duration  delta)
inlinenoexcept

Sets the timer expiration time.

It is illegal to arm a timer that has already been armed (and not disarmed by expiration or cancel()). In the current implementation, this will result in an assertion failure. See rearm().

Parameters
deltathe time when the timer expires, relative to now

◆ arm() [2/2]

template<typename Clock = steady_clock_type>
void seastar::timer< Clock >::arm ( time_point  until,
std::optional< duration >  period = {} 
)
noexcept

Sets the timer expiration time.

It is illegal to arm a timer that has already been armed (and not disarmed by expiration or cancel()). In the current implementation, this will result in an assertion failure. See rearm().

Parameters
untilthe time when the timer expires
periodoptional automatic rearm duration; if given the timer will automatically rearm itself when it expires, using the period to calculate the next expiration time.

◆ arm_periodic()

template<typename Clock = steady_clock_type>
void seastar::timer< Clock >::arm_periodic ( duration  delta)
inlinenoexcept

Sets the timer expiration time, with automatic rearming

Parameters
deltathe time when the timer expires, relative to now. The timer will also rearm automatically using the same delta time.

◆ armed()

template<typename Clock = steady_clock_type>
bool seastar::timer< Clock >::armed ( ) const
inlinenoexcept

Returns whether the timer is armed

Returns
true if the timer is armed and has not expired yet.

◆ cancel()

template<typename Clock = steady_clock_type>
bool seastar::timer< Clock >::cancel ( )
noexcept

Cancels an armed timer.

If the timer was armed, it is disarmed. If the timer was not armed, does nothing.

Returns
true if the timer was armed before the call.

◆ get_timeout()

template<typename Clock = steady_clock_type>
time_point seastar::timer< Clock >::get_timeout ( ) const
inlinenoexcept

Gets the expiration time of an armed timer.

Returns
the time at which the timer is scheduled to expire (undefined if the timer is not armed).

◆ rearm()

template<typename Clock = steady_clock_type>
void seastar::timer< Clock >::rearm ( time_point  until,
std::optional< duration >  period = {} 
)
inlinenoexcept

Sets the timer expiration time. If the timer was already armed, it is canceled first.

Parameters
untilthe time when the timer expires
periodoptional automatic rearm duration; if given the timer will automatically rearm itself when it expires, using the period to calculate the next expiration time.

◆ rearm_periodic()

template<typename Clock = steady_clock_type>
void seastar::timer< Clock >::rearm_periodic ( duration  delta)
inlinenoexcept

Sets the timer expiration time, with automatic rearming. If the timer was already armed, it is canceled first.

Parameters
deltathe time when the timer expires, relative to now. The timer will also rearm automatically using the same delta time.

◆ set_callback() [1/2]

template<typename Clock = steady_clock_type>
void seastar::timer< Clock >::set_callback ( noncopyable_function< void()> &&  callback)
inlinenoexcept

Sets the callback function to be called when the timer expires.

Parameters
callbackthe callback to be executed when the timer expires.

◆ set_callback() [2/2]

template<typename Clock = steady_clock_type>
void seastar::timer< Clock >::set_callback ( scheduling_group  sg,
noncopyable_function< void()> &&  callback 
)
inlinenoexcept

Sets the callback function to be called when the timer expires.

Parameters
sgthe scheduling group under which the callback will be executed.
callbackthe callback to be executed when the timer expires.

The documentation for this class was generated from the following file: