Examples and Programming Models

An approach I like, which seems to be somewhat common amongst developers using Apple's Grand Central Dispatch serial queues is to use a SerialQueue inside your class to protect it's internal data structures and to perform async operations. The queue is private and the public methods forward to the queue.

This is quite nice as simple operations like retrieving property values can use DispatchSync while longer-running operations can use DispatchAsync and return results to the caller asynchronously (or not at all).

In this example, the queue acts as an enhanced "lock", where it is mostly used as an ordinary lock, but enables some async behaviour with the Set method being able to asynchronously write to the backing store without blocking the caller. The serial queue behaviour means that multiple writes will always complete in the correct order, and future reads will block until the writes are complete, guaranteeing consistency

class DataManager
{
    readonly SerialQueue m_queue = new SerialQueue();
    readonly Dictionary<string, object> m_records = new Dictionary<string, object>();
    readonly string m_filePath;

    public int Count => m_queue.DispatchSync(() => m_records.Count);

    public DataManager(string filePath)
    {
        m_filePath = filePath;
        m_queue.DispatchSync(() => {
            var data = File.ReadAllBytes(m_filePath);
            var json = Encoding.UTF8.GetString(data);
            foreach (var kv in (Dictionary<string, object>)Deserialize(json))
                m_records[kv.Key] = kv.Value;
        });
    }

    public object Get(string key) => m_queue.DispatchSync(() => m_records[key]);

    public void Set(string key, object item)
    {
        m_queue.DispatchAsync(() => {
            m_records[key] = item;
            var json = Serialize(m_records);
            var data = Encoding.UTF8.GetBytes(json);
            File.WriteAllBytes(m_filePath, data);
        });
    }

    static string Serialize(object data) { } // writes m_records to JSON
    static object Deserialize(string json) { } // writes m_records to JSON
}

If this were a GCD serial queue in Objective-C or swift, we'd have to stop there, however this is C#, and we have async. The above example can be modified to return a Task so is compatible with async/await. The basic/naive approach is to simply wrap our DispatchAsync calls with tasks by using TaskCompletionSource. This is a little unwieldy, however it works well.

public Task<object> GetAsync(string key)
{
    var tcs = new TaskCompletionSource<object>();
    m_queue.DispatchAsync(() => tcs.SetResult(m_records[key]));
    return tcs.Task;
}

public Task SetAsync(string key, object item)
{
    var tcs = new TaskCompletionSource<bool>();
    m_queue.DispatchAsync(() => {
        m_records[key] = item;
        var json = Serialize(m_records);
        var data = Encoding.UTF8.GetBytes(json);
        File.WriteAllBytes(m_filePath, data);
        tcs.SetResult(true);
    });
    return tcs.Task;
}

Callers can now do something like this:

var inventory = await dataManager.GetAsync("inventory");
var newInventory = Update(inventory);
await dataManager.SetAsync("inventory", newInventory);

However, the SerialQueue has inbuilt support for async/await, so we can do better than that.
Since 2.1.0, you can await directly on the queue itself to jump to it. We can refactor the above code to this (which I hope you find compelling. I certainly thought it was pretty neat):

public async Task<object> GetAsync(string key)
{
    await m_queue; // jump onto the serial queue
    
    return m_records[key];
}

public async Task SetAsync(string key, object item)
{
    await m_queue; // jump onto the serial queue

    m_records[key] = item;
    var json = Serialize(m_records);
    var data = Encoding.UTF8.GetBytes(json);
   File.WriteAllBytes(m_filePath, data);
}

And as above, the caller can still do this;

var inventory = await dataManager.GetAsync("inventory");
var newInventory = Update(inventory);
await dataManager.SetAsync("inventory", newInventory);

The default behaviour of the await operator is to capture the current SynchronizationContext and return on that. In laymans terms this means if you put the above code in your UI thread, it will all run on the UI thread, while the SerialQueue offloads the work to a background thread.

The nice thing about a SerialQueue in this example (as opposed to just regular tasks) is that it still preserves the order of operations and ensures only one thing is running at a time so the underlying m_records and other private data won't get corrupted by race conditions