xtd::iasync_result Class Reference

#include <iasync_result.h>

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.

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

Member Function Documentation

async_mutex()

virtual std::shared_mutex& xtd::iasync_result::async_mutex ( )

pure virtual

Gets a std::mutex that is used to wait for an asynchronous operation to complete.

Returns

A std::mutex 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 std::mutex until the xtd::iasync_result::async_mutex property is read. It is the choice of the xtd::iasync_result implementer. However, if the implementer creates xtd::iasync_result::async_mutex, it is the responsibility of the implementer to signal the std::mutex that will terminate the wait at the appropriate time. Once created, xtd::iasync_result xtd::iasync_result::async_mutex 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_mutex 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

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.

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