xtd 0.2.0
Loading...
Searching...
No Matches
xtd::threading::timer Class Referencefinal
Inheritance diagram for xtd::threading::timer:
xtd::object

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
Supports all classes in the xtd class hierarchy and provides low-level services to derived classes....
Definition object.h:42
Provides a mechanism for executing a method on a thread pool thread at specified intervals....
Definition timer.h:49
#define core_export_
Define shared library export.
Definition core_export.h:13
Inheritance
xtd::objectxtd::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.
Represents a thread synchronization event that, when signaled, resets automatically after releasing a...
Definition auto_reset_event.h:36
void change(int32 due_time, int32 period)
changes the start time and the interval between method invocations for a timer, using 32-bit signed i...
#define startup_(main_method)
Defines the entry point to be called when the application loads. Generally this is set either to the ...
Definition startup.h:175
The xtd::threading namespace provides classes and interfaces that enable multithreaded programming....
Definition abandoned_mutex_exception.h:11
The xtd namespace contains all fundamental classes to access Hardware, Os, System,...
Definition xtd_about_box.h:10
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.

Public 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.
 
 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.
 
 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.
 
 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.
 
 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.
 
 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.
 
 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.
 
 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.
 
 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.
 

Public 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.
 
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.
 
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.
 
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.
 
void close ()
 Releases all resources used by the current instance of xtd::threading::timer.
 

Additional Inherited Members

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

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
callbackthe address of a method to be executed
Exceptions
ArgumentNullExceptionThe 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
callbackthe address of a method to be executed
due_timeThe 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.
periodThe time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.
Exceptions
ArgumentNullExceptionThe callback is null.
xtd::argument_out_of_range_exceptionThe 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
callbackthe address of a method to be executed
due_timeThe 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.
periodThe time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.
Exceptions
ArgumentNullExceptionThe callback is null.
xtd::argument_out_of_range_exceptionThe 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
callbackthe address of a method to be executed
due_timeThe 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.
periodThe time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.
Exceptions
ArgumentNullExceptionThe callback or due_time or period param is null.
xtd::argument_out_of_range_exceptionThe 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
callbackthe address of a method to be executed
due_timeThe 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.
periodThe time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.
Exceptions
ArgumentNullExceptionThe callback is null.
xtd::argument_out_of_range_exceptionThe 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
callbackthe address of a method to be executed
stateAn object containing information to be used by the callback method, or null.
due_timeThe 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.
periodThe time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.
Exceptions
ArgumentNullExceptionThe callback is null.
xtd::argument_out_of_range_exceptionThe 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
callbackthe address of a method to be executed
stateAn object containing information to be used by the callback method, or null.
due_timeThe 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.
periodThe time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.
Exceptions
ArgumentNullExceptionThe callback is null.
xtd::argument_out_of_range_exceptionThe 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
callbackthe address of a method to be executed
stateAn object containing information to be used by the callback method, or null.
due_timeThe 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.
periodThe time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.
Exceptions
ArgumentNullExceptionThe callback or due_time or period param is null.
xtd::argument_out_of_range_exceptionThe 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
callbackthe address of a method to be executed
stateAn object containing information to be used by the callback method, or null.
due_timeThe 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.
periodThe time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.
Exceptions
ArgumentNullExceptionThe callback is null.
xtd::argument_out_of_range_exceptionThe 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_timeThe 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.
periodThe time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.
Exceptions
xtd::argument_out_of_range_exceptionThe 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_timeThe 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.
periodThe time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.
Exceptions
xtd::argument_out_of_range_exceptionThe 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_timeThe 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.
periodThe time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.
Exceptions
ArgumentNullExceptionThe due_time or period param is null.
xtd::argument_out_of_range_exceptionThe 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_timeThe 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.
periodThe time interval between invocations of callback, in milliseconds. Specify Timeout::Infinite to disable periodic signaling.
Exceptions
xtd::argument_out_of_range_exceptionThe 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: