AsyncLock: an async/await-friendly locking library for C# and .NET

One of the biggest improvements to C# and the .NET ecosystem in recent years has been the introduction of the async/await programming paradigm and the improvements it brings to both performance (no need to create thousands of threads if they spend most of their time blocking on IO) and productivity (no need to muck around with synchronization primitives or marshal exceptions between threads). While it takes a bit of getting used to, once you’ve gone async/await, you (literally) can’t go back.

async/await programming in C# has been repeatedly compared to a virus – once it gets into your codebase, it works its way throughout the rest, devouring all synchronous code that dares stand in its way. Due to the way it’s (quite cleverly) implemented in the compiler, you can’t really mix synchronous and asynchronous code with async/await the way you (painfully) could with BeginXXX and EndXXX and other IASync multithreaded programming approaches.

For the most part, that doesn’t cause too much of a problem.. except when it comes to marshaling access to non-thread-safe operations. If you’re an old WIN32 hat and your code is still built around mutexes and events, you’ll be fine (albeit running code that isn’t performing quite as awesomely as it could be). But if you’ve embraced the C# equivalent of a critical section and turned to using lock (...) { /* sensitive code here */ } everywhere, you’ll quickly run into a major gotcha: await and lock don’t place nice together at all, and you’re not allowed to use await statements in a lock block to prevent a deadlock (due to the way await with the remainder of the function body stuffed into a continuation, and the same thread resuming work elsewhere).

Here’s where our new AsyncLock library steps into the picture: it’s written from the ground up to be a safe and easy-to-use replacement for lock in pretty much all contexts. While there are plenty of libraries calling themselves “asynchronous locking libraries” or “async locks” out there, if you read the fine print you’ll see that they end up being fairly useless as they do not offer any sort of reëntrance support and will deadlock on recursion. The problem is that these are built around one of the most basic Win32 synchronization primitives: the semaphore. C#’s SemaphoreSlim is a first-class citizen of the brave, new async/await world and even has asynchronous WaitAsync method that can pause execution of the current thread context, returning control up the stack, until the semaphore becomes available. But the problem is that as a very low level primitive, SemaphoreSlim does not offer any sort of reëntrance support and will deadlock on recursion – if not used properly.

AsyncLock is an open source library/wrapper around SemaphoreSlim that adds reëntrance and recursion without taking await async/await functionality. Using AsyncLock couldn’t be simpler: simply swap any lock (lockObject) { ... } calls with using (lockObject.Lock()) { ... } and continue as before. But let’s see how (and why) AsyncLock works, primarily by looking at the pathological synchronization cases it doesn’t choke on.

A naïve solution to working around the limitation on awaiting inside a lock block would be to replace the lock with a semapahore, and then use current thread id to detect recursion, bypassing the lock as needed. At a first glance, it certainly does the trick:

class SemaphoreTest
{
    SemaphoreSlim lock = new SemaphoreSlim(1, 1); //initially available
    uint lockOwnerThreadId;

    public async Task Lock()
    {
        if (Thread.ThreadId == lockOwnerThreadId)
        {
            return true;
        }
        await lock.WaitAsync();
        return true;
    }

    public async Task Test()
    {
        Lock(lock);

        try
        {
            //do something not thread safe here
            if (someCondition)
            {
                //use recursion
                return await Test();
            }
        }
        finally
        {
            lock.Release(1);
        }
    }
}

It certainly works. We successfully obtain the lock in repeated calls to Test() and can successfully await the result of that function while holding the lock. But what happens in the following case? (For brevity, we’ve create an object called BadAsyncLock that has a method Lock() which implements the semaphore + thread id check code in the sample above.)

class ThreadIdConflict
{
    BadAsyncLock _lock = new BadAsyncLock();

    async void Button1_Click()
    {
        using (_lock.Lock())
        {
            await Task.Delay(-1); //at this point, control goes back to the UI thread
        }
    }

    async void Button2_Click()
    {
        using (_lock.Lock())
        {
            await Task.Delay(-1); //at this point, control goes back to the UI thread
        }
    }
}

That was the “code behind” from a very simple GUI application. There’s no recursion here, just two, distinct event handlers each needing exclusive access to the same variable or method, so we gave them an async lock that uses the thread ID + semaphore approach from the previous example. But here our workaround falls flat on its face. The devil is in the detail, and in this case, how async/await actually works and what it does.

One of the primary goals of async/await is to prevent needless blocking of the UI waiting on long-running activities to complete. Instead of having to create a new thread, pass data to and from the helper thread, use events to signal an abort, marshal exceptions back to the original thread for handling, etc. all you have to do is use async/await and the compiler takes care of the rest. But how it does so is key – the event handler Button1_Click() is executed synchronously just like it always would have been in legacy code. There’s no asynchronous work being done here, there is only ever just the one thread. Even when it encounters the await LongRunningTaskAsync() call, it still continues synchronous execution until it reaches something that cannot be executed without blocking – typically an IO (disk, network, etc) read/write or a wait on a semaphore or event. At that point, the current execution context is set aside and the remaining code (from the await to the end of the execution scope) is placed in a continuation. A event of sorts is set up that will signal that the asynchronous non-CPU-bound operation has completed/is ready, at which time the main thread will continue execution of the continuation that was set up earlier.

It’s not exactly accurate, but you can think of the main UI thread as doing something like this:

class UiThread
{
	Map<WaitHandle, Action> _callbacks;

	void MainThreadPump()
	{
		int callbackId = WaitHandle.WaitAny(_callbacks.Keys, Timeout.FromMilliseconds(100))
		if (callbackId != -1)
		{
			_callbacks.Values[callbackId]();
		}

		UpdateUi();
	}
}

The actual implementation of async/await obviously looks nothing like this; there’s a lot more to it than a simple global list of callbacks. But the idea is the same: the main thread runs the UI code. It pauses execution of an event handler (but not the actual thread itself) when a “hard” await is encountered and goes back to running the main UI. When the await has finished, the continuation is executed &emdash; again, on the main thread itself.

The key here is that it’s always the same thread doing the execution (except in the event of a non-awaited call to async function). The same thread that ran Button1_Click() then paused execution of that code due to an await call is the same thread that will run Button2_Click(). The execution of the remainder of the Button1_Click code has only been set aside, not actually paused. Meaning that when we come to execute Button2_Click while Button1_Click() has obtained “exclusive” access to a code section via the semaphore, the semaphore will still be unavailable, but the OwningThreadId comparison will pass since it is the same thread that is executing both methods! In traditional, sequential/blocking execution, you can assume same thread == recursion, but that assumption completely falls apart in the wonderful world of async/await.

So what’s the solution? We need some other way to determine recursion, something that doesn’t rely on the thread id to make that decision. Fortunately, there’s a very simple (and obvious) answer: we have access to the stack trace via the Environment class. Why don’t we use that to decide whether we are recursively obtaining a lock?

Update 5/25/2017: AsyncLock is now using a different, more-efficient method of detecting recursion based off the task ID and not the stack trace.

Let’s update our Lock.Lock() method to something more like this:

List _stackTraces = new List();
async Task Lock()
{
	if (!lock.locked)
	{
		_stackTraces.Add(Environment.StackTrace);
		lock.Wait();
		return true;
	}
	else if (_stackTraces.Peek().IsParentOf(Environment.StackTrace))
	{
		_stackTraces.Add(Environment.StackTrace);
		return true;
	}
	else
	{
		//wait for the lock to become available somehow
		return true;
	}
}

In the above code, we are using the value of Environment.StackTrace to determine whether or not we are being called in a reëntrance situation. Assume the call to Lock() doesn’t litter the stack trace, and that there is a helper method StackTrace.IsParentOf(StackTrace) that can be used to tell if the current call is a child of the previously stored stack trace. (Also assume the obvious race conditions in the code above don’t exist!) Is this enough? If we were to use this code with the previous test case (Button1_Click() vs Button2_Click()) it would certainly appear to work. The stack trace during the execution of Button1_Click() would not match that of the thread during the execution of Button2_Click(), but if Button1_Click() were to call Button2_Click() (or itself) for some reason, the owning stack id would match and the lock attempt would go through.

However, this approach would fail to handle a case that the first solution (based on the comparison of thread ids) would have handily caught:

class StackTraceConflict
{
    BadAsyncLock _lock = new BadAsyncLock();

    async void DoSomething()
    {
        using (_lock.Lock())
        {
            await Task.Delay(-1);
        }
    }

    void DoManySomethings()
    {
        while(true)
        {
            DoSomething(); //no wait here!
        }
    }
}

In this code sample, several threads are spun up¹ to simultaneously execute DoSomething() several times on several, different threads. The catch? Since they’re all starting execution from the same spot, the stack trace for all threads is the same and our stack trace-based approach to lock resolution would completely fail!

As such, the proper solution is to combine both the thread id and the stack trace to get a complete picture of who is calling whom and where all threads and continuations currently stand. Here’s some code that both demonstrates a tricky test case that our AsyncLock library gets right and at the same time just how easy it is to use AsyncLock in both its synchronous and asynchronous locking variants:

class AsyncLockTest
{
    AsyncLock _lock = new AsyncLock();
    void Test()
    {
        //the code below will be run immediately (and asynchronously, in a new thread)
        Task.Run(async () =>
        {
            //this first call to LockAsync() will obtain the lock without blocking
            using (await _lock.LockAsync())
            {
                //this second call to LockAsync() will be recognized as being a reëntrant call and go through
                using (await _lock.LockAsync())
                {
                    //we now hold the lock exclusively and no one else can use it for 1 minute
                    await Task.Delay(TimeSpan.FromMinutes(1));
                }
            }
        }).Wait(TimeSpan.FromSeconds(30));

        //this call to obtain the lock is synchronously made from the main thread
        //It will, however, block until the asynchronous code which obtained the lock above finishes
        using (_lock.Lock())
        {
            //now we have obtained exclusive access
        }
    }
}

In the above code, we have a single thread that executes both a recursive and non-recursive attempt to obtain the same lock. The 30 second wait on the task is to make sure the task starts before the main code does; and once there, the lock will first be obtained normally (non-contested), then once more as a reëntrant call, which will be allowed. The task will then pause its execution once it encounters the Task.Delay() call for one minute, during which time it still holds exclusive access to the shared resource. Once the 30 second grace period expires, the main thread will resume execution, and will try to obtain the (already locked) AsyncLock instance. The initial attempt to obtain the lock will fail, as it is still held by the (paused) task. 30 seconds later, the task finishes its wait and releases the lock, the main thread obtains the lock, and code execution continues.

The code snippet above also demonstrates the two different lock options that AsyncLock exposes: AsyncLock.Lock() and AsyncLock.LockAsync() They are both basically identical beneath the hood, except that the async method embraces the async/await paradigm and will cede its execution until a point in the future when the lock becomes available and it can attempt to re-obtain it. This makes await lock.LockAsync() non-blocking and its use is highly encouraged.

AsyncLock is released as open source (MIT-licensed) library on GitHub. Please feel free to fork it and create issues and/or pull requests as you see fit. AsyncLock is also available on Nuget. AsyncLock compiles against .NET Standard and has no outside dependencies, making it even easier to use in all your applications and is especially designed

1. Not necessarily, it is at the discretion of the compiler and dependent on the configuration and state of the thread pool, but potentially so for sure. ↩