xtd::iasync_result Class Reference

Inheritance diagram for xtd::iasync_result:

Definition

Represents the status of an asynchronous operation.

Namespace

xtd

Library

xtd.core

Remarks

The xtd::iasync_result interface is implemented by classes containing methods that can operate asynchronously. It is the return type of methods that initiate an asynchronous operation, such as xtd::io::file_stream.begin_read, and it is passed to methods that conclude an asynchronous operation, such as xtd::io::file_stream::end_read. xtd::iasync_result objects are also passed to methods invoked by xtd::async_callback delegates when an asynchronous operation completes.

An object that supports the xtd::iasync_result interface stores state information for an asynchronous operation and provides a synchronization object to allow threads to be signaled when the operation completes.

Note

The async_result class is the implementation of xtd::iasync_result that is returned by the begin_invoke method when you use a delegate to call a method asynchronously.

Examples

The following example shows how to use xtd::iasync_result interface.

#include <xtd/console>
#include <xtd/iasync_result>
#include <xtd/threading/thread>
 
using namespace xtd;
using namespace xtd::threading;
 
class async_demo {
public:
  // The method to be executed asynchronously.
  string test_method(int call_duration, int* thread_id) {
    console::write_line("Test method begins.");
    thread::sleep(call_duration);
    *thread_id = thread::current_thread().managed_thread_id();
    return string::format("My call time was {}.", call_duration);
  }
};
 
// The delegate must have the same signature as the method
// it will call asynchronously.
using async_method_caller = delegate<string(int call_duration, int* thread_id)>;
 
auto main() -> int {
  // The asynchronous method puts the thread id here.
  auto thread_id = 0;
  
  // Create an instance of the test class.
  auto ad = async_demo {};
  
  // Create the delegate.
  auto caller = async_method_caller {ad, &async_demo::test_method};
  
  // Initiate the asychronous call.
  auto result = caller.begin_invoke(3000, &thread_id);
  
  thread::sleep(0);
  console::write_line("Main thread {} does some work.", thread::current_thread().managed_thread_id());
  
  // Wait for the wait_handle to become signaled.
  result->async_wait_handle().wait_one();
  
  // Perform additional processing here.
  // Call end_invoke to retrieve the results.
  auto return_value = caller.end_invoke(result);
  
  // Close the wait handle.
  result->async_wait_handle().close();
  
  console::write_line("The call executed on thread {}, with return value \"{}\".", thread_id, return_value);
}
 
// This code produces the following output :
//
// Main thread 1 does some work.
// Test method begins.
// The call executed on thread 2, with return value "My call time was 3000.".

Public Methods
virtual std::any	async_state () const noexcept=0
	Gets a user-defined object that qualifies or contains information about an asynchronous operation.
virtual xtd::threading::wait_handle &	async_wait_handle () noexcept=0
	Gets a xtd::threading::wait_handle that is used to wait for an asynchronous operation to complete.
virtual bool	completed_synchronously () const noexcept=0
	Gets a value that indicates whether the asynchronous operation completed synchronously.
virtual bool	is_completed () const noexcept=0
	Gets a value that indicates whether the asynchronous operation has completed.

Member Function Documentation

async_state()

virtual std::any xtd::iasync_result::async_state ( ) const

pure virtualnoexcept

Gets a user-defined object that qualifies or contains information about an asynchronous operation.

Returns

A user-defined object that qualifies or contains information about an asynchronous operation.

Remarks

This property returns the object that is the last parameter of the method that initiates an asynchronous operation.

Notes to Implementers

Implement this property to allow the caller of an asynchronous operation to obtain an application-defined object specified at the start of the operation.

Notes to Callers

This object can be used to pass state information for the asynchronous operation to an AsyncCallback that you provide.

async_wait_handle()

virtual xtd::threading::wait_handle & xtd::iasync_result::async_wait_handle ( )

pure virtualnoexcept

Gets a xtd::threading::wait_handle that is used to wait for an asynchronous operation to complete.

Returns

A xtd::threading::wait_handle that is used to wait for an asynchronous operation to complete.

Remarks

The return value allows the client to wait for an asynchronous operation to complete instead of polling xtd::iasync_result::is_completed until the operation concludes. The return value can be used to perform a wait operation.

Notes to Implementers

The object that implements xtd::iasync_result does not need to create the xtd::threading::wait_handle until the xtd::iasync_result::async_wait_handle property is read. It is the choice of the xtd::iasync_result implementer. However, if the implementer creates xtd::iasync_result::async_wait_handle, it is the responsibility of the implementer to signal the xtd::threading::wait_handle that will terminate the wait at the appropriate time. Once created, xtd::iasync_result xtd::iasync_result::async_wait_handle should be kept alive until the user calls the method that concludes the asynchronous operation. At that time the object behind xtd::iasync_result::async_wait_handle can be discarded.

Notes to Callers

Clients that wait for the operation to complete (as opposed to polling) use this property to obtain a synchronization object to wait on.

Notes to Implementers

completed_synchronously()

virtual bool xtd::iasync_result::completed_synchronously ( ) const

pure virtualnoexcept

Gets a value that indicates whether the asynchronous operation completed synchronously.

Returns

true if the asynchronous operation completed synchronously; otherwise, false.

Remarks

If the synchronous completion of the call is detected in the xtd::async_callback delegate, it is probable that the thread that initiated the asynchronous operation is the current thread.

Notes to Callers

Use this property to determine if the asynchronous operation completed synchronously. For example, this property can return true for an asynchronous I/O operation if the I/O request was small.

is_completed()

virtual bool xtd::iasync_result::is_completed ( ) const

pure virtualnoexcept

Gets a value that indicates whether the asynchronous operation has completed.

Returns

true if the operation is complete; otherwise, false.

Remarks

When this property is true, you can assume it is safe to discard any resources you allocate for use by the asynchronous operation.

Notes to Implementers

Implementers will typically return the value of a private field or internal test as the value of this property.

Notes to Callers

Clients that poll for operation status (as opposed to waiting on a synchronization object) use this property to determine the status of the operation.

---

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

• xtd.core/include/xtd/iasync_result.h