TPL and Traditional .NET Framework Asynchronous Programming

The .NET Framework provides the following two standard patterns for performing I/O-bound and compute-bound asynchronous operations:

  • Asynchronous Programming Model (APM), in which asynchronous operations are represented by a pair of Begin/End methods such as FileStream.BeginRead and Stream.EndRead.

  • Event-based asynchronous pattern (EAP), in which asynchronous operations are represented by a method/event pair that are named OperationNameAsync and OperationNameCompleted, for example, WebClient.DownloadStringAsync and WebClient.DownloadStringCompleted. (EAP was introduced in the .NET Framework version 2.0.)

The Task Parallel Library (TPL) can be used in various ways in conjunction with either of the asynchronous patterns. You can expose both APM and EAP operations as Tasks to library consumers, or you can expose the APM patterns but use Task objects to implement them internally. In both scenarios, by using Task objects, you can simplify the code and take advantage of the following useful functionality:

  • Register callbacks, in the form of task continuations, at any time after the task has started.

  • Coordinate multiple operations that execute in response to a Begin_ method, by using the ContinueWhenAll and ContinueWhenAny methods, or the WaitAll method or the WaitAny method.

  • Encapsulate asynchronous I/O-bound and compute-bound operations in the same Task object.

  • Monitor the status of the Task object.

  • Marshal the status of an operation to a Task object by using TaskCompletionSource(Of TResult).

Both the System.Threading.Tasks.TaskFactory and System.Threading.Tasks.TaskFactory(Of TResult) classes provide several overloads of theFromAsync andFromAsyncmethods that let you encapsulate an APM Begin/End method pair in one Task instance or Task(Of TResult) instance. The various overloads accommodate any Begin/End method pair that have from zero to three input parameters.

For pairs that have End methods that return a value (Function in Visual Basic), use the methods in TaskFactory(Of TResult), which create a Task(Of TResult). For End methods that return void (Sub in Visual Basic), use the methods in TaskFactory, which create a Task.

For those few cases in which the Begin method has more than three parameters or contains ref or out parameters, additional FromAsync overloads that encapsulate only the End method are provided.

The following code example shows the signature for the FromAsync overload that matches the FileStream.BeginRead and FileStream.EndRead methods. This overload takes three input parameters, as follows.

Public Function FromAsync(Of TArg1, TArg2, TArg3)(
                ByVal beginMethod As Func(Of TArg1, TArg2, TArg3, AsyncCallback, Object, IAsyncResult),
                ByVal endMethod As Func(Of IAsyncResult, TResult),
                ByVal dataBuffer As TArg1,
                ByVal byteOffsetToStartAt As TArg2,
                ByVal maxBytesToRead As TArg3,
                ByVal stateInfo As Object)

The first parameter is a Func(Of T1, T2, T3, T4, T5, TResult) delegate that matches the signature of the FileStream.BeginRead method. The second parameter is a Func(Of T, TResult) delegate that takes an IAsyncResult and returns a TResult. Because EndRead returns an integer, the compiler infers the type of TResult as Int32 and the type of the task as Task. The last four parameters are identical to those in the FileStream.BeginRead method:

  • The buffer in which to store the file data.

  • The offset in the buffer at which to begin writing data.

  • The maximum amount of data to read from the file.

  • An optional object that stores user-defined state data to pass to the callback.

If you require access to the data in the file, as opposed to just the number of bytes, the FromAsync method is not sufficient. Instead, use Task, whose Result property contains the file data. You can do this by adding a continuation to the original task. The continuation performs the work that would typically be performed by the AsyncCallback delegate. It is invoked when the antecedent completes, and the data buffer has been filled. (The FileStream object should be closed before returning.)

The following example shows how to return a Task that encapsulates the BeginRead/EndRead pair of the FileStream class.

Const MAX_FILE_SIZE As Integer = 14000000
Shared Function GetFileStringAsync(ByVal path As String) As Task(Of String)
    Dim fi As New FileInfo(path)
    Dim data(fi.Length) As Byte 

    Dim fs As FileStream = New FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read, data.Length, True)

    ' Task(Of Integer) returns the number of bytes read 
    Dim myTask As Task(Of Integer) = Task(Of Integer).Factory.FromAsync(
        AddressOf fs.BeginRead, AddressOf fs.EndRead, data, 0, data.Length, Nothing)

    ' It is possible to do other work here while waiting 
    ' for the antecedent task to complete. 
    ' ... 

    ' Add the continuation, which returns a Task<string>.  
    Return myTask.ContinueWith(Function(antecedent)
                                   fs.Close()
                                   If (antecedent.Result < 100) Then 
                                       Return "Data is too small to bother with." 
                                   End If 
                                   ' If we did not receive the entire file, the end of the 
                                   ' data buffer will contain garbage. 
                                   If (antecedent.Result < data.Length) Then
                                       Array.Resize(data, antecedent.Result)
                                   End If 

                                   ' Will be returned in the Result property of the Task<string> 
                                   ' at some future point after the asynchronous file I/O operation completes. 
                                   Return New UTF8Encoding().GetString(data)
                               End Function)

End Function

The method can then be called, as follows.

Dim myTask As Task(Of String) = GetFileStringAsync(path)

' Do some other work 
' ... 

Try
    Console.WriteLine(myTask.Result.Substring(0, 500))
Catch ex As AggregateException
    Console.WriteLine(ex.InnerException.Message)
End Try

In typical IAsyncResult operations, if your AsyncCallback delegate requires some custom state data, you have to pass it in through the last parameter in the Begin method, so that the data can be packaged into the IAsyncResult object that is eventually passed to the callback method. This is typically not required when the FromAsync methods are used. If the custom data is known to the continuation, then it can be captured directly in the continuation delegate. The following example resembles the previous example, but instead of examining the Result property of the antecedent, the continuation examines the custom state data that is directly accessible to the user delegate of the continuation.

Public Function GetFileStringAsync2(ByVal path As String) As Task(Of String)
    Dim fi = New FileInfo(path)
    Dim data(fi.Length) As Byte 
    Dim state As New MyCustomState()

    Dim fs As New FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read, data.Length, True)
    ' We still pass null for the last parameter because 
    ' the state variable is visible to the continuation delegate. 
    Dim myTask As Task(Of Integer) = Task(Of Integer).Factory.FromAsync(
            AddressOf fs.BeginRead, AddressOf fs.EndRead, data, 0, data.Length, Nothing)

    Return myTask.ContinueWith(Function(antecedent)
                                   fs.Close()
                                   ' Capture custom state data directly in the user delegate. 
                                   ' No need to pass it through the FromAsync method. 
                                   If (state.StateData.Contains("New York, New York")) Then 
                                       Return "Start spreading the news!" 
                                   End If 

                                   ' If we did not receive the entire file, the end of the 
                                   ' data buffer will contain garbage. 
                                   If (antecedent.Result < data.Length) Then
                                       Array.Resize(data, antecedent.Result)
                                   End If 
                                   '/ Will be returned in the Result property of the Task<string> 
                                   '/ at some future point after the asynchronous file I/O operation completes. 
                                   Return New UTF8Encoding().GetString(data)
                               End Function)

End Function

The static ContinueWhenAll and ContinueWhenAny methods provide added flexibility when used in conjunction with the FromAsync methods. The following example shows how to initiate multiple asynchronous I/O operations, and then wait for all of them to complete before you execute the continuation.

Public Function GetMultiFileData(ByVal filesToRead As String()) As Task(Of String)
    Dim fs As FileStream
    Dim tasks(filesToRead.Length) As Task(Of String)
    Dim fileData() As Byte = Nothing 
    For i As Integer = 0 To filesToRead.Length
        fileData(&H1000) = New Byte()
        fs = New FileStream(filesToRead(i), FileMode.Open, FileAccess.Read, FileShare.Read, fileData.Length, True)

        ' By adding the continuation here, the  
        ' Result of each task will be a string.
        tasks(i) = Task(Of Integer).Factory.FromAsync(AddressOf fs.BeginRead,
                                                      AddressOf fs.EndRead,
                                                      fileData,
                                                      0,
                                                      fileData.Length,
                                                      Nothing).
                                                  ContinueWith(Function(antecedent)
                                                                   fs.Close()
                                                                   'If we did not receive the entire file, the end of the 
                                                                   ' data buffer will contain garbage. 
                                                                   If (antecedent.Result < fileData.Length) Then 
                                                                       ReDim Preserve fileData(antecedent.Result)
                                                                   End If 

                                                                   'Will be returned in the Result property of the Task<string> 
                                                                   ' at some future point after the asynchronous file I/O operation completes. 
                                                                   Return New UTF8Encoding().GetString(fileData)
                                                               End Function)
    Next 

    Return Task(Of String).Factory.ContinueWhenAll(tasks, Function(data)

                                                              ' Propagate all exceptions and mark all faulted tasks as observed.
                                                              Task.WaitAll(data)

                                                              ' Combine the results from all tasks. 
                                                              Dim sb As New StringBuilder()
                                                              For Each t As Task(Of String) In data
                                                                  sb.Append(t.Result)
                                                              Next 
                                                              ' Final result to be returned eventually on the calling thread. 
                                                              Return sb.ToString()
                                                          End Function)
End Function

For those few cases in which the Begin method requires more than three input parameters, or has ref or out parameters, you can use the FromAsync overloads, for example, TaskFactory(Of TResult).FromAsync(IAsyncResult, Func(Of IAsyncResult, TResult)), that represent only the End method. These methods can also be used in any scenario in which you are passed an IAsyncResult and want to encapsulate it in a Task.

Shared Function ReturnTaskFromAsyncResult() As Task(Of String)
    Dim ar As IAsyncResult = DoSomethingAsynchronously()
    Dim t As Task(Of String) = Task(Of String).Factory.FromAsync(ar, Function(res) CStr(res.AsyncState))
    Return t
End Function

The task returned by a FromAsync method has a status of WaitingForActivation and will be started by the system at some point after the task is created. If you attempt to call Start on such a task, an exception will be raised.

You cannot cancel a FromAsync task, because the underlying .NET Framework APIs currently do not support in-progress cancellation of file or network I/O. You can add cancellation functionality to a method that encapsulates a FromAsync call, but you can only respond to the cancellation before FromAsync is called or after it completed (for example, in a continuation task).

Some classes that support EAP, for example, WebClient, do support cancellation, and you can integrate that native cancellation functionality by using cancellation tokens.

The TPL does not provide any methods that are specifically designed to encapsulate an event-based asynchronous operation in the same way that the FromAsync family of methods wrap the IAsyncResult pattern. However, the TPL does provide the System.Threading.Tasks.TaskCompletionSource(Of TResult) class, which can be used to represent any arbitrary set of operations as a Task(Of TResult). The operations may be synchronous or asynchronous, and may be I/O bound or compute-bound, or both.

The following example shows how to use a TaskCompletionSource(Of TResult) to expose a set of asynchronous WebClient operations to client code as a basic Task(Of TResult). The method lets you enter an array of Web URLs, and a term or name to search for, and then returns the number of times the search term occurs on each site.

Class SimpleWebExample
    Dim tcs As New TaskCompletionSource(Of String())
    Dim nameToSearch As String 
    Dim token As CancellationToken
    Dim results As New List(Of String)
    Dim m_lock As Object 
    Dim count As Integer 
    Dim addresses() As String 

    Public Function GetWordCountsSimplified(ByVal urls() As String, ByVal str As String, ByVal token As CancellationToken) As Task(Of String())

        Dim webClients() As WebClient
        ReDim webClients(urls.Length)

        ' If the user cancels the CancellationToken, then we can use the 
        ' WebClient's ability to cancel its own async operations.
        token.Register(Sub()
                           For Each wc As WebClient In webClients
                               If Not wc Is Nothing Then
                                   wc.CancelAsync()
                               End If 
                           Next 
                       End Sub)


        For i As Integer = 0 To urls.Length
            webClients(i) = New WebClient()

            ' Specify the callback for the DownloadStringCompleted 
            ' event that will be raised by this WebClient instance. 
            AddHandler webClients(i).DownloadStringCompleted, AddressOf WebEventHandler

            Dim address As New Uri(urls(i))
            ' Pass the address, and also use it for the userToken  
            ' to identify the page when the delegate is invoked.
            webClients(i).DownloadStringAsync(address, address)
        Next 

        ' Return the underlying Task. The client code 
        ' waits on the Result property, and handles exceptions 
        ' in the try-catch block there. 
        Return tcs.Task
    End Function 

    Public Sub WebEventHandler(ByVal sender As Object, ByVal args As DownloadStringCompletedEventArgs)

        If args.Cancelled = True Then
            tcs.TrySetCanceled()
            Return 
        ElseIf Not args.Error Is Nothing Then
            tcs.TrySetException(args.Error)
            Return 
        Else 
            ' Split the string into an array of words, 
            ' then count the number of elements that match 
            ' the search term. 
            Dim words() As String = args.Result.Split(" "c)
            Dim NAME As String = nameToSearch.ToUpper()
            Dim nameCount = (From word In words.AsParallel()
                            Where word.ToUpper().Contains(NAME)
                            Select word).Count()

            ' Associate the results with the url, and add new string to the array that  
            ' the underlying Task object will return in its Result property.
            results.Add(String.Format("{0} has {1} instances of {2}", args.UserState, nameCount, NAME))
        End If 

        SyncLock (m_lock)
            count = count + 1
            If (count = addresses.Length) Then
                tcs.TrySetResult(results.ToArray())
            End If 
        End SyncLock 
    End Sub 
End Class

For a more complete example, which includes additional exception handling and shows how to call the method from client code, see How to: Wrap EAP Patterns in a Task.

Remember that any task that is created by a TaskCompletionSource(Of TResult) will be started by that TaskCompletionSource and, therefore, user code should not call the Start method on that task.

In some scenarios, it may be desirable to directly expose the IAsyncResult pattern by using Begin/End method pairs in an API. For example, you may want to maintain consistency with existing APIs, or you may have automated tools that require this pattern. In such cases, you can use Tasks to simplify how the APM pattern is implemented internally.

The following example shows how to use tasks to implement an APM Begin/End method pair for a long-running compute-bound method.

Class Calculator
    Public Function BeginCalculate(ByVal decimalPlaces As Integer, ByVal ac As AsyncCallback, ByVal state As Object) As IAsyncResult
        Console.WriteLine("Calling BeginCalculate on thread {0}", Thread.CurrentThread.ManagedThreadId)
        Dim myTask = Task(Of String).Factory.StartNew(Function(obj) Compute(decimalPlaces), state)
        myTask.ContinueWith(Sub(antedecent) ac(myTask))

    End Function 
    Private Function Compute(ByVal decimalPlaces As Integer)
        Console.WriteLine("Calling compute on thread {0}", Thread.CurrentThread.ManagedThreadId)

        ' Simulating some heavy work.
        Thread.SpinWait(500000000)

        ' Actual implemenation left as exercise for the reader. 
        ' Several examples are available on the Web. 
        Return "3.14159265358979323846264338327950288" 
    End Function 

    Public Function EndCalculate(ByVal ar As IAsyncResult) As String
        Console.WriteLine("Calling EndCalculate on thread {0}", Thread.CurrentThread.ManagedThreadId)
        Return CType(ar, Task(Of String)).Result
    End Function 
End Class 

Class CalculatorClient
    Shared decimalPlaces As Integer 
    Shared Sub Main()
        Dim calc As New Calculator
        Dim places As Integer = 35
        Dim callback As New AsyncCallback(AddressOf PrintResult)
        Dim ar As IAsyncResult = calc.BeginCalculate(places, callback, calc)

        ' Do some work on this thread while the calulator is busy.
        Console.WriteLine("Working...")
        Thread.SpinWait(500000)
        Console.ReadLine()
    End Sub 

    Public Shared Sub PrintResult(ByVal result As IAsyncResult)
        Dim c As Calculator = CType(result.AsyncState, Calculator)
        Dim piString As String = c.EndCalculate(result)
        Console.WriteLine("Calling PrintResult on thread {0}; result = {1}",
                   Thread.CurrentThread.ManagedThreadId, piString)
    End Sub 

End Class

The Streamextensions.cs file, in Samples for Parallel Programming with the .NET Framework 4 on the MSDN Web site, contains several reference implementations that use Task objects for asynchronous file and network I/O.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft