System.IAsyncResult Interface

Summary

Represents the status of an asynchronous operation.

C# Syntax:

public interface IAsyncResult

The IAsyncResult 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 FileStream.BeginRead, and is the type of the third parameter of methods that conclude an asynchronous operation, such as FileStream.EndRead. IAsyncResult objects are also passed to methods invoked by AsyncCallback delegates when an asynchronous operation completes.

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

For a detailed description of how the IAsyncResult interface is used, see the topic.

The following sample demonstrates using an IAsyncResult to obtain the return value of an asynchronous operation.

    // Asynchronous Callback method.
    public static void MyCallback(IAsyncResult ar) {

        // Obtains the last parameter of the delegate call.
        int value = Convert.ToInt32(ar.AsyncState);

        // Obtains return value from the delegate call using EndInvoke.
        AsyncResult aResult = (AsyncResult)ar;
        SampSyncSqrDelegate temp = (SampSyncSqrDelegate)aResult.AsyncDelegate;
        int result = temp.EndInvoke(ar);

        Console.Write("Simple.SomeMethod (AsyncCallback): Result of ");
        Console.WriteLine("{0} in SampleSynchronized.Square is {1} ", value, result);
    }

    

The following sample demonstrates waiting for an asynchronous operation to complete.

using System;
using System.Threading;
using System.Runtime.Remoting;
using System.Runtime.Remoting.Contexts;
using System.Runtime.Remoting.Messaging;

//
// Context-Bound type with Synchronization Context Attribute
//
[Synchronization()]
public class SampleSyncronized : ContextBoundObject
{
    // A method that does some work - returns the square of the given number
    public int Square(int i)
    {
        Console.Write("SampleSyncronized.Square called.  ");
        Console.WriteLine("The hash of the current thread is: {0}", Thread.CurrentThread.GetHashCode());
        return i*i;
    }
}


//
// Async delegate used to call a method with this signature asynchronously
//
public delegate int SampSyncSqrDelegate(int i);

//Main sample class
public class AsyncResultSample
{
    public static void Main()
    {
        int callParameter = 0;
        int callResult = 0;

        //Create an instance of a context-bound type SampleSynchronized
        //Because SampleSynchronized is context-bound, the object sampSyncObj 
        //is a transparent proxy
        SampleSyncronized sampSyncObj = new SampleSyncronized();


        //call the method synchronously
        Console.Write("Making a synchronous call on the object.  ");
        Console.WriteLine("The hash of the current thread is: {0}", Thread.CurrentThread.GetHashCode());
        callParameter = 10;
        callResult = sampSyncObj.Square(callParameter);
        Console.WriteLine("Result of calling sampSyncObj.Square with {0} is {1}.\n\n", callParameter, callResult);


        //call the method asynchronously
        Console.Write("Making an asynchronous call on the object.  ");
        Console.WriteLine("The hash of the current thread is: {0}", Thread.CurrentThread.GetHashCode());
        SampSyncSqrDelegate sampleDelegate = new SampSyncSqrDelegate(sampSyncObj.Square);
        callParameter = 17;

        IAsyncResult aResult = sampleDelegate.BeginInvoke(callParameter, null, null);

        //Wait for the call to complete
        aResult.AsyncWaitHandle.WaitOne();

        callResult = sampleDelegate.EndInvoke(aResult);
        Console.WriteLine("Result of calling sampSyncObj.Square with {0} is {1}.", callParameter, callResult);
    }
}

    

System Namespace

System.IAsyncResult Member List:

Public Properties

AsyncState	Read-only Gets a user-defined object that qualifies or contains information about an asynchronous operation.
AsyncWaitHandle	Read-only Gets a WaitHandle that is used to wait for an asynchronous operation to complete.
CompletedSynchronously	Read-only Gets an indication of whether the asynchronous operation completed synchronously.
IsCompleted	Read-only Gets an indication whether the asynchronous operation has completed.

System.IAsyncResult Member Details

Summary

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

C# Syntax:

object AsyncState {get;}

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

Notes to implementors: Implement this property to allow the caller of an asynchronous operation to obtain an application-defined object specified at the start of the operation. This object can be used to pass state information for the asynchronous operation to an AsyncCallback that you provide.

Return to top

Summary

Gets a WaitHandle that is used to wait for an asynchronous operation to complete.

C# Syntax:

WaitHandle AsyncWaitHandle {get;}

The return value allows the client to wait for an asynchronous operation to complete instead of polling IAsyncResult.IsCompleted until the operation concludes. The return value can be used to perform a WaitHandle.WaitOne, WaitHandle.WaitAny, or WaitHandle.WaitAll operation.

The common language runtime supplies a number of waitable objects, such as ManualResetEvent, AutoResetEvent, and Mutex, all of which mirror Win32 synchronization primitives.

Notes to implementors: IAsyncResult.AsyncWaitHandle can be allocated eagerly or on demand. It is the choice of the IAsyncResult implementer. Once allocated, IAsyncResult.AsyncWaitHandle should be kept alive until the user calls the method that concludes the asynchronous operation. At that time the object behind IAsyncResult.AsyncWaitHandle can be discarded. Clients that wait for the operation to complete (as opposed to polling) use this property to obtain a synchronization object to wait on.

Return to top

Summary

Gets an indication of whether the asynchronous operation completed synchronously.

C# Syntax:

bool CompletedSynchronously {get;}

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

Notes to implementors: Most implementers of the IAsyncResult interface will not use this property and should return false. 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.

Return to top

Summary

Gets an indication whether the asynchronous operation has completed.

C# Syntax:

bool IsCompleted {get;}

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

Notes to implementors: Implementers will typically return the value of a private field or internal test as the value of this property. Clients that poll for operation status (as opposed to waiting on a synchronization object), use this property to determine the status of the operation.

Return to top

Top of page