xtd 0.2.0
Loading...
Searching...
No Matches
xtd::iasync_result Class Referenceabstract
Inheritance diagram for xtd::iasync_result:
xtd::interface

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.".
static void write_line()
Writes the current line terminator to the standard output stream using the specified format informati...
xtd::basic_string< char > string
Represents text as a sequence of UTF-8 code units.
Definition __string_definitions.h:43
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

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_handleasync_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: