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

Clock

type 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

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

sg	Scheduling group to run the callback under.
callback	function (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

callback

function (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

delta

the 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

until	the time when the timer expires
period	optional 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

delta

the 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

until	the time when the timer expires
period	optional 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

delta

the 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

callback

the 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

sg	the scheduling group under which the callback will be executed.
callback	the callback to be executed when the timer expires.

---

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

• seastar/core/timer.hh