Occasionally you might want to create an application that can only have a single instance running on a machine at a time. For example, maybe you’ve a tray icon application or maybe an application that caches data for other applications to use etc.

We can achieve this by using a Mutex. A Mutex is very much like a Monitor/lock but can exist across multiple processes.

class Program
{
   static void Main(string[] args)
   {
      using(Mutex mutex = new Mutex(false, "some_unique_application_key"))
      {
         if(!mutex.WaitOne(TimeSpan.FromSeconds(3), false))
         {
            // another instance of the application must be running so exit
            return;
         }
         // Put code to run the application here
      }
   }
}

So in the above code we create a mutex with a unique key (“some_unique_application_key”). It’s best to use something like a URL and application name, so maybe “putridparrot.com\MyApp” as an example. The mutex is held onto for the life of the application for obvious reasons.

Next we try to WaitOne, we need a timeout on this otherwise we’ll just block at this point until the other instance closes down (or more specifically the Mutex on the other instance is released). So choose a time span of your choice. If the timeout occurs then false is returned from WaitOne and we can take it that another instance of the application is running, so we exit this instance of the application.

On the other hand if (within the timeout) WaitOne returns true then no other instance of the application (well more specifically the named Mutex) exists and we can go ahead and do whatever we need to run our application.

Basically a Semaphore allows us to set the initial count and the maximum number of threads than can enter a critical section.

The standard analogy of how a Semaphore works is the nightclub and bouncer analogy. So a nightclub has a capacity of X and the bouncer stops any clubbers entering once the nightclub reaches it’s capacity. Those clubbers can only enter when somebody leaves the nightclub.

In the case of a Semaphore we use WaitOne (or Wait on SemaphoreSlim) to act as the “bouncer” to the critical section and Release to inform the “bouncer” that a thread has left the critical section. For example

private readonly Semaphore semaphore = new Semaphore(3, 3);

private void MyCriticalSection(object o)
{
    sempahore.WaitOne();
    // do something
    semaphore.Release();
}

In the code above, say our calling method creates 20 threads all running the MyCriticalSection code, i.e.

for (int i = 0; i < 20; i++)
{
   Thread thread = new Thread(Run);
   thread.Start();
}

What happens is that the first three threads to arrive at semaphore.WaitOne will be allowed access to the code between the WaitOne and Release. All other threads block until one or more threads calls release. Thus ensuring that at any one time a maximum of (in this case) 3 threads can have access to the critical section.

Okay but the Semaphore allows an initial count (the first argument) so what’s that about ?

So let’s assume instead we have an initial count of 0, what happens then ?

private readonly Semaphore semaphore = new Semaphore(0, 3);

The above code still says we have a maximum of 3 threads allowed in our critical section, but it’s basically reserved 3 threads (maximum threads – initial count = reserved). In essence this is like saying the calling thread called WaitOne three times. The point being that when we fire off our 20 threads none will gain access to the critical section as all slots are reserved. So we would need to Release some slots before the blocked threads would be allowed into the critical section.

Obviously this is useful if we wanted to start a bunch of threads but we weren’t ready for the critical section to be entered yet.

However we can also set the initial count to another number, so let’s say we set it to 1 and maximum is still 3, now we have a capacity of 3 threads for our critical section but currently only one is allowed to enter the section until the reserved slots are released.

Note: It’s important to be sure that you only release the same number of times that you WaitOne or in the case of reserved slots you can only release up to the number of reserved slots.

To put it more simply, think reference counting. If you WaitOne you must call Release once and only once for each WaitOne. In the case of where we reserved 3 slots you can call Release(3) (or release less than 3) but you cannot release 4 as this would cause a SemaphoreFullException.

Important: Unlike a Mutex or Monitor/lock a Semaphore does not have thread affinity, in other words we can call Release from any thread, not just the thread which called WaitOne.

SemaphoreSlim

SemaphoreSlim, as the name suggests in a lightweight implementation of a Semaphore. The first thing to notice is that it uses Wait instead of WaitOne. The real purpose of the SemaphoreSlim is to supply a faster Semaphore (typically a Semaphore might take 1 ms per WaitOne and per Release, the SemaphoreSlim takes a quarter of this time, source ).

See also

Semaphore and SemaphoreSlim
Overview of Synchronization Primitives

and the brilliant Threading in C#

Occasionally we will either want to wrap some code in a Task to allow us to use async await and maybe creating an actual Task is not required. It could be legacy code, for example maybe we’re running a threadpool thread and want to make this appear as a async await capable method or maybe we are mocking a method in our unit tests.

In such cases we can use the TaskCompletionSource.

Let’s look at a slightly convoluted example. We have a third party (or binary only) library with a ExternalMethod class and a method called CalculateMeanAsync which uses the threadpool to execute some process and when the process is completed it calls the supplied callback Action passing a double value as a result. So it’s method signature might look like

public static void CalculateMeanValueAsync(Action<double> callback)

Now we want to use this method in a more async await style i.e. we’d like to call the method like this

double d = await CalculateMeanValueAsync();

We want to basically create a task to handle this but we want to manually control it from outside of the external method. We can thus use the TaskCompletedSource as a puppet task, writing something like the code below to wrap the external method call in an async await compatible piece of code.

public Task<double> CalculateMeanValueAsync()
{
   var tcs = new TaskCompletionSource<double>();

   ExternalMethod.CalculateMeanValueAsync(result => 
   {
      tcs.SetResult(result);
   });

   return tcs.Task;
}

What happens here is we create a TaskCompletionSource, and return a Task from it (which obviously may or may not return prior to the ExternalMethod.CalculateMeanValueAsync completion. Our calling code awaits our new CalculateMeanValueAsync method and when the callback Action is called we set the result using tcs.SetResult. This will now cause our TaskCompletionSource task to complete allows our code to continue to any code after the await in the calling method.

So we’ve essentially made a method appear as a Task style async method but controlling the flow via the TaskCompletionSource.

Another example might be in unit testing. When mocking an interface which returns a Task we could create a TaskCompletionSource and create a setup that returns it’s Task property, then set the mock result on the TaskCompletionSource. An example of such a test is listed below:

[Fact]
public async Task CalculateMean_ExpectCallToIStatisticCalculator_ResultShouldBeSuppliedByMock()
{
   TaskCompletionSource<double> tc = new TaskCompletionSource<double>();

   var mock = new Mock<IStatisticsCalculator>();
   mock.Setup(s => s.CalculateMeanAsync()).Returns(tc.Task);

   tc.SetResult(123.45);

   Calculator c = new Calculator(mock.Object);
   double mean = await c.CalculateMeanAsync();
   Assert.Equal(123.45, mean);

   mock.Verify();
}

So in this example we have a Calculator class which takes an IStatisticsCalculator (maybe it allows us to swap in and out different code for the calculations – I didn’t say it was a perfect example). Now in our test we want to create a mock (I’m using xUnit and Moq for this). We expect the Calculator to call the mock code and return the result from it.

As you can see the mock sets up the Task and then we set the result on the TaskCompletionSource to emulate a completion of the task.

Note: In this example you must return Task on your async test method or you may find the test passing even when it clearly shouldn’t

The Parallel static class gives us a few nice helper methods to carry out For, ForEach and Invoke methods in a parallel way. In reality we should say a potentially parallel way as there’s no guarantee they will be executed in separate tasks.

Parallel.ForEach

The ForEach method has several overloads, but basically this will loop through an IEnumerable passing each value into an Action. For example

int[] values = new[] { 3, 5, 1, 45, 12, 6, 49 };
Parallel.ForEach(values, Console.WriteLine);

The order in which the Console.WriteLine method is passed values is non-deterministic. In other words there’s no guarantee that 1 will be processed before 45 and so on. A key thing to remember is that all values will be processed before the Parallel.ForEach call returns control to the calling code. In other word a Wait stops the calling code to continue until all items in the enumerable object passed to the ForEach method have been processed.

This means if you run Parallel.ForEach from a UI thread then it will block even though each item placed into the ForEach list is potentially run in parallel. So you need to do something like

Task.Factory.StartNew(() => Parallel.ForEach(values, SomeAction));

Obviously if anything within the action needs to update the UI thread you’ll need to marshal it onto the UI thread.

Parallel.For

Along with the ForEach we also have the For loop. Which allows us to loop from a (inclusive) to b (exclusive) indices calling the supplied Action with the index. For example

int[] values = new[] { 3, 5, 1, 45, 12, 6, 49 };
Parallel.For(0, 2, i => Console.WriteLine(values[i]));

In this instance only “values” 3 and 5 will be passed to the action as we’re starting at (and including) index 0 and stopping before index 2 (as it’s exclusive). The same issues/traits exist for the For loop in that it is blocking etc.

Invoke

Finally we have Invoke which takes an array of Actions and calls them in a potentially parallel manner. Thus if we had several actions that we want to call potentially in parallel we can pass them to the Invoke method to be executed. For example

Parallel.Invoke(() => Console.WriteLine(3), 
                () => Console.WriteLine(4), 
                () => Console.WriteLine(5));

As per For and ForEach this method will potentially execute the actions in parallel but will block the calling thread.

Exceptions

If exceptions occur within the loops or invoke the Parallel library will throw an AggregationException which will contain one or more InnerExceptions.

ParallelLoopState

We can also pass a ParallelLoopState object into either the ForEach or For loops which allows us to Break or Stop a parallel loop as well as allowing us to find out whether a loop has exceptioned or is stopped etc.

ParallelOptions

Each of the For, ForEach and Invoke method have an overload which takes ParallelOptions. This enables us to set the maximum degree of parallelism, the task scheduler and the cancellation token.

The maximum degree of parallelism allows us to limit the possible number of threads uses in a Parallel method.

The cancellation token allows us a way to cancel a parallel task however this is a cooperative operations, in other words the algorithm writer must poll the cancellation token and take the action to cancel the algorithm etc. when the token is set to Cancel. Tasks are not interrupted or stopped in anyway, it’s down to the algorithm to detect and stop.

The task scheduler allows us to assign a custom scheduler to the parallel code.