xtd::threading::timer Class Reference

Definition

Provides a mechanism for executing a method on a thread pool thread at specified intervals. This class cannot be inherited.

class core_export_ timer final : public xtd::object

Inheritance

xtd::object → xtd::threading::timer

Header

#include <xtd/threading/timer> 

Namespace

xtd::threading

Library

xtd.core

Examples

The following example defines a status_checker class that includes a check_status method whose signature is the same as the xtd::threading::timer_callback delegate. The state argument of the check_status method is an xtd::threading::auto_reset_event object that is used to synchronize the application thread and the thread pool thread that executes the callback delegate. The status_checker class also includes two state variables: invoke_count Indicates the number of times the callback method has been invoked. max_count Determines the maximum number of times the callback method should be invoked. The application thread creates the timer, which waits one second and then executes the check_status callback method every 250 milliseconds. The application thread then blocks until the xtd::threading::auto_reset_event object is signaled. When the check_status callback method executes max_count times, it calls the auto_reset_event::set method to set the state of the xtd::threading::auto_reset_event object to signaled. The first time this happens, the application thread calls the xtd::threading::timer::change(int32, int32) method so that the callback method now executes every half second. It once again blocks until the xtd::threading::auto_reset_event object is signaled.

#include <xtd/threading/auto_reset_event>
#include <xtd/threading/timer>
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>

using namespace xtd;
using namespace xtd::threading;

namespace timer_example {
  class status_checker {
  private:
    int invoke_count = 0;
    int max_count = 0;
    
  public:
    status_checker(int count) {
      invoke_count = 0;
      max_count = count;
    }
    
    // This method is called by the timer delegate.
    void check_status(std::any state_info) {
      auto auto_event = as<auto_reset_event>(state_info);
      auto now = date_time::now();
      console::write_line("{:t}.{:D3} Checking status {,2}.",
                          now, now.millisecond(),
                          ++invoke_count);
      
      if (invoke_count == max_count) {
        // Reset the counter and signal the waiting thread.
        invoke_count = 0;
        auto_event.set();
      }
    }
  };

  class program {
  public:
    static void main() {
      // Create an auto_reset_event to signal the timeout threshold in the
      // timer callback has been reached.
      auto auto_event = auto_reset_event {false};
      
      auto status_checker = timer_example::status_checker {10};
      
      // Create a timer that invokes check_status after one second,
      // and every 1/4 second thereafter.
      auto now = date_time::now();
      console::write_line("{:t}.{:D3} Creating timer.\n",
                          now, now.millisecond());
      auto state_timer = timer {{status_checker, &timer_example::status_checker::check_status},
                                auto_event, 1000, 250};
      
      // When auto_event signals, change the period to every half second.
      auto_event.wait_one();
      state_timer.change(0, 500);
      console::write_line("\nChanging period to .5 seconds.\n");
      
      // When auto_event signals the second time, dispose of the timer.
      auto_event.wait_one();
      state_timer.close();
      console::write_line("\nDestroying timer.");
    }
  };
}

startup_(timer_example::program::main);

// This example produces output similar to the following:
//
// 10:37:37.167 Creating timer.
//
// 10:37:38.172 Checking status  1.
// 10:37:38.426 Checking status  2.
// 10:37:38.679 Checking status  3.
// 10:37:38.932 Checking status  4.
// 10:37:39.185 Checking status  5.
// 10:37:39.439 Checking status  6.
// 10:37:39.691 Checking status  7.
// 10:37:39.946 Checking status  8.
// 10:37:40.200 Checking status  9.
// 10:37:40.455 Checking status 10.
//
// Changing period to .5 seconds.
//
// 10:37:40.719 Checking status  1.
// 10:37:41.220 Checking status  2.
// 10:37:41.725 Checking status  3.
// 10:37:42.229 Checking status  4.
// 10:37:42.733 Checking status  5.
// 10:37:43.235 Checking status  6.
// 10:37:43.740 Checking status  7.
// 10:37:44.245 Checking status  8.
// 10:37:44.746 Checking status  9.
// 10:37:45.249 Checking status 10.
//
// Destroying timer.

Remarks

Use a xtd::threading::timer_callback delegate to specify the method you want the xtd::threading::timer to execute. The signature of the xtd::threading::timer_callback delegate is:

using timer_callback = action<std::any> 

.

The timer delegate is specified when the timer is constructed, and cannot be changed. The method does not execute on the thread that created the timer; it executes on axtd::threading::thread-pool thread supplied by the system.

Note

xtd includes several timer classes, each of which offers different functionality:

• xtd::timers::timer, which fires an event and executes the code in one or more event sinks at regular intervals. The class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime.
• xtd::threading::timer, which executes a single callback method on a thread pool thread at regular intervals. The callback method is defined when the timer is instantiated and cannot be changed. Like the xtd::timers::timer class, this class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime.
• xtd::forms::timer, a Windows Forms component that fires an event and executes the code in one or more event sinks at regular intervals. The component has no user interface and is designed for use in a single-threaded environment; it executes on the UI thread.

Remarks

When you create a timer, you can specify an amount of time to wait before the first execution of the method (due time), and an amount of time to wait between subsequent executions (period). The xtd::threading::timer class has the same resolution as the system clock. This means that if the period is less than the resolution of the system clock, the xtd::threading::timer_callback delegate will execute at intervals defined by the resolution of the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems. You can change the due time and period, or disable the timer, by using the xtd::forms::timer::change method.

Note

As long as you are using a xtd::threading::timer, you must keep a reference to it. As with any managed object, a xtd::threading::timer is subject to garbage collection when there are no references to it. The fact that a xtd::threading::timer is still active does not prevent it from being collecte

The system clock that is used is the same clock used by GetTickCount, which is not affected by changes made with timeBeginPeriod and timeEndPeriod.

Remarks

The callback method executed by the timer should be reentrant, because it is called onxtd::threading::thread-pool threads. The callback can be executed simultaneously on two thread pool threads if the timer interval is less than the time required to execute the callback, or if all thread pool threads are in use and the callback is queued multiple times.

Note

xtd::threading::timer is a simple, lightweight timer that uses callback methods and is served by thread pool threads. It is not recommended for use with Windows Forms, because its callbacks do not occur on the user interface thread. xtd::forms::timer is a better choice for use with Windows Forms. For server-based timer functionality, you might consider using xtd::timers::timer, which raises events and has additional features.

Examples:

timer.cpp.

Constructors
	timer (const timer_callback &callback)
	Initializes a new instance of the timer class with an infinite period and an infinite due time, using the newly created timer object as the state object. More...
	timer (const timer_callback &callback, int32 due_time, int32 period)
	Initializes a new instance of the timer class, using a 32-bit signed integer to specify the time interval. More...
	timer (const timer_callback &callback, int64 due_time, int64 period)
	Initializes a new instance of the timer class, using a 64-bit signed integer to specify the time interval. More...
	timer (const timer_callback &callback, const time_span &due_time, const time_span &period)
	Initializes a new instance of the timer class, using a TimaSpan to specify the time interval. More...
	timer (const timer_callback &callback, uint32 due_time, uint32 period)
	Initializes a new instance of the timer class, using a 32-bit unsigned integer to specify the time interval. More...
	timer (const timer_callback &callback, std::any state, int32 due_time, int32 period)
	Initializes a new instance of the timer class, using a 32-bit signed integer to specify the time interval. More...
	timer (const timer_callback &callback, std::any state, int64 due_time, int64 period)
	Initializes a new instance of the timer class, using a 64-bit signed integer to specify the time interval. More...
	timer (const timer_callback &callback, std::any state, const time_span &due_time, const time_span &period)
	Initializes a new instance of the timer class, using a TimaSpan to specify the time interval. More...
	timer (const timer_callback &callback, std::any state, uint32 due_time, uint32 period)
	Initializes a new instance of the timer class, using a 32-bit unsigned integer to specify the time interval. More...

Methods
void	change (int32 due_time, int32 period)
	changes the start time and the interval between method invocations for a timer, using 32-bit signed integers to measure time intervals. More...
void	change (int64 due_time, int64 period)
	changes the start time and the interval between method invocations for a timer, using 64-bit signed integers to measure time intervals. More...
void	change (const time_span &due_time, const time_span &period)
	changes the start time and the interval between method invocations for a timer, using time_span values to measure time intervals. More...
void	change (uint32 due_time, uint32 period)
	changes the start time and the interval between method invocations for a timer, using 32-bit unsigned integers to measure time intervals. More...
void	close ()
	Releases all resources used by the current instance of xtd::threading::timer. More...

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object. More...
bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object. More...
virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type. More...
virtual type_object	get_type () const noexcept
	Gets the type of the current instance. More...
template<typename object_t >
std::unique_ptr< object_t >	memberwise_clone () const noexcept
	Creates a shallow copy of the current object. More...
virtual xtd::ustring	to_string () const noexcept
	Returns a sxd::ustring that represents the current object. More...
Static Public Member Functions inherited from xtd::object
static bool	equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are considered equal. More...
static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance. More...

Constructor & Destructor Documentation

timer() [1/9]

xtd::threading::timer::timer ( const timer_callback &  callback )

explicit

Initializes a new instance of the timer class with an infinite period and an infinite due time, using the newly created timer object as the state object.

Parameters

callback

the address of a method to be executed

Exceptions

ArgumentNullException

The callback is null.

Remarks

Call this constructor when you want to use the timer object itself as the state object. After creating the timer, use the change method to set the interval and due time.

This constructor specifies an infinite due time before the first callback and an infinite interval between callbacks, in order to prevent the first callback from occurring before the timer object is assigned to the state object.

timer() [2/9]

xtd::threading::timer::timer	(	const timer_callback &	callback,
		int32	due_time,
		int32	period
	)

Initializes a new instance of the timer class, using a 32-bit signed integer to specify the time interval.

Parameters

callback	the address of a method to be executed
due_time	The amount of time to delay before callback is invoked, in milliseconds. Specify Timeout::Infinite to prevent the timer from starting. Specify zero (0) to start the timer immediately.
period	The time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.

Exceptions

ArgumentNullException	The callback is null.
xtd::argument_out_of_range_exception	The due_time or period parameter is negative and is not equal to Timeout::Infinite.

Remarks

The callback parameter is invoked once after due_time elapses, and thereafter each time the period time interval elapses.

timer() [3/9]

xtd::threading::timer::timer	(	const timer_callback &	callback,
		int64	due_time,
		int64	period
	)

Initializes a new instance of the timer class, using a 64-bit signed integer to specify the time interval.

Parameters

callback	the address of a method to be executed
due_time	The amount of time to delay before callback is invoked, in milliseconds. Specify Timeout::Infinite to prevent the timer from starting. Specify zero (0) to start the timer immediately.
period	The time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.

Exceptions

ArgumentNullException	The callback is null.
xtd::argument_out_of_range_exception	The due_time or period parameter is negative and is not equal to Timeout::Infinite.

Remarks

The callback parameter is invoked once after due_time elapses, and thereafter each time the period time interval elapses.

timer() [4/9]

xtd::threading::timer::timer	(	const timer_callback &	callback,
		const time_span &	due_time,
		const time_span &	period
	)

Initializes a new instance of the timer class, using a TimaSpan to specify the time interval.

Parameters

callback	the address of a method to be executed
due_time	The amount of time to delay before callback is invoked, in milliseconds. Specify Timeout::Infinite to prevent the timer from starting. Specify zero (0) to start the timer immediately.
period	The time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.

Exceptions

ArgumentNullException	The callback or due_time or period param is null.
xtd::argument_out_of_range_exception	The due_time or period parameter is negative and is not equal to Timeout::Infinite.

Remarks

The callback parameter is invoked once after due_time elapses, and thereafter each time the period time interval elapses.

timer() [5/9]

xtd::threading::timer::timer	(	const timer_callback &	callback,
		uint32	due_time,
		uint32	period
	)

Initializes a new instance of the timer class, using a 32-bit unsigned integer to specify the time interval.

Parameters

callback	the address of a method to be executed
due_time	The amount of time to delay before callback is invoked, in milliseconds. Specify Timeout::Infinite to prevent the timer from starting. Specify zero (0) to start the timer immediately.
period	The time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.

Exceptions

ArgumentNullException	The callback is null.
xtd::argument_out_of_range_exception	The due_time or period parameter is negative and is not equal to Timeout::Infinite.

Remarks

The callback parameter is invoked once after due_time elapses, and thereafter each time the period time interval elapses.

timer() [6/9]

xtd::threading::timer::timer	(	const timer_callback &	callback,
		std::any	state,
		int32	due_time,
		int32	period
	)

Initializes a new instance of the timer class, using a 32-bit signed integer to specify the time interval.

Parameters

callback	the address of a method to be executed
state	An object containing information to be used by the callback method, or null.
due_time	The amount of time to delay before callback is invoked, in milliseconds. Specify Timeout::Infinite to prevent the timer from starting. Specify zero (0) to start the timer immediately.
period	The time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.

Exceptions

ArgumentNullException	The callback is null.
xtd::argument_out_of_range_exception	The due_time or period parameter is negative and is not equal to Timeout::Infinite.

Remarks

The callback parameter is invoked once after due_time elapses, and thereafter each time the period time interval elapses.

timer() [7/9]

xtd::threading::timer::timer	(	const timer_callback &	callback,
		std::any	state,
		int64	due_time,
		int64	period
	)

Initializes a new instance of the timer class, using a 64-bit signed integer to specify the time interval.

Parameters

callback	the address of a method to be executed
state	An object containing information to be used by the callback method, or null.
due_time	The amount of time to delay before callback is invoked, in milliseconds. Specify Timeout::Infinite to prevent the timer from starting. Specify zero (0) to start the timer immediately.
period	The time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.

Exceptions

ArgumentNullException	The callback is null.
xtd::argument_out_of_range_exception	The due_time or period parameter is negative and is not equal to Timeout::Infinite.

Remarks

The callback parameter is invoked once after due_time elapses, and thereafter each time the period time interval elapses.

timer() [8/9]

xtd::threading::timer::timer	(	const timer_callback &	callback,
		std::any	state,
		const time_span &	due_time,
		const time_span &	period
	)

Initializes a new instance of the timer class, using a TimaSpan to specify the time interval.

Parameters

callback	the address of a method to be executed
state	An object containing information to be used by the callback method, or null.
due_time	The amount of time to delay before callback is invoked, in milliseconds. Specify Timeout::Infinite to prevent the timer from starting. Specify zero (0) to start the timer immediately.
period	The time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.

Exceptions

ArgumentNullException	The callback or due_time or period param is null.
xtd::argument_out_of_range_exception	The due_time or period parameter is negative and is not equal to Timeout::Infinite.

Remarks

The callback parameter is invoked once after due_time elapses, and thereafter each time the period time interval elapses.

timer() [9/9]

xtd::threading::timer::timer	(	const timer_callback &	callback,
		std::any	state,
		uint32	due_time,
		uint32	period
	)

Initializes a new instance of the timer class, using a 32-bit unsigned integer to specify the time interval.

Parameters

callback	the address of a method to be executed
state	An object containing information to be used by the callback method, or null.
due_time	The amount of time to delay before callback is invoked, in milliseconds. Specify Timeout::Infinite to prevent the timer from starting. Specify zero (0) to start the timer immediately.
period	The time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.

Exceptions

ArgumentNullException	The callback is null.
xtd::argument_out_of_range_exception	The due_time or period parameter is negative and is not equal to Timeout::Infinite.

Remarks

The callback parameter is invoked once after due_time elapses, and thereafter each time the period time interval elapses.

Member Function Documentation

change() [1/4]

void xtd::threading::timer::change	(	int32	due_time,
		int32	period
	)

changes the start time and the interval between method invocations for a timer, using 32-bit signed integers to measure time intervals.

Parameters

due_time	The amount of time to delay before callback is invoked, in milliseconds. Specify Timeout::Infinite to prevent the timer from starting. Specify zero (0) to start the timer immediately.
period	The time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.

Exceptions

xtd::argument_out_of_range_exception

The due_time or period parameter is negative and is not equal to Timeout::Infinite.

Examples:

timer.cpp.

change() [2/4]

void xtd::threading::timer::change	(	int64	due_time,
		int64	period
	)

changes the start time and the interval between method invocations for a timer, using 64-bit signed integers to measure time intervals.

Parameters

due_time	The amount of time to delay before callback is invoked, in milliseconds. Specify Timeout::Infinite to prevent the timer from starting. Specify zero (0) to start the timer immediately.
period	The time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.

Exceptions

xtd::argument_out_of_range_exception

The due_time or period parameter is negative and is not equal to Timeout::Infinite.

change() [3/4]

void xtd::threading::timer::change	(	const time_span &	due_time,
		const time_span &	period
	)

changes the start time and the interval between method invocations for a timer, using time_span values to measure time intervals.

Parameters

due_time	The amount of time to delay before callback is invoked, in milliseconds. Specify Timeout::Infinite to prevent the timer from starting. Specify zero (0) to start the timer immediately.
period	The time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.

Exceptions

ArgumentNullException	The due_time or period param is null.
xtd::argument_out_of_range_exception	The due_time or period parameter is negative and is not equal to Timeout::Infinite.

change() [4/4]

void xtd::threading::timer::change	(	uint32	due_time,
		uint32	period
	)

changes the start time and the interval between method invocations for a timer, using 32-bit unsigned integers to measure time intervals.

Parameters

due_time	The amount of time to delay before callback is invoked, in milliseconds. Specify Timeout::Infinite to prevent the timer from starting. Specify zero (0) to start the timer immediately.
period	The time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.

Exceptions

xtd::argument_out_of_range_exception

The due_time or period parameter is negative and is not equal to Timeout::Infinite.

close()

void xtd::threading::timer::close

(

)

Releases all resources used by the current instance of xtd::threading::timer.

---

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

• xtd.core/include/xtd/threading/timer.h