Interop with Other Asynchronous Patterns and Types

A brief history of asynchronous patterns in .NET:

• .NET Framework 1.0 introduced the IAsyncResult pattern, otherwise known as the Asynchronous Programming Model (APM), or the Begin/End pattern.
• .NET Framework 2.0 added the Event-based Asynchronous Pattern (EAP).
• .NET Framework 4 introduced the Task-based Asynchronous Pattern (TAP), which supersedes both APM and EAP and provides the ability to easily build migration routines from the earlier patterns.

Tasks and the Asynchronous Programming Model (APM)

From APM to TAP

Because the Asynchronous Programming Model (APM) pattern is structured, it is quite easy to build a wrapper to expose an APM implementation as a TAP implementation. .NET Framework 4 and later versions include helper routines in the form of FromAsync method overloads to provide this translation.

Consider the Stream class and its BeginRead and EndRead methods, which represent the APM counterpart to the synchronous Read method:

C#

public int Read(byte[] buffer, int offset, int count)

C#

public IAsyncResult BeginRead(byte[] buffer, int offset,
                              int count, AsyncCallback callback,
                              object state)

C#

public int EndRead(IAsyncResult asyncResult)

You can use the TaskFactory<TResult>.FromAsync method to implement a TAP wrapper for this operation as follows:

C#

public static Task<int> ReadAsync(this Stream stream,
                                  byte[] buffer, int offset,
                                  int count)
{
    if (stream == null)
       throw new ArgumentNullException("stream");

    return Task<int>.Factory.FromAsync(stream.BeginRead,
                                       stream.EndRead, buffer,
                                       offset, count, null);
}

This implementation is similar to the following:

C#

 public static Task<int> ReadAsync(this Stream stream,
                                   byte [] buffer, int offset,
                                   int count)
 {
    if (stream == null)
        throw new ArgumentNullException("stream");

    var tcs = new TaskCompletionSource<int>();
    stream.BeginRead(buffer, offset, count, iar =>
                     {
                        try {
                           tcs.TrySetResult(stream.EndRead(iar));
                        }
                        catch(OperationCanceledException) {
                           tcs.TrySetCanceled();
                        }
                        catch(Exception exc) {
                           tcs.TrySetException(exc);
                        }
                     }, null);
    return tcs.Task;
}

From TAP to APM

If your existing infrastructure expects the APM pattern, you'll also want to take a TAP implementation and use it where an APM implementation is expected. Because tasks can be composed and the Task class implements IAsyncResult, you can use a straightforward helper function to do this. The following code uses an extension of the Task<TResult> class, but you can use an almost identical function for non-generic tasks.

C#

public static IAsyncResult AsApm<T>(this Task<T> task,
                                    AsyncCallback callback,
                                    object state)
{
    if (task == null)
        throw new ArgumentNullException("task");

    var tcs = new TaskCompletionSource<T>(state);
    task.ContinueWith(t =>
                      {
                         if (t.IsFaulted)
                            tcs.TrySetException(t.Exception.InnerExceptions);
                         else if (t.IsCanceled)
                            tcs.TrySetCanceled();
                         else
                            tcs.TrySetResult(t.Result);

                         if (callback != null)
                            callback(tcs.Task);
                      }, TaskScheduler.Default);
    return tcs.Task;
}

Now, consider a case where you have the following TAP implementation:

C#

public static Task<String> DownloadStringAsync(Uri url)

and you want to provide this APM implementation:

C#

public IAsyncResult BeginDownloadString(Uri url,
                                        AsyncCallback callback,
                                        object state)

C#

public string EndDownloadString(IAsyncResult asyncResult)

The following example demonstrates one migration to APM:

C#

public IAsyncResult BeginDownloadString(Uri url,
                                        AsyncCallback callback,
                                        object state)
{
   return DownloadStringAsync(url).AsApm(callback, state);
}

public string EndDownloadString(IAsyncResult asyncResult)
{
   return ((Task<string>)asyncResult).Result;
}

Tasks and the Event-based Asynchronous Pattern (EAP)

Wrapping an Event-based Asynchronous Pattern (EAP) implementation is more involved than wrapping an APM pattern, because the EAP pattern has more variation and less structure than the APM pattern. To demonstrate, the following code wraps the DownloadStringAsync method. DownloadStringAsync accepts a URI, raises the DownloadProgressChanged event while downloading in order to report multiple statistics on progress, and raises the DownloadStringCompleted event when it's done. The final result is a string that contains the contents of the page at the specified URI.

C#

 public static Task<string> DownloadStringAsync(Uri url)
 {
     var tcs = new TaskCompletionSource<string>();
     var wc = new WebClient();
     wc.DownloadStringCompleted += (s,e) =>
         {
             if (e.Error != null)
                tcs.TrySetException(e.Error);
             else if (e.Cancelled)
                tcs.TrySetCanceled();
             else
                tcs.TrySetResult(e.Result);
         };
     wc.DownloadStringAsync(url);
     return tcs.Task;
}

Tasks and Wait Handles

From Wait Handles to TAP

Although wait handles don't implement an asynchronous pattern, advanced developers may use the WaitHandle class and the ThreadPool.RegisterWaitForSingleObject method for asynchronous notifications when a wait handle is set. You can wrap the RegisterWaitForSingleObject method to enable a task-based alternative to any synchronous wait on a wait handle:

C#

public static Task WaitOneAsync(this WaitHandle waitHandle)
{
    if (waitHandle == null)
        throw new ArgumentNullException("waitHandle");

    var tcs = new TaskCompletionSource<bool>();
    var rwh = ThreadPool.RegisterWaitForSingleObject(waitHandle,
        delegate { tcs.TrySetResult(true); }, null, -1, true);
    var t = tcs.Task;
    t.ContinueWith( (antecedent) => rwh.Unregister(null));
    return t;
}

With this method, you can use existing WaitHandle implementations in asynchronous methods. For example, if you want to throttle the number of asynchronous operations that are executing at any particular time, you can utilize a semaphore (a System.Threading.SemaphoreSlim object). You can throttle to N the number of operations that run concurrently by initializing the semaphore's count to N, waiting on the semaphore any time you want to perform an operation, and releasing the semaphore when you're done with an operation:

C#

static int N = 3;

static SemaphoreSlim m_throttle = new SemaphoreSlim(N, N);

static async Task DoOperation()
{
    await m_throttle.WaitAsync();
    // do work
    m_throttle.Release();
}

You can also build an asynchronous semaphore that does not rely on wait handles and instead works completely with tasks. To do this, you can use techniques such as those discussed in Consuming the Task-based Asynchronous Pattern for building data structures on top of Task.

From TAP to Wait Handles

As previously mentioned, the Task class implements IAsyncResult, and that implementation exposes an IAsyncResult.AsyncWaitHandle property that returns a wait handle that will be set when the Task completes. You can get a WaitHandle for a Task as follows:

C#

WaitHandle wh = ((IAsyncResult)task).AsyncWaitHandle;

See also

• Task-based Asynchronous Pattern (TAP)
• Implementing the Task-based Asynchronous Pattern
• Consuming the Task-based Asynchronous Pattern