Time-Out Usage
Use time-outs to specify the maximum time a caller is willing to wait for completion of a method call.
A time-out might take the form of a parameter to the method call as follows.
server.PerformOperation(timeout)
server.PerformOperation(timeout);
Alternately, a time-out can be used as a property on the server class as follows.
server.Timeout = timeout
server.PerformOperation()
server.Timeout = timeout;
server.PerformOperation();
You should favor the first approach, because the association between the operation and the time-out is clearer. The property-based approach might be better if the server class is designed to be a component used with visual designers.
Historically, time-outs have been represented by integers. Integer time-outs can be hard to use because it is not obvious what the unit of the time-out is, and it is difficult to translate units of time into the commonly used millisecond.
A better approach is to use the TimeSpan structure as the time-out type. TimeSpan solves the problems with the integer time-outs mentioned above. The following code example shows how to use a time-out of type TimeSpan .
Public Class Server
Public Sub PerformOperation(timeout As TimeSpan)
' Insert code for the method here.
Console.WriteLine("performing operation with timeout {0}", _
timeout.ToString())
End Sub
End Class
public class Server
{
public void PerformOperation(TimeSpan timeout)
{
// Insert code for the method here.
Console.WriteLine("performing operation with timeout {0}",
timeout.ToString());
}
}
public ref class Server
{
public:
void PerformOperation(TimeSpan timeout)
{
// Insert code for the method here.
Console::WriteLine("performing operation with timeout {0}",
timeout.ToString());
}
};
If the time-out is set to TimeSpan(0), the method should throw an exception if the operation is not immediately completed. If the time-out is TimeSpan.MaxValue, the operation should wait forever without timing out, as if there were no time-out set. A server class is not required to support either of these values, but it should throw an ArgumentException if an unsupported time-out value is specified.
If a time-out expires and an exception is thrown, the server class should cancel the underlying operation.
If a default time-out is used, the server class should include a static property specifying the time-out to be used if the user does not specify one. The following code example demonstrates implementing a property that specifies the default time-out.
Class ServerWithDefault
Private Shared defaultTimeout As New TimeSpan(1000)
Public Overloads Sub PerformOperation()
Me.PerformOperation(DefaultOperationTimeout)
End Sub
Public Overloads Sub PerformOperation(timeout As TimeSpan)
' Insert code here.
Console.WriteLine("performing operation with timeout {0}", _
timeout.ToString())
End Sub
Public Shared ReadOnly Property DefaultOperationTimeout As TimeSpan
Get
Return defaultTimeout
End Get
End Property
End Class
class ServerWithDefault
{
static TimeSpan defaultTimeout = new TimeSpan(1000);
public void PerformOperation()
{
this.PerformOperation(DefaultOperationTimeout);
}
public void PerformOperation(TimeSpan timeout)
{
// Insert code here.
Console.WriteLine("performing operation with timeout {0}",
timeout.ToString());
}
public static TimeSpan DefaultOperationTimeout
{
get
{
return defaultTimeout;
}
}
}
ref class ServerWithDefault
{
private:
static TimeSpan defaultTimeout = TimeSpan(1000);
public:
void PerformOperation()
{
this->PerformOperation(DefaultOperationTimeout);
}
void PerformOperation(TimeSpan timeout)
{
// Insert code here.
Console::WriteLine("performing operation with timeout {0}",
timeout.ToString());
}
static property TimeSpan DefaultOperationTimeout
{
TimeSpan get()
{
return defaultTimeout;
}
}
};
Types that cannot resolve time-outs to the resolution of a TimeSpan should round the time-out to the nearest interval that can be accommodated. For example, a type that can wait only in one-second increments should round to the nearest second. An exception to this rule is when a value is rounded down to zero. In this case, the time-out should be rounded up to the minimum time-out possible. Rounding away from zero prevents busy-wait loops where a zero time-out value causes 100 percent processor utilization.
In addition, it is recommended that you throw an exception when a time-out expires instead of returning an error code. Expiration of a time-out means that the operation could not complete successfully and therefore should be treated and handled as any other run-time error. For more information, see Design Guidelines for Exceptions.
In the case of an asynchronous operation with a time-out, the callback function should be called and an exception thrown when the results of the operation are first accessed. This is illustrated in the following code example.
Sub OnReceiveCompleted(ByVal sender As System.Object, ByVal asyncResult As ReceiveCompletedEventArgs)
Dim queue As MessageQueue = CType(sender, MessageQueue)
' The following code will throw an exception
' if BeginReceive has timed out.
Dim message As Message = queue.EndReceive(asyncResult.AsyncResult)
Console.WriteLine(("Message: " + CStr(message.Body)))
queue.BeginReceive(New TimeSpan(1, 0, 0))
End Sub
void OnReceiveCompleted(Object sender, ReceiveCompletedEventArgs asyncResult)
{
MessageQueue queue = (MessageQueue) sender;
// The following code will throw an exception
// if BeginReceive has timed out.
Message message = queue.EndReceive(asyncResult.AsyncResult);
Console.WriteLine("Message: " + (string)message.Body);
queue.BeginReceive(new TimeSpan(1,0,0));
}
Portions Copyright 2005 Microsoft Corporation. All rights reserved.
Portions Copyright Addison-Wesley Corporation. All rights reserved.
For more information on design guidelines, see the "Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries" book by Krzysztof Cwalina and Brad Abrams, published by Addison-Wesley, 2005.