Friendlier error messages in case of cache access timeouts

In case accessing the object cache times out, don't spew an ugly message
like

  main.CacheLockException: Error! WaitForSingleObject returns 258, last error 183

instead, mention that it's a time out error and that there's an
environment variable which can be set to avoid this issue.

Author: Frerich Raabe

CHANGELOG.md

@@ -11,6 +11,9 @@ clcache changelog
    which can be used to make clcache generate profiling information. The
    generated data can be processed into a final report using a new
    `showprofilereport.py` script.
+ * Improvement: Timeout errors when accessing the cache now generate friendlier
+   error messages mentioning the possibility to work around the issue using the
+   `CLCACHE_OBJECT_CACHE_TIMEOUT_MS` environment variable.
 
 ## clcache 3.2.0 (2016-07-28)
 

clcache.py

@@ -221,6 +221,7 @@ class CacheLock(object):
     can be used in 'with' statements. """
     INFINITE = 0xFFFFFFFF
     WAIT_ABANDONED_CODE = 0x00000080
+    WAIT_TIMEOUT_CODE = 0x00000102
 
     def __init__(self, mutexName, timeoutMs):
         mutexName = 'Local\\' + mutexName
@@ -247,9 +248,15 @@ def acquire(self):
         result = windll.kernel32.WaitForSingleObject(
             self._mutex, wintypes.INT(self._timeoutMs))
         if result not in [0, self.WAIT_ABANDONED_CODE]:
-            errorString = 'Error! WaitForSingleObject returns {result}, last error {error}'.format(
-                result=result,
-                error=windll.kernel32.GetLastError())
+            if result == self.WAIT_TIMEOUT_CODE:
+                errorString = \
+                    'Failed to acquire cache lock after {}ms; ' \
+                    'try setting CLCACHE_OBJECT_CACHE_TIMEOUT_MS environment variable to a larger value.'.format(
+                        self._timeoutMs)
+            else:
+                errorString = 'Error! WaitForSingleObject returns {result}, last error {error}'.format(
+                    result=result,
+                    error=windll.kernel32.GetLastError())
             raise CacheLockException(errorString)
         self._acquired = True