Asynchronous Programming Design Pattern
The following code example demonstrates a server class that factorizes a number.
Public Class PrimeFactorizer
Public Function Factorize(factorizableNum As Long, ByRef primefactor1
As Long, ByRef primefactor2 As Long) As Boolean
primefactor1 = 1
primefactor2 = factorizableNum
' Factorize using a low-tech approach.
Dim i As Integer
For i = 2 To factorizableNum - 1
If 0 = factorizableNum Mod i Then
primefactor1 = i
primefactor2 = factorizableNum / i
Exit For
End If
Next i
If 1 = primefactor1 Then
Return False
Else
Return True
End If
End Function
End Class
[C#]
public class PrimeFactorizer
{
public bool Factorize(long factorizableNum,
ref long primefactor1,
ref long primefactor2)
{
primefactor1 = 1;
primefactor2 = factorizableNum;
// Factorize using a low-tech approach.
for (int i=2;i<factorizableNum;i++)
{
if (0 == (factorizableNum % i))
{
primefactor1 = i;
primefactor2 = factorizableNum / i;
break;
}
}
if (1 == primefactor1 )
return false;
else
return true ;
}
}
The following code example shows a client defining a pattern for asynchronously invoking the Factorize method from the PrimeFactorizer class in the previous example.
' Define the delegate.
Delegate Function FactorizingAsyncDelegate(factorizableNum As Long, ByRef
primefactor1 As Long, ByRef primefactor2 As Long)
End Sub
' Create an instance of the Factorizer.
Dim pf As New PrimeFactorizer()
' Create a delegate on the Factorize method on the Factorizer.
Dim fd As New FactorizingDelegate(pf.Factorize)
[C#]
// Define the delegate.
public delegate bool FactorizingAsyncDelegate(long factorizableNum,
ref long primefactor1,
ref long primefactor2);
// Create an instance of the Factorizer.
PrimeFactorizer pf = new PrimeFactorizer();
// Create a delegate on the Factorize method on the Factorizer.
FactorizingDelegate fd = new FactorizingDelegate(pf.Factorize);
The compiler will emit the following FactorizingAsyncDelegate class after parsing its definition in the first line of the previous example. It will generate the BeginInvoke and EndInvoke methods.
Public Class FactorizingAsyncDelegate
Inherits Delegate
Public Function Invoke(factorizableNum As Long, ByRef primefactor1 As
Long, ByRef primefactor2 As Long) As Boolean
End Function
' Supplied by the compiler.
Public Function BeginInvoke(factorizableNum As Long, ByRef primefactor1
As Long, ByRef primefactor2 As Long, cb As AsyncCallback,
AsyncState As Object) As
IasyncResult
End Function
' Supplied by the compiler.
Public Function EndInvoke(ByRef primefactor1 As Long, ByRef
primefactor2 As Long, ar As IAsyncResult) As Boolean
End Function
[C#]
public class FactorizingAsyncDelegate : Delegate
{
public bool Invoke(ulong factorizableNum,
ref ulong primefactor1, ref ulong primefactor2);
// Supplied by the compiler.
public IAsyncResult BeginInvoke(ulong factorizableNum,
ref unsigned long primefactor1,
ref unsigned long primefactor2, AsyncCallback cb,
Object AsyncState);
// Supplied by the compiler.
public bool EndInvoke(ref ulong primefactor1,
ref ulong primefactor2, IAsyncResult ar);
}
The interface used as the delegate parameter in the following code example is defined in the .NET Framework Class Library. For more information, see IAsyncResult Interface.
Delegate Function AsyncCallback(ar As IAsyncResult)
' Returns true if the asynchronous operation has been completed.
Public Interface IasyncResult
' Handle to block on for the results.
ReadOnly Property IsCompleted() As Boolean
' Get accessor implementation goes here.
End Property
' Caller can use this to wait until operation is complete.
ReadOnly Property AsyncWaitHandle() As WaitHandle
' Get accessor implementation goes here.
End Property
' The delegate object for which the async call was invoked.
ReadOnly Property AsyncObject() As [Object]
' Get accessor implementation goes here.
End Property
' The state object passed in through BeginInvoke.
ReadOnly Property AsyncState() As [Object]
' Get accessor implementation goes here.
End Property
' Returns true if the call completed synchronously.
ReadOnly Property CompletedSynchronously() As Boolean
' Get accessor implementation goes here.
End Property
End Interface
[C#]
public delegate AsyncCallback (IAsyncResult ar);
public interface IAsyncResult
{
// Returns true if the asynchronous operation has completed.
bool IsCompleted { get; }
// Caller can use this to wait until operation is complete.
WaitHandle AsyncWaitHandle { get; }
// The delegate object for which the async call was invoked.
Object AsyncObject { get; }
// The state object passed in through BeginInvoke.
Object AsyncState { get; }
// Returns true if the call completed synchronously.
bool CompletedSynchronously { get; }
}
Note that the object that implements the IAsyncResult Interface must be a waitable object and its underlying synchronization primitive should be signaled after the call is canceled or completed. This enables the client to wait for the call to complete instead of polling. The runtime supplies a number of waitable objects that mirror Win32 synchronization primitives, such as ManualResetEvent, AutoResetEvent and Mutex. It also supplies methods that support waiting for such synchronization objects to become signaled with "any" or "all" semantics. Such methods are context-aware to avoid deadlocks.
The Cancel method is a request to cancel processing of the method after the desired time-out period has expired. Note that it is only a request by the client and the server is recommended to honor it. Further, the client should not assume that the server has stopped processing the request completely after receiving notification that the method has been canceled. In other words, the client is recommended to not destroy resources such as file objects, as the server might be actively using them. The IsCanceled property will be set to true if the call was canceled and the IsCompleted property will be set to true after the server has completed processing of the call. After the server sets the IsCompleted property to true, the server cannot use any client-supplied resources outside of the agreed-upon sharing semantics. Thus, it is safe for the client to destroy the resources after the IsCompleted property returns true.
The Server property returns the server object that provided the IAsyncResult.
The following code example demonstrates the client-side programming model for invoking the Factorize method asynchronously.
public class ProcessFactorizeNumber
{
private long _ulNumber;
public ProcessFactorizeNumber(long number)
{
_ulNumber = number;
}
[OneWayAttribute()]
public void FactorizedResults(IAsyncResult ar)
{
long factor1=0, factor2=0;
// Extract the delegate from the AsynchResult.
FactorizingAsyncDelegate fd =
(FactorizingAsyncDelegate) ((AsyncResult)ar).AsyncDelegate;
// Obtain the result.
fd.EndInvoke(ref factor1, ref factor2, ar);
// Output the results.
Console.Writeline("On CallBack: Factors of {0} : {1} {2}",
_ulNumber, factor1, factor2);
}
}
// Async Variation 1.
// The ProcessFactorizeNumber.FactorizedResults callback function
// is called when the call completes.
public void FactorizeNumber1()
{
// Client code.
PrimeFactorizer pf = new PrimeFactorizer();
FactorizingAsyncDelegate fd = new FactorizingAsyncDelegate (pf.Factorize);
long factorizableNum = 1000589023, temp=0;
// Create an instance of the class that
// will be called when the call completes.
ProcessFactorizedNumber fc =
new ProcessFactorizedNumber(factorizableNum);
// Define the AsyncCallback delegate.
AsyncCallbackDelegate cb = new AsyncCallback(fc.FactorizedResults);
// Any object can be the state object.
Object state = new Object();
// Asynchronously invoke the Factorize method on pf.
// Note: If you have pure out parameters, you do not need the
// temp variable.
IAsyncResult ar = fd.BeginInvoke(factorizableNum, ref temp, ref temp,
cb, state);
// Proceed to do other useful work.
// Async Variation 2.
// Waits for the result.
// Asynchronously invoke the Factorize method on pf.
// Note: If you have pure out parameters, you do not need
// the temp variable.
public void FactorizeNumber2()
{
// Client code.
PrimeFactorizer pf = new PrimeFactorizer();
FactorizingAsyncDelegate fd = new FactorizingAsyncDelegate (pf.Factorize);
long factorizableNum = 1000589023, temp=0;
// Create an instance of the class
// to be called when the call completes.
ProcessFactorizedNumber fc =
new ProcessFactorizedNumber(factorizableNum);
// Define the AsyncCallback delegate.
AsyncCallback cb = new AsyncCallback(fc.FactorizedResults);
// Any object can be the state object.
Object state = new Object();
// Asynchronously invoke the Factorize method on pf.
IAsyncResult ar = fd.BeginInvoke(factorizableNum, ref temp, ref temp,
null, null);
ar.AsyncWaitHandle.WaitOne(10000, false);
if(ar.IsCompleted)
{
int factor1=0, factor2=0;
// Obtain the result.
fd.EndInvoke(ref factor1, ref factor2, ar);
// Output the results.
Console.Writeline("Sequential : Factors of {0} : {1} {2}",
factorizableNum, factor1, factor2);
}
}
Note that if FactorizeCallback is a context-bound class that requires synchronized or thread-affinity context, the callback function is dispatched through the context dispatcher infrastructure. In other words, the callback function itself might execute asynchronously with respect to its caller for such contexts. These are the semantics of the one-way qualifier on method signatures. Any such method call might execute synchronously or asynchronously with respect to caller, and the caller cannot make any assumptions about completion of such a call when execution control returns to it.
Also, calling EndInvoke before the asynchronous operation is complete will block the caller. Calling it a second time with the same AsyncResult is undefined.
Summary of Asynchronous Programming Design Pattern
The server splits an asynchronous operation into its two logical parts: the part that takes input from the client and starts the asynchronous operation, and the part that supplies the results of the asynchronous operation to the client. In addition to the input needed for the asynchronous operation, the first part also takes an AsyncCallbackDelegate object to be called when the asynchronous operation is completed. The first part returns a waitable object that implements the IAsyncResult interface used by the client to determine the status of the asynchronous operation. The server typically also uses the waitable object it returned to the client to maintain any state associated with asynchronous operation. The client uses the second part to obtain the results of the asynchronous operation by supplying the waitable object.
When initiating asynchronous operations, the client can either supply the callback function delegate or not supply it.
The following options are available to the client for completing asynchronous operations:
- Poll the returned IAsyncResult object for completion.
- Attempt to complete the operation prematurely, thereby blocking until the operation completes.
- Wait on the IAsyncResult object. The difference between this and the previous option is that the client can use time-outs to periodically take back control.
- Complete the operation inside the callback function routine.
One scenario in which both synchronous and asynchronous read and write methods are desirable is the use of file input/output. The following example illustrates the design pattern by showing how the File object implements read and write operations.
Public Class File
' Other methods for this class go here.
' Synchronous read method.
Function Read(buffer() As [Byte], NumToRead As Long) As Long
' Asynchronous read method.
Function BeginRead(buffer() As [Byte], NumToRead As Long, cb As
AsyncCallbackDelegate) As IAsyncResult
Function EndRead(ar As IAsyncResult) As Long
' Synchronous write method.
Function Write(buffer() As [Byte], NumToWrite As Long) As Long
' Asynchrnous write method.
Function BeginWrite(buffer() As [Byte], NumToWrite As Long, cb As
AsyncCallbackDelegate) As IAsyncResult
Function EndWrite(ar As IAsyncResult) As Long
End Class
[C#]
public class File
{
// Other methods for this class go here.
// Synchronous read method.
long Read(Byte[] buffer, long NumToRead);
// Asynchronous read method.
IAsyncResult BeginRead(Byte[] buffer, long NumToRead,
AsyncCallbackDelegate cb);
long EndRead(IAsyncResult ar);
// Synchronous write method.
long Write(Byte[] buffer, long NumToWrite);
// Asynchrnous write method.
IAsyncResult BeginWrite(Byte[] buffer, long NumToWrite,
AsyncCallbackDelegate cb);
long EndWrite(IAsyncResult ar);
}
The client cannot easily associate state with a given asynchronous operation without defining a new callback function delegate for each operation. This can be fixed by making Begin methods, such as BeginWrite, take an extra object parameter that represents the state and which is captured in the IAsyncResult.
See Also
Design Guidelines for Class Library Developers | Asynchronous Execution | IAsyncResult Interface