Add wait_handle example

examples/xtd.core.examples/README.md

@@ -285,6 +285,7 @@
 * [semaphore](threading/semaphore/README.md) shows how to use [xtd::threading:semaphore](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1threading_1_1semaphore.html) class.
 * [thread](threading/thread/README.md) shows hows how to use [xtd::threading::thread](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1threading_1_1thread.html) class.
 * [timeout](threading/timeout/README.md) shows how to use [xtd::threading:timeout](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1threading_1_1timeout.html) class.
+* [wait_handle](threading/wait_handle/README.md) shows how to use [xtd::threading:semaphore](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1threading_1_1wait_handle.html) class.
 
 ## [Uri](uri/README.md)
 

examples/xtd.core.examples/threading/CMakeLists.txt

@@ -15,4 +15,5 @@ add_projects(
   semaphore
   thread
   timeout
+  wait_handle
 )

examples/xtd.core.examples/threading/README.md

@@ -13,4 +13,4 @@
 * [semaphore](semaphore/README.md) shows how to use [xtd::threading:semaphore](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1threading_1_1semaphore.html) class.
 * [thread](thread/README.md) shows hows how to use [xtd::threading::thread](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1threading_1_1thread.html) class.
 * [timeout](timeout/README.md) shows how to use [xtd::threading:timeout](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1threading_1_1timeout.html) class.
-
+* [wait_handle](wait_handle/README.md) shows how to use [xtd::threading:semaphore](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1threading_1_1wait_handle.html) class.

examples/xtd.core.examples/threading/wait_handle/CMakeLists.txt

@@ -0,0 +1,6 @@
+cmake_minimum_required(VERSION 3.5)
+
+project(wait_handle)
+find_package(xtd REQUIRED)
+add_sources(README.md src/wait_handle.cpp)
+target_type(CONSOLE_APPLICATION)

examples/xtd.core.examples/threading/wait_handle/README.md

@@ -0,0 +1,31 @@
+# wait_handle
+
+Shows how to use [xtd::threading::wait_handle](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1threading_1_1wait_handle.html) class.
+
+## Sources
+
+[src/wait_handle.cpp](src/wait_handle.cpp)
+
+[CMakeLists.txt](CMakeLists.txt)
+
+# Build and run
+
+Open "Command Prompt" or "Terminal". Navigate to the folder that contains the project and type the following:
+
+```cmake
+xtdc run
+```
+
+# Output
+
+```
+MMain thread is waiting for BOTH tasks to complete.
+Performing a task for 4000 milliseconds.
+Performing a task for 9000 milliseconds.
+Both tasks are completed (time waited=00:00:09:011011000)
+
+The main thread is waiting for either task to complete.
+Performing a task for 7000 milliseconds.
+Performing a task for 4000 milliseconds.
+Task 2 finished first (time waited=00:00:04:011925000).
+```

examples/xtd.core.examples/threading/wait_handle/src/wait_handle.cpp

@@ -0,0 +1,74 @@
+#include <xtd/threading/auto_reset_event>
+//#include <xtd/threading/thread_pool>
+#include <xtd/threading/thread>
+#include <xtd/console>
+#include <xtd/date_time>
+#include <xtd/random>
+#include <xtd/startup>
+
+using namespace xtd;
+using namespace xtd::threading;
+
+namespace wait_handle_example {
+  class program {
+  public:
+    static void main() {
+      // Queue up two tasks on two different threads;
+      // wait until all tasks are completed.
+      auto dt = date_time::now();
+      console::write_line("Main thread is waiting for BOTH tasks to complete.");
+      //thread_pool::queue_user_work_item(wait_callback(do_task), event1);
+      //xthread_pool::queue_user_work_item(wait_callback(do_task), event2);
+      auto t1 = thread::start_new(parameterized_thread_start {do_task}, &event1);
+      auto t2 = thread::start_new(parameterized_thread_start {do_task}, &event2);
+      wait_handle::wait_all({event1, event2});
+      // The time shown below should match the longest task.
+      console::write_line("Both tasks are completed (time waited={0})",
+                          date_time::now() - dt);
+
+      // Queue up two tasks on two different threads;
+      // wait until any task is completed.
+      dt = date_time::now();
+      console::write_line();
+      console::write_line("The main thread is waiting for either task to complete.");
+      //thread_pool::queue_user_work_item(wait_callback(do_task), event1);
+      //thread_pool::queue_user_work_item(wait_callback(do_task), event2);
+      auto t3 = thread::start_new(parameterized_thread_start {do_task}, &event1);
+      auto t4 = thread::start_new(parameterized_thread_start {do_task}, &event2);
+      auto index = wait_handle::wait_any({event1, event2});
+      // The time shown below should match the shortest task.
+      console::write_line("Task {0} finished first (time waited={1}).",
+                          index + 1, date_time::now() - dt);
+    }
+
+    static void do_task(std::any state) {
+      auto are = as<auto_reset_event*>(state);
+      auto time = 1000 * r.next(2, 10);
+      console::write_line("Performing a task for {0} milliseconds.", time);
+      thread::sleep(time);
+      are->set();
+    }
+
+  private:
+    // Define two auto_reset_event.
+    inline static auto_reset_event event1 {false};
+    inline static auto_reset_event event2 {false};
+
+    // Define a random number generator for testing.
+    inline static xtd::random r;
+  };
+}
+
+startup_(wait_handle_example::program);
+
+// This example produces output similar to the following:
+//
+// Main thread is waiting for BOTH tasks to complete.
+// Performing a task for 4000 milliseconds.
+// Performing a task for 9000 milliseconds.
+// Both tasks are completed (time waited=00:00:09:011011000)
+//
+// The main thread is waiting for either task to complete.
+// Performing a task for 7000 milliseconds.
+// Performing a task for 4000 milliseconds.
+// Task 2 finished first (time waited=00:00:04:011925000).

src/xtd.core/include/xtd/threading/wait_handle.h

@@ -38,6 +38,9 @@ namespace xtd {
     /// * xtd::threading::wait_handle::wait_all, which allows a thread to wait until all the wait handles in an array receive a signal.
     /// * xtd::threading::wait_handle::wait_any, which allows a thread to wait until any one of a specified set of wait handles has been signaled.
     /// @remarks The overloads of these methods provide timeout intervals for abandoning the wait, and the opportunity to exit a synchronization context before entering the wait, allowing other threads to use the synchronization context.
+    /// @par Examples
+    /// The following code example shows how two threads can do background tasks while the Main thread waits for the tasks to complete using the static xtd::threading::wait_handle::wait_any and xtd::threading::wait_handle::wait_all methods of the xtd::threading::wait_handle class.
+    /// @include wait_handle.cpp
     class wait_handle abstract_ {
       friend class thread;
     public: