Timeouts and TimeSpans

Huh? We’re waiting how long?

You don't have to work for a long time in software development to come across code similar to the following

void DoSomething()
{
   var data = GetData(5000);
}
Data GetData(int timeout)
{
   Thread.Sleep(timeout); // or something that takes a while
}

There is one major issue with this code that specifically relates to its readability and consequently its long term maintainability.

Can you spot it?

Don’t worry if you couldn’t. This is a very easy flaw to miss and is usually not uncovered until someone is tasked with maintaining or changing a block of code like this.

What is a “timeout”

The issue with the code block above is that the unit of the “timeout” value is unclear at the point of use.

5000 of what? Seconds, micro-, milli-, nano-, cpu ticks? *gasp* maybe it’s minutes! You just can’t be sure unless you check.

This one coding issue has in the past caused me to loose countless minutes in extreme code deep-diving and wading through disassembled code just to figure out exactly what unit is being implied for “timeout”.

Issues such as these can also cause more subtle and hard to track down issues related to unit mismatches as the code is extended or used by other programmers. What if one programmer is expecting milliseconds but others supply microseconds? Sometimes these issues cause multi-million dollar losses as was the case with the Mars Climate Orbiter in 1999.

For every problem there is a solution

Here are three simple alternatives that can help you avoid making or mitigate this kind of an issue and significantly improve your and your colleagues life’s in the long run.

The code examples below are presented in C# but apply to most modern programming languages.

Solution 1: Working under tight constraints

By simply tagging the relative function and parameter names with the explicit timeout unit a lot of uncertainty has been removed. If changing the function name is impossible due to legacy constraints, just changing the parameter name to reflect the unit will help immensely and can usually be done without sacrificing any backwards compatibility (exceptions to this are when relying on named parameters).

void CoolAndClear()
{
   var data = GetDataWithTimeoutMSec(5000);
}

Data GetDataWithTimeoutMSec(int timeoutInMilliseconds)
{
   Thread.Sleep(timeoutInMilliseconds);
}

Solution 2: Having full freedom to change

The absolute best case scenario is when you’re able to modify the parameter type to be a non-ambiguous type. An example of this would be to change the timeout variable’s type from int to a System.TimeSpan struct instead.

void CoolAndClear()
{
   var data = GetData(TimeSpan.FromMilliSeconds(5000));
}

Data GetData(TimeSpan timeout)
{
   Thread.Sleep(timeout);
}

In this case the exact unit is explicitly stated at the point of use and all ambiguity is removed. This also provides solutions for special cases such as when specifying an Infinite timeout value or special hard-coded custom values.

Note that it would not be advisable to mix both Solutions 1 and 2. Their combination would introduce even more ambiguity than before. Such as this statement

GetDataWithTimeoutMsec( TimeSpan.FromMinutes(10) )

Solution 2: Extra credit

When using the System.TimeSpan or other custom object there exists the possibility in C# to create extension methods to make the code even more concise and simpler to read

void CoolAndClear()
{
   var data = GetData(5000.MilliSeconds());
   // or
   var data = GetData(20.Seconds());
   // or
   var data = GetData(3.Minutes());
}

If you like this approach then feel free to download the skeleton code for these extension methods from my OneDrive.

Solution 3: Working under impossible constraints

In some cases you might find yourself working under almost impossible constraints where modifying any part of the code is not permitted. In those cases adding clear documentation would still be a huge improvement.

void CoolStuff()
{
   var data = GetData(5000);
}

/// <summary>
/// Gets data with a user supplied
/// <see cref=”timeout”/> in milliseconds.
/// </summary>
/// <param name=”timeout”>The timeout value in milliseconds. 
/// Value of 0 will cause the function to return immediately. 
/// Value of -1 will specify an infinite waiting period.</param>
Data GetData(int timeout)
{
   Thread.Sleep(timeout); // or something that takes a while
}

Actually come to think of it, even if you end up choosing to do either solution 1 or 2, always do Solution 3 as well.

.     .     .

This entry can also be found on Medium:
https://medium.com/@sverrirs/timeouts-and-timespans-ca05ae5c2d15#.usxppi1h8

[Arhived] Timeouts and TimeSpans: Huh? We're waiting how long?

Update 4 Feb 2016 There is a more up to date version of this article here. 

You don't have to work for a long time in software development to come across code similar to the following:

void DoSomething()
{
   var data = GetDataWithTimeout(5000);
   //... continued
}
Data GetDataWithTimeout(int timeout)
{
   //...
   Thread.Sleep(timeout);
   //...
}

There is one major issue with this code that specifically relates to its readability and consequently its long term maintainability:

1. The unit of the timeout value is unclear at the point of use!

This has caused me to loose countless minutes to drilling to extreme depths to figure out exactly what unit is being implied on the timeout.

How to avoid this loss of productivity and immediate code rot?

Here are two simple alternatives that can help you avoid making this kind of a mistake and significantly improve your and your colleagues life's in the long run.

1. Explicitly mentioning the timeout unit

By simply tagging the relative function and parameter names with the unit a lot of uncertainty has been removed. If changing the function name is impossible due to legacy constraints, just changing the parameter name will help immensely and can usually be done without sacrificing any backwards compatibility.

void DoSomething()
{
   var data = GetDataWithTimeoutMSec(5000);
   //... continued
}
Data GetDataWithTimeoutMSec(int timeoutInMilliseconds)
{
   //...
   Thread.Sleep(timeoutInMilliseconds);
   //...
}

2. Relying on TimeSpan and helpful extension methods

In the case where you're able to modify the parameter type no renaming is necessary as the code can be modified to use the System.TimeSpan struct instead. Actually I would advise against also using the renaming tactic if this approach is used as combining them will introduce more ambiguity than before (calling GetDataWithTimeoutMsec(TimeSpan.FromMinutes(10)) would be confusing.

void DoSomething()
{
   var data = GetDataWithTimeout(5000.MilliSeconds());

   //... continued

   // Other examples

   var data = GetDataWithTimeout(20.Seconds());
   var data = GetDataWithTimeout(3.Minutes());
}
Data GetDataWithTimeout(TimeSpan timeout)
{
   //...
   Thread.Sleep(timeout);
   //...
}

The skeleton code for the Seconds()/Minutes() extension methods can be downloaded from my OneDrive here.

This entry is also available on LinkedIn:
https://www.linkedin.com/pulse/timeouts-c-timespans-huh-were-waiting-how-long-sverrir-sigmundarson

2 Feb 2016 An updated version of this entry can now be found on Medium:
https://medium.com/@sverrirs/timeouts-and-timespans-ca05ae5c2d15#.usxppi1h8