xtd::timers::timer Class Reference

Inheritance diagram for xtd::timers::timer:

Definition

Generates an event after a set interval, with an option to generate recurring events.

class core_export_ timer : public xtd::object

Inheritance

xtd::object → xtd::timers::timer

Header

#include <xtd/threading/timer>

Namespace

xtd::threading

Library

xtd.core

Remarks

The xtd::timers::timer component is a server-based timer that raises an xtd::timers::timer::elapsed event in your application after the number of milliseconds in the xtd::timers::timer::interval property has elapsed. You can configure the xtd::timers::timer object to raise the event just once or repeatedly using the xtd::timers::timer::auto_reset property. Typically, a xtd::timers::timer object is declared at the class level so that it stays in scope as long as it is needed. You can then handle its xtd::timers::timer::elapsed event to provide regular processing. For example, suppose you have a critical server that must be kept running 24 hours a day, 7 days a week. You could create a service that uses a xtd::timers::timer object to periodically check the server and ensure that the system is up and running. If the system is not responding, the service could attempt to restart the server or notify an administrator.

The server-based xtd::timers::timer class is designed for use with worker threads in a multithreaded environment. Server timers can move among threads to handle the raised xtd::timers::timer::elapsed event, resulting in more accuracy than Windows timers in raising the event on time.

The xtd::timers::timer component raises the xtd::timers::timer::elapsed event, based on the value (in milliseconds) of the xtd::timers::timer::interval property. You can handle this event to perform the processing you need. For example, suppose that you have an online sales application that continuously posts sales orders to a database. The service that compiles the instructions for shipping operates on a batch of orders rather than processing each order individually. You could use a xtd::timers::timer to start the batch processing every 30 minutes.

Warning

The xtd::timers::timer class has the same resolution as the system clock. This means that the xtd::timers::timer::elapsed event will fire at an interval defined by the resolution of the system clock if the xtd::timers::timer::interval property is less than the resolution of the system clock. For more information, see the xtd::timers::timer::interval property.

Note

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

When xtd::timers::timer::auto_reset is set to false, a xtd::timers::timer object raises the xtd::timers::timer::elapsed event only once, after the first xtd::timers::timer::iInterval has elapsed. To keep raising the xtd::timers::timer::elapsed event regularly at the interval defined by the xtd::timers::timer::interval, set xtd::timers::timer::auto_reset to true, which is the default value.

If the xtd::timers::timer::synchronizing_object property is equal to std::nullopt, the xtd::timers::timer::elapsed event is raised on a xtd::threading::thread_pool thread. If processing of the xtd::timers::timer::elapsed event lasts longer than xtd::timers::timer::interval, the event might be raised again on another xtd::threading::thread_pool thread. In this situation, the event handler should be reentrant.

Note

The event-handling method might run on one thread at the same time that another thread calls the xtd::timers::timer::stop method or sets the xtd::timers::timer::enabled property to false. This might result in the xtd::timers::timer::elapsed event being raised after the timer is stopped. The example code for the xtd::timers::timerstop method shows one way to avoid this race condition.

Remarks

Even if xtd::timers::timer::synchronizing_object is not equal to std::nullopt, xtd::timers::timer::elapsed events can occur after the xtd::timers::timer::close or xtd::timers::timer::stop method has been called or after the xtd::timers::timer::enabled property has been set to false, because the signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the xtd::timers::timer::elapsed event to ignore subsequent events.

If you use the xtd::timers::timer class with a user interface element, such as a form or control, without placing the timer on that user interface element, assign the form or control that contains the xtd::timers::timer to the xtd::timers::timer::synchronizing_object property, so that the event is marshaled to the user interface thread.

For a list of default property values for an instance of xtd::timers::timer, see the xtd::timers::timer::timer constructor.

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.

Examples

The following example instantiates a xtd::timers::timer object that fires its xtd::timers::timer::elapsed event every two seconds (2,000 milliseconds), sets up an event handler for the event, and starts the timer. The event handler displays the value of the xtd::timers::elapsed_event_args::signal_time property each time it is raised.

#include <xtd/timers/timer>
#include <xtd/console>
#include <xtd/date_time>
#include <xtd/startup>
 
using namespace xtd;
using namespace xtd::timers;
 
namespace timer_example {
  class program {
  public:
    static void main() {
      set_timer();
      
      console::write_line("\nPress the Enter key to exit the application...\n");
      console::write_line("The application started at {:t}.{:d3}", date_time::now(), date_time::now().millisecond());
      console::read_line();
      a_timer.stop();
      a_timer.close();
      
      console::write_line("Terminating the application...");
    }
     
    static void set_timer() {
      // Hook up the elapsed event for the timer.
      a_timer.elapsed += on_timed_event;
      a_timer.auto_reset(true);
      a_timer.enabled(true);
    }
    
    static void on_timed_event(object& source, const elapsed_event_args& e) {
      console::write_line("The elapsed event was raised at {:t}.{:d3}",
                          e.signal_time(), e.signal_time().millisecond());
    }
    
  private:
    // Create a timer with a two second interval.
    inline static timer a_timer {2'000};
  };
}
 
startup_(timer_example::program::main);
 
// This example produces output similar to the following:
//
// Press the Enter key to exit the application...
//
// The application started at 22:12:37.523
// The elapsed event was raised at 22:12:39.531
// The elapsed event was raised at 22:12:41.537
// The elapsed event was raised at 22:12:43.543
// The elapsed event was raised at 22:12:45.548
// The elapsed event was raised at 22:12:47.553
// The elapsed event was raised at 22:12:49.557
// The elapsed event was raised at 22:12:51.560
// The elapsed event was raised at 22:12:53.565
// The elapsed event was raised at 22:12:55.570
//
// Terminating the application...

Examples

timers_timer.cpp, and timers_timer_synchronizing_object.cpp.

Public Events
event< timer, elapsed_event_handler >	elapsed
	Occurs when the interval elapses.

Public Constructors
	timer ()
	Initializes a new instance of the xtd::timers::timer class, and sets all the properties to their initial values.
	timer (double interval)
	Initializes a new instance of the xtd::timers::timer class, and sets the xtd::timers::timer::interval property to the specified number of milliseconds.
	timer (const xtd::time_span &interval)
	Initializes a new instance of the xtd::timers::timer class, setting the xtd::timers::timer::interval property to the specified period.

Public Properties
bool	auto_reset () const noexcept
	Gets a boolean indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event only once (false) or repeatedly (true).
timer &	auto_reset (bool value)
	Sets a boolean indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event only once (false) or repeatedly (true).
bool	enabled () const noexcept
	Gets a value indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event.
timer &	enabled (bool value)
	Sets a value indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event.
double	interval () const noexcept
	Gets the interval, expressed in milliseconds, at which to raise the xtd::timers::timer::elapsed event.
timer &	interval (double value)
	Sets the interval, expressed in milliseconds, at which to raise the xtd::timers::timer::elapsed event.
std::optional< std::reference_wrapper< isynchronize_invoke > >	synchronizing_object () const noexcept
	Gets the object used to marshal event-handler calls that are issued when an interval has elapsed.
timer &	synchronizing_object (isynchronize_invoke &value)
	Sets the object used to marshal event-handler calls that are issued when an interval has elapsed.
timer &	synchronizing_object (std::nullptr_t value)
	Resets the object used to marshal event-handler calls that are issued when an interval has elapsed.

Public Methods
void	close ()
	Releases the resources used by the xtd::timers::timer.
void	start ()
	Starts raising the xtd::timers::timer::elapsed event by setting xtd::timers::timer::enabled to true.
void	stop ()
	Stops raising the xtd::timers::timer::elapsed event by setting xtd::timers::timer::enabled to false.

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 xtd::size	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<class 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<class object_a_t , class 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<class object_a_t , class 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/3]

xtd::timers::timer::timer

(

)

Initializes a new instance of the xtd::timers::timer class, and sets all the properties to their initial values.

Remarks

The following table shows initial property values for an instance of xtd::timers::timer.

Property	Initial alue
xtd::timers::timer::auto_reset	true
xtd::timers::timer::enabled	false
xtd::timers::timer::nterval	100 milliseconds
xtd::timers::timer::synchronizing_object	std::nullopt

timer() [2/3]

xtd::timers::timer::timer ( double  interval )

explicit

Initializes a new instance of the xtd::timers::timer class, and sets the xtd::timers::timer::interval property to the specified number of milliseconds.

Parameters

interval

The time, in milliseconds, between events. The value must be greater than zero and less than or equal to int32_object::max_value.

Exceptions

d::argument_exception

The value of the interval parameter is less than or equal to zero, or greater than int32_object::max_value.

Remarks

This constructor sets the xtd::timers::timer::interval property of the new timer instance, but does not enable the timer.

timer() [3/3]

xtd::timers::timer::timer ( const xtd::time_span &  interval )

explicit

Initializes a new instance of the xtd::timers::timer class, setting the xtd::timers::timer::interval property to the specified period.

Parameters

interval

The time between events. The value in milliseconds must be greater than zero and less than or equal to int32_object::max_value.

Member Function Documentation

auto_reset() [1/2]

bool xtd::timers::timer::auto_reset ( ) const

noexcept

Gets a boolean indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event only once (false) or repeatedly (true).

Returns

true if the xtd::timers::timer should raise the xtd::timers::timer::elapsed event each time the interval elapses; false if it should raise the xtd::timers::timer::elapsed event only once, after the first time the interval elapses. The default is true.

Remarks

If the xtd::timers::timer is already enabled when the xtd::timers::timer::start method is called, the interval is reset. If xtd::timers::timer::auto_reset is false, the xtd::timers::timer::start method must be called in order to start the count again.

Resetting the interval affects when the xtd::timers::timer::elapsed event is raised. For example, if you set the interval to 5 seconds and then set the xtd::timers::timer::enabled property to true, the count starts at the time xtd::timers::timer::enabled is set. If you reset the interval to 10 seconds when the count is 3 seconds, the xtd::timers::timer::elapsed event is raised for the first time 13 seconds after the xtd::timers::timer::enabled property was set to true.

auto_reset() [2/2]

timer & xtd::timers::timer::auto_reset

(

bool

value

)

Sets a boolean indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event only once (false) or repeatedly (true).

Parameters

value

true if the xtd::timers::timer should raise the xtd::timers::timer::elapsed event each time the interval elapses; false if it should raise the xtd::timers::timer::elapsed event only once, after the first time the interval elapses. The default is true.

Remarks

If the xtd::timers::timer is already enabled when the xtd::timers::timer::start method is called, the interval is reset. If xtd::timers::timer::auto_reset is false, the xtd::timers::timer::start method must be called in order to start the count again.

Resetting the interval affects when the xtd::timers::timer::elapsed event is raised. For example, if you set the interval to 5 seconds and then set the xtd::timers::timer::enabled property to true, the count starts at the time xtd::timers::timer::enabled is set. If you reset the interval to 10 seconds when the count is 3 seconds, the xtd::timers::timer::elapsed event is raised for the first time 13 seconds after the xtd::timers::timer::enabled property was set to true.

enabled() [1/2]

bool xtd::timers::timer::enabled ( ) const

noexcept

Gets a value indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event.

Returns

true if the xtd::timers::timer should raise the xtd::timers::timer::elapsed event; otherwise, false. The default is false.

Exceptions

xtd::object_closed_exception	This property cannot be set because the timer has been closed.
xtd::argument_exception	The xtd::timers::timer::interval property was set to a value greater than xtd::int32_object::max_value before the timer was enabled.

Remarks

Setting xtd::timers::timer::enabled to true is the same as calling xtd::timers::timer::start, while setting xtd::timers::timer::enabled to false is the same as calling xtd::timers::timer::stop.

Note

The signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a xtd::threading::thread_pool thread. This might result in the xtd::timers::timer::elapsed event being raised after the xtd::timers::timer::enabled property is set to false. The code example for the xtd::timers::timer::stop method shows one way to work around this race condition.

Remarks

If xtd::timers::timer::enabled is set to true and xtd::timers::timer::auto_reset is set to false, the xtd::timers::timer raises the xtd::timers::timer::elapsed event only once, the first time the interval elapses.

If the interval is set after the xtd::timers::timer has started, the count is reset. For example, if you set the interval to 5 seconds and then set the xtd::timers::timer::enabled property to true, the count starts at the time xtd::timers::timer::enabled is set. If you reset the interval to 10 seconds when count is 3 seconds, the xtd::timers::timer::elapsed event is raised for the first time 13 seconds after Enabled was set to true.

enabled() [2/2]

timer & xtd::timers::timer::enabled

(

bool

value

)

Sets a value indicating whether the xtd::timers::timer should raise the xtd::timers::timer::elapsed event.

Parameters

value

true if the xtd::timers::timer should raise the xtd::timers::timer::elapsed event; otherwise, false. The default is false.

Exceptions

xtd::object_closed_exception	This property cannot be set because the timer has been closed.
xtd::argument_exception	The xtd::timers::timer::interval property was set to a value greater than xtd::int32_object::max_value before the timer was enabled.

Remarks

Setting xtd::timers::timer::enabled to true is the same as calling xtd::timers::timer::start, while setting xtd::timers::timer::enabled to false is the same as calling xtd::timers::timer::stop.

Note

The signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a xtd::threading::thread_pool thread. This might result in the xtd::timers::timer::elapsed event being raised after the xtd::timers::timer::enabled property is set to false. The code example for the xtd::timers::timer::stop method shows one way to work around this race condition.

Remarks

If xtd::timers::timer::enabled is set to true and xtd::timers::timer::auto_reset is set to false, the xtd::timers::timer raises the xtd::timers::timer::elapsed event only once, the first time the interval elapses.

If the interval is set after the xtd::timers::timer has started, the count is reset. For example, if you set the interval to 5 seconds and then set the xtd::timers::timer::enabled property to true, the count starts at the time xtd::timers::timer::enabled is set. If you reset the interval to 10 seconds when count is 3 seconds, the xtd::timers::timer::elapsed event is raised for the first time 13 seconds after Enabled was set to true.

interval() [1/2]

double xtd::timers::timer::interval ( ) const

noexcept

Gets the interval, expressed in milliseconds, at which to raise the xtd::timers::timer::elapsed event.

Returns

The time, in milliseconds, between xtd::timers::timer::elapsed events. The value must be greater than zero, and less than or equal to xtd::int32_object::max_value. The default is 100 milliseconds.

Exceptions

xtd::argument_exception

The interval is less than or equal to zero. -or The interval is greater than xtd::int32_object::max_value.

Remarks

You use the xtd::timers::timer::interval property to determine the frequency at which the xtd::timers::timer::elapsed event is fired. Because the xtd::timers::timer class depends on the system clock, it has the same resolution as the system clock. This means that the xtd::timers::timer::elapsed event will fire at an interval defined by the resolution of the system clock if the xtd::timers::timer::interval property is less than the resolution of the system clock. The following example sets the xtd::timers::timer::interval property to 5 milliseconds. When run on a Windows system whose system clock has a resolution of approximately 15 milliseconds, the event fires approximately every 15 milliseconds rather than every 5 milliseconds.

Note

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

If the interval is set after the xtd::timers::timer has started, the count is reset. For example, if you set the interval to 5 seconds and then set the xtd::timers::timer::enabled property to true, the count starts at the time xtd::timers::timer::enabled is set. If you reset the interval to 10 seconds when count is 3 seconds, the xtd::timers::timer::elapsed event is raised for the first time 13 seconds after xtd::timers::timer::enabled was set to true.

If xtd::timers::timer::enabled is set to true and xtd::timers::timer::auto_reset is set to false, the xtd::timers::timer raises the xtd::timers::timer::elapsed event only once, the first time the interval elapses. xtd::timers::timer::enabled is then set to false.

Note

If xtd::timers::timer::enabled and xtd::timers::timer::auto_reset are both set to false, and the timer has previously been enabled, setting the xtd::timers::timer::interval property causes the xtd::timers::timer::elapsed event to be raised once, as if the xtd::timers::timer::enabled property had been set to true. To set the interval without raising the event, you can temporarily set the xtd::timers::timer::enabled property to true, set the xtd::timers::timer::interval property to the desired time interval, and then immediately set the xtd::timers::timer::enabled property back to false.

interval() [2/2]

timer & xtd::timers::timer::interval

(

double

value

)

Sets the interval, expressed in milliseconds, at which to raise the xtd::timers::timer::elapsed event.

Parameters

value

The time, in milliseconds, between xtd::timers::timer::elapsed events. The value must be greater than zero, and less than or equal to xtd::int32_object::max_value. The default is 100 milliseconds.

Exceptions

xtd::argument_exception

The interval is less than or equal to zero. -or The interval is greater than xtd::int32_object::max_value.

Remarks

You use the xtd::timers::timer::interval property to determine the frequency at which the xtd::timers::timer::elapsed event is fired. Because the xtd::timers::timer class depends on the system clock, it has the same resolution as the system clock. This means that the xtd::timers::timer::elapsed event will fire at an interval defined by the resolution of the system clock if the xtd::timers::timer::interval property is less than the resolution of the system clock. The following example sets the xtd::timers::timer::interval property to 5 milliseconds. When run on a Windows system whose system clock has a resolution of approximately 15 milliseconds, the event fires approximately every 15 milliseconds rather than every 5 milliseconds.

Note

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

If the interval is set after the xtd::timers::timer has started, the count is reset. For example, if you set the interval to 5 seconds and then set the xtd::timers::timer::enabled property to true, the count starts at the time xtd::timers::timer::enabled is set. If you reset the interval to 10 seconds when count is 3 seconds, the xtd::timers::timer::elapsed event is raised for the first time 13 seconds after xtd::timers::timer::enabled was set to true.

If xtd::timers::timer::enabled is set to true and xtd::timers::timer::auto_reset is set to false, the xtd::timers::timer raises the xtd::timers::timer::elapsed event only once, the first time the interval elapses. xtd::timers::timer::enabled is then set to false.

Note

If xtd::timers::timer::enabled and xtd::timers::timer::auto_reset are both set to false, and the timer has previously been enabled, setting the xtd::timers::timer::interval property causes the xtd::timers::timer::elapsed event to be raised once, as if the xtd::timers::timer::enabled property had been set to true. To set the interval without raising the event, you can temporarily set the xtd::timers::timer::enabled property to true, set the xtd::timers::timer::interval property to the desired time interval, and then immediately set the xtd::timers::timer::enabled property back to false.

synchronizing_object() [1/3]

std::optional< std::reference_wrapper< isynchronize_invoke > > xtd::timers::timer::synchronizing_object ( ) const

noexcept

Gets the object used to marshal event-handler calls that are issued when an interval has elapsed.

Returns

The xtd::isynchronize_invoke representing the object used to marshal the event-handler calls that are issued when an interval has elapsed. The default is std::nullopt.

Remarks

When xtd::timers::timer::synchronizing_object is std::nullopt, the method that handles the xtd::timers::timer::elapsed event is called on a thread from the system-thread pool. For more information on system-thread pools, see xtd::threading::thread_pool.

When the xtd::timers::timer::elapsed event is handled by a visual Windows Forms component, such as a button, accessing the component through the system-thread pool might result in an exception or just might not work. Avoid this effect by setting xtd::timers::timer::synchronizing_object to a Windows Forms component, which causes the method that handles the xtd::timers::timer::elapsed event to be called on the same thread that the component was created on.

Note

Even if the xtd::timers::timer::synchronizing_object property is not std::nullopt, xtd::timers::timer::elapsed events can occur after the xtd::timers::timer::close or xtd::timers::timer::stop method has been called or after the Enabled property has been set to false, because the signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the xtd::timers::timer::elapsed event to ignore subsequent events.

Examples

The following example is a Windows Forms app that serves as a very simple text file editor. When the text in the text box has not been saved, the app asks the user at one-minute intervals whether they want to save the contents of the text box. To do this, the xtd::timers::timer::interval property is set to one minute (60,000 milliseconds), and the xtd::timers::timer::synchronizing_object property is set to the xtd::forms::form object.

#include <xtd/forms/application>
#include <xtd/forms/button>
#include <xtd/forms/form>
#include <xtd/forms/message_box>
#include <xtd/forms/save_file_dialog>
#include <xtd/forms/text_box>
#include <xtd/io/stream_writer>
#include <xtd/timers/timer>
#include <xtd/date_time>
#include <xtd/startup>
#include <memory>
 
using namespace xtd;
using namespace xtd::forms;
using namespace xtd::io;
using namespace xtd::timers;
 
namespace timer_example {
  class form1 : public form {
  public:
    static void main() {
      application::run(form1 {});
    }
    
    form1() {
      initialize_component();
      
      text("Quick Text Editor");
      button1.text("Save");
      text_box1.multiline(true);
 
      // Configure the SaveFile dialog
      save_file_dialog1.filter("txt files (*.txt)|*.txt|All files (*.*)|*.*");
      save_file_dialog1.restore_directory(true);
      
      // Define the event handler
      timer.elapsed += {*this, &form1::prompt_for_save};
      // Synchronize the timer with the text box
      timer.synchronizing_object(*this);
      // Start the timer
      timer.auto_reset(true);
 
    }
    
  private:
    void initialize_component() {
      form_closing += {*this, &form1::form1_form_closing};
      controls().push_back_range({text_box1, button1});
 
      button1.dock(dock_style::bottom);
      button1.click += {*this, &form1::button1_click};
 
      text_box1.dock(dock_style::fill);
      text_box1.text_changed += {*this, &form1::text_box1__text_changed};
    }
 
    void prompt_for_save(object& source, const elapsed_event_args& e) {
      if (has_changed && !dialog_is_open) {
        elapsed_minutes++;
        dialog_is_open = true;
        
        if (message_box::show(string::format("{0} minutes have elapsed since the text was saved. Save it now? ",
                                              elapsed_minutes), "Save Text",
                              message_box_buttons::yes_no_cancel, message_box_icon::question) == dialog_result::yes)
          button1_click(*this, event_args::empty);
      }
      dialog_is_open = false;
    }
    
    void button1_click(object& sender, const event_args& e) {
      if (string::is_empty(save_file_dialog1.file_name())) {
        if (save_file_dialog1.show_dialog() == dialog_result::ok)
          sw = new_ptr<stream_writer>(save_file_dialog1.file_name(), false);
      }
      txt = text_box1.text();
      has_changed = false;
      timer.stop();
    }
    
    void form1_form_closing(object& sender, form_closing_event_args& e) {
      timer.close();
      if (sw != null) {
        sw->write(txt);
        sw->close();
      }
    }
    
    void text_box1__text_changed(object& sender, const event_args& e) {
      has_changed = true;
      timer.start();
    }
    
    button button1;
    save_file_dialog save_file_dialog1;
    text_box text_box1;
 
    bool dialog_is_open = false;
    int elapsed_minutes = 0;
    bool has_changed = false;
    ptr<stream_writer> sw;
    string txt;
 
    // Create a timer with a 1-minute interval
    timers::timer timer {60'000};
  };
}
 
startup_(timer_example::form1::main);

synchronizing_object() [2/3]

timer & xtd::timers::timer::synchronizing_object

(

isynchronize_invoke &

value

)

Sets the object used to marshal event-handler calls that are issued when an interval has elapsed.

Parameters

value

The xtd::isynchronize_invoke representing the object used to marshal the event-handler calls that are issued when an interval has elapsed. The default is std::nullopt.

Remarks

When xtd::timers::timer::synchronizing_object is std::nullopt, the method that handles the xtd::timers::timer::elapsed event is called on a thread from the system-thread pool. For more information on system-thread pools, see xtd::threading::thread_pool.

When the xtd::timers::timer::elapsed event is handled by a visual Windows Forms component, such as a button, accessing the component through the system-thread pool might result in an exception or just might not work. Avoid this effect by setting xtd::timers::timer::synchronizing_object to a Windows Forms component, which causes the method that handles the xtd::timers::timer::elapsed event to be called on the same thread that the component was created on.

Note

Even if the xtd::timers::timer::synchronizing_object property is not std::nullopt, xtd::timers::timer::elapsed events can occur after the xtd::timers::timer::close or xtd::timers::timer::stop method has been called or after the Enabled property has been set to false, because the signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the xtd::timers::timer::elapsed event to ignore subsequent events. The following example is a Windows Forms app that serves as a very simple text file editor. When the text in the text box has not been saved, the app asks the user at one-minute intervals whether they want to save the contents of the text box. To do this, the xtd::timers::timer::interval property is set to one minute (60,000 milliseconds), and the xtd::timers::timer::synchronizing_object property is set to the xtd::forms::form object.

#include <xtd/forms/application>
#include <xtd/forms/button>
#include <xtd/forms/form>
#include <xtd/forms/message_box>
#include <xtd/forms/save_file_dialog>
#include <xtd/forms/text_box>
#include <xtd/io/stream_writer>
#include <xtd/timers/timer>
#include <xtd/date_time>
#include <xtd/startup>
#include <memory>
 
using namespace xtd;
using namespace xtd::forms;
using namespace xtd::io;
using namespace xtd::timers;
 
namespace timer_example {
  class form1 : public form {
  public:
    static void main() {
      application::run(form1 {});
    }
    
    form1() {
      initialize_component();
      
      text("Quick Text Editor");
      button1.text("Save");
      text_box1.multiline(true);
 
      // Configure the SaveFile dialog
      save_file_dialog1.filter("txt files (*.txt)|*.txt|All files (*.*)|*.*");
      save_file_dialog1.restore_directory(true);
      
      // Define the event handler
      timer.elapsed += {*this, &form1::prompt_for_save};
      // Synchronize the timer with the text box
      timer.synchronizing_object(*this);
      // Start the timer
      timer.auto_reset(true);
 
    }
    
  private:
    void initialize_component() {
      form_closing += {*this, &form1::form1_form_closing};
      controls().push_back_range({text_box1, button1});
 
      button1.dock(dock_style::bottom);
      button1.click += {*this, &form1::button1_click};
 
      text_box1.dock(dock_style::fill);
      text_box1.text_changed += {*this, &form1::text_box1__text_changed};
    }
 
    void prompt_for_save(object& source, const elapsed_event_args& e) {
      if (has_changed && !dialog_is_open) {
        elapsed_minutes++;
        dialog_is_open = true;
        
        if (message_box::show(string::format("{0} minutes have elapsed since the text was saved. Save it now? ",
                                              elapsed_minutes), "Save Text",
                              message_box_buttons::yes_no_cancel, message_box_icon::question) == dialog_result::yes)
          button1_click(*this, event_args::empty);
      }
      dialog_is_open = false;
    }
    
    void button1_click(object& sender, const event_args& e) {
      if (string::is_empty(save_file_dialog1.file_name())) {
        if (save_file_dialog1.show_dialog() == dialog_result::ok)
          sw = new_ptr<stream_writer>(save_file_dialog1.file_name(), false);
      }
      txt = text_box1.text();
      has_changed = false;
      timer.stop();
    }
    
    void form1_form_closing(object& sender, form_closing_event_args& e) {
      timer.close();
      if (sw != null) {
        sw->write(txt);
        sw->close();
      }
    }
    
    void text_box1__text_changed(object& sender, const event_args& e) {
      has_changed = true;
      timer.start();
    }
    
    button button1;
    save_file_dialog save_file_dialog1;
    text_box text_box1;
 
    bool dialog_is_open = false;
    int elapsed_minutes = 0;
    bool has_changed = false;
    ptr<stream_writer> sw;
    string txt;
 
    // Create a timer with a 1-minute interval
    timers::timer timer {60'000};
  };
}
 
startup_(timer_example::form1::main);

synchronizing_object() [3/3]

timer & xtd::timers::timer::synchronizing_object

(

std::nullptr_t

value

)

Resets the object used to marshal event-handler calls that are issued when an interval has elapsed.

Parameters

value

nullptr.

Remarks

When xtd::timers::timer::synchronizing_object is std::nullopt, the method that handles the xtd::timers::timer::elapsed event is called on a thread from the system-thread pool. For more information on system-thread pools, see xtd::threading::thread_pool.

When the xtd::timers::timer::elapsed event is handled by a visual Windows Forms component, such as a button, accessing the component through the system-thread pool might result in an exception or just might not work. Avoid this effect by setting xtd::timers::timer::synchronizing_object to a Windows Forms component, which causes the method that handles the xtd::timers::timer::elapsed event to be called on the same thread that the component was created on.

Note

Even if the xtd::timers::timer::synchronizing_object property is not std::nullopt, xtd::timers::timer::elapsed events can occur after the xtd::timers::timer::close or xtd::timers::timer::stop method has been called or after the Enabled property has been set to false, because the signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the xtd::timers::timer::elapsed event to ignore subsequent events. The following example is a Windows Forms app that serves as a very simple text file editor. When the text in the text box has not been saved, the app asks the user at one-minute intervals whether they want to save the contents of the text box. To do this, the xtd::timers::timer::interval property is set to one minute (60,000 milliseconds), and the xtd::timers::timer::synchronizing_object property is set to the xtd::forms::form object.

#include <xtd/forms/application>
#include <xtd/forms/button>
#include <xtd/forms/form>
#include <xtd/forms/message_box>
#include <xtd/forms/save_file_dialog>
#include <xtd/forms/text_box>
#include <xtd/io/stream_writer>
#include <xtd/timers/timer>
#include <xtd/date_time>
#include <xtd/startup>
#include <memory>
 
using namespace xtd;
using namespace xtd::forms;
using namespace xtd::io;
using namespace xtd::timers;
 
namespace timer_example {
  class form1 : public form {
  public:
    static void main() {
      application::run(form1 {});
    }
    
    form1() {
      initialize_component();
      
      text("Quick Text Editor");
      button1.text("Save");
      text_box1.multiline(true);
 
      // Configure the SaveFile dialog
      save_file_dialog1.filter("txt files (*.txt)|*.txt|All files (*.*)|*.*");
      save_file_dialog1.restore_directory(true);
      
      // Define the event handler
      timer.elapsed += {*this, &form1::prompt_for_save};
      // Synchronize the timer with the text box
      timer.synchronizing_object(*this);
      // Start the timer
      timer.auto_reset(true);
 
    }
    
  private:
    void initialize_component() {
      form_closing += {*this, &form1::form1_form_closing};
      controls().push_back_range({text_box1, button1});
 
      button1.dock(dock_style::bottom);
      button1.click += {*this, &form1::button1_click};
 
      text_box1.dock(dock_style::fill);
      text_box1.text_changed += {*this, &form1::text_box1__text_changed};
    }
 
    void prompt_for_save(object& source, const elapsed_event_args& e) {
      if (has_changed && !dialog_is_open) {
        elapsed_minutes++;
        dialog_is_open = true;
        
        if (message_box::show(string::format("{0} minutes have elapsed since the text was saved. Save it now? ",
                                              elapsed_minutes), "Save Text",
                              message_box_buttons::yes_no_cancel, message_box_icon::question) == dialog_result::yes)
          button1_click(*this, event_args::empty);
      }
      dialog_is_open = false;
    }
    
    void button1_click(object& sender, const event_args& e) {
      if (string::is_empty(save_file_dialog1.file_name())) {
        if (save_file_dialog1.show_dialog() == dialog_result::ok)
          sw = new_ptr<stream_writer>(save_file_dialog1.file_name(), false);
      }
      txt = text_box1.text();
      has_changed = false;
      timer.stop();
    }
    
    void form1_form_closing(object& sender, form_closing_event_args& e) {
      timer.close();
      if (sw != null) {
        sw->write(txt);
        sw->close();
      }
    }
    
    void text_box1__text_changed(object& sender, const event_args& e) {
      has_changed = true;
      timer.start();
    }
    
    button button1;
    save_file_dialog save_file_dialog1;
    text_box text_box1;
 
    bool dialog_is_open = false;
    int elapsed_minutes = 0;
    bool has_changed = false;
    ptr<stream_writer> sw;
    string txt;
 
    // Create a timer with a 1-minute interval
    timers::timer timer {60'000};
  };
}
 
startup_(timer_example::form1::main);

close()

void xtd::timers::timer::close

(

)

Releases the resources used by the xtd::timers::timer.

start()

void xtd::timers::timer::start

(

)

Starts raising the xtd::timers::timer::elapsed event by setting xtd::timers::timer::enabled to true.

Remarks

If xtd::timers::timer::start is called and xtd::timers::timer::auto_reset is set to false, the xtd::timers::timer raises the xtd::timers::timer::elapsed event only once, the first time the interval elapses. If xtd::timers::timer::start is called and xtd::timers::timer::auto_reset is true, the xtd::timers::timer raises the xtd::timers::timer::elapsed event the first time the interval elapses and continues to raise the event on the specified interval.

Note

If xtd::timers::timer::auto_reset is false, the xtd::timers::timer::start method must be called in order to start the count again.

stop()

void xtd::timers::timer::stop

(

)

Stops raising the xtd::timers::timer::elapsed event by setting xtd::timers::timer::enabled to false.

Remarks

You can also stop timing by setting xtd::timers::timer::enabled to false.

Note

The signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a xtd::threading::thread_pool thread, so the event-handling method might run on one thread at the same time that a call to the xtd::timers::timer::stop method runs on another thread. This might result in the xtd::timers::timer::elapsed event being raised after the xtd::timers::timer::stop method is called. The second code example in the Examples section shows one way to work around this race condition.

Member Data Documentation

elapsed

event<timer, elapsed_event_handler> xtd::timers::timer::elapsed

Occurs when the interval elapses.

Remarks

The xtd::timers::timer::elapsed event is raised if the xtd::timers::timer::enabled property is true and the time interval (in milliseconds) defined by the xtd::timers::timer::interval property elapses. If the xtd::timers::timer::auto_reset property is true, the event is raised repeatedly at an interval defined by the xtd::timers::timer::interval property; otherwise, the event is raised only once, the first time the xtd::timers::timer::interval value elapses.

If xtd::timers::timer::interval is set after the xtd::timers::timer has started, the count is reset. For example, if you set the interval to 5 seconds and then set xtd::timers::timer::enabled to true, the count starts at the time xtd::timers::timer::enabled is set. If you reset the interval to 10 seconds when count is 3 seconds, the xtd::timers::timer::elapsed event is raised for the first time 13 seconds after xtd::timers::timer::enabled was set to true.

If the xtd::timers::timer::synchronizing_object property is std::nullopt,the xtd::timers::timer::elapsed event is raised on a xtd::threading::thread_pool thread. If the processing of the xtd::timers::timer::elapsed event lasts longer than xtd::timers::timer::interval, the event might be raised again on another xtd::threading::thread_pool thread. In this situation, the event handler should be reentrant.

Note

The event-handling method might run on one thread at the same time that another thread calls the xtd::timers::timer::stop method or sets the xtd::timers::timer::enabled property to false. This might result in the xtd::timers::timer::elapsed event being raised after the timer is stopped. The example code for the Stop method shows one way to avoid this race condition.

Remarks

Even if xtd::timers::timer::synchronizing_object is not std::nullopt, xtd::timers::timer::elapsed events can occur after the xtd::timers::timer::close or xtd::timers::timer::stop method has been called or after the xtd::timers::timer:enabled property has been set to false, because the signal to raise the xtd::timers::timer::elapsed event is always queued for execution on a thread pool thread. One way to resolve this race condition is to set a flag that tells the event handler for the xtd::timers::timer::elapsed event to ignore subsequent events.

---

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

• xtd.core/include/xtd/timers/timer.hpp