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

classDataManager{readonlySerialQueuem_queue=newSerialQueue();readonlyDictionary<string,object>m_records=newDictionary<string,object>();readonlystringm_filePath;publicintCount=>m_queue.DispatchSync(()=>m_records.Count);publicDataManager(stringfilePath){m_filePath=filePath;m_queue.DispatchSync(()=>{vardata=File.ReadAllBytes(m_filePath);varjson=Encoding.UTF8.GetString(data);foreach(varkvin(Dictionary<string,object>)Deserialize(json))m_records[kv.Key]=kv.Value;});}publicobjectGet(stringkey)=>m_queue.DispatchSync(()=>m_records[key]);publicvoidSet(stringkey,objectitem){m_queue.DispatchAsync(()=>{m_records[key]=item;varjson=Serialize(m_records);vardata=Encoding.UTF8.GetBytes(json);File.WriteAllBytes(m_filePath,data);});}staticstringSerialize(objectdata){}// writes m_records to JSONstaticobjectDeserialize(stringjson){}// 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.

publicTask<object>GetAsync(stringkey){vartcs=newTaskCompletionSource<object>();m_queue.DispatchAsync(()=>tcs.SetResult(m_records[key]));returntcs.Task;}publicTaskSetAsync(stringkey,objectitem){vartcs=newTaskCompletionSource<bool>();m_queue.DispatchAsync(()=>{m_records[key]=item;varjson=Serialize(m_records);vardata=Encoding.UTF8.GetBytes(json);File.WriteAllBytes(m_filePath,data);tcs.SetResult(true);});returntcs.Task;}

Callers can now do something like this:

varinventory=awaitdataManager.GetAsync("inventory");varnewInventory=Update(inventory);awaitdataManager.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):

publicasyncTask<object>GetAsync(stringkey){awaitm_queue;// jump onto the serial queuereturnm_records[key];}publicasyncTaskSetAsync(stringkey,objectitem){awaitm_queue;// jump onto the serial queuem_records[key]=item;varjson=Serialize(m_records);vardata=Encoding.UTF8.GetBytes(json);File.WriteAllBytes(m_filePath,data);}

And as above, the caller can still do this;

varinventory=awaitdataManager.GetAsync("inventory");varnewInventory=Update(inventory);awaitdataManager.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