4

Recently I came across a Microsoft interface with a quite unusual API:

public interface IHostApplicationLifetime
{
    public CancellationToken ApplicationStarted { get; }
    public CancellationToken ApplicationStopping { get; }
    public CancellationToken ApplicationStopped { get; }
}

The documentation of the property ApplicationStopping suggests confusingly that this property is actually an event (emphasis added):

Triggered when the application host is performing a graceful shutdown. Shutdown will block until this event completes.

It seems that what should be a traditional EventHandler event, has been replaced with a CancellationToken property. This is how I expected this interface to be:

public interface IHostApplicationLifetime
{
    public event EventHandler ApplicationStarted;
    public event EventHandler ApplicationStopping;
    public event EventHandler ApplicationStopped;
}

My question is, are these two notifications mechanisms equivalent? If not, what are the pros and cons of each approach, from the perspective of an API designer? In which circumstances a CancellationToken property is superior to a classic event?

28
  • use an event vs a cancellation token very different concepts and meaning altogether. Could you please update your post with what you've tried, what isn't working and expected output?
    – Trevor
    Oct 7, 2020 at 13:31
  • An event, I am assuming you mean System.Threading.AutoResetEvent or ilk, is very different from a cancellation token. Oct 7, 2020 at 13:39
  • A CancelationToken can be baked into a method and make it cancelable. How would you do the same thing with an event? Can you update your question with an example of an alternative of, say, the BlockingCollection<T>.Take method, that uses events instead of a CancelationToken? Oct 7, 2020 at 13:57
  • 2
    There is a very simple reason for the CancellationToken over EventHandler. With an EventHandler, you would not know if ApplicationStarted before your EventHandler registration ran. This means you would need to add a bool IsApplicationStarted { get; } property. The CancellationToken would also implicitely handle lifetime of the Event.
    – Aron
    Oct 8, 2020 at 9:39
  • 2
    There is a blog post explaining this architectural decision here: andrewlock.net/… Does that make it more clear? Oct 9, 2020 at 18:20

2 Answers 2

4

Microsoft should have been more careful with the documentation. It is confusing to describe the CancellationTokens as events to be "triggered".

I'm certainly not a C# language expert so hopefully the community will let us know if I'm missing import points. But let me take a stab a few things...

So your question: are they equivalent.. only in the sense that they both provide a way to register and invoke callbacks. But for a lot of other reasons, no.

CancellationTokens are wrapper around CancellationTokenSource. They tie into the Task implementation. They are thread safe. They can be invoked externally and can be invoked by a timer. You can chain multiple CancellationTokenSource together. They maintain state which indicates if they are, or are not, canceled and you can query that state.

C# events, the language feature, are in the words of the documentation a special multicast delegate. They can only be invoked within the class where they are declared. They are not really thread safe. They are baked into XAML and WPF.

I'm not going to comment too much on where one is superior to the other as they are very different. In the normal course I don't think you'd consider events in situations where you would consider CancellationTokens. They overlapped in the case of IHostApplicationLifetime mainly because of bad documentation and the redesign of the hosting infrastructure for .NET Core. As @EricLippert mentioned this link provides a great overview of that.

2
  • +1 for the link! Regarding thread safety, after having read Stephen Cleary's article, it occurred to me that a CancellationToken may suffer from a similar race condition as the events: It is possible to dispose a CancellationTokenRegistration from Thread1 while the registered callback is already running on Thread2. Oct 9, 2020 at 21:50
  • But then I noticed the method Unregister that returns a bool. If the result is true, then you can safely dispose any disposable resources that are referenced by the callback, because it is guaranteed that the callback is neither running, nor will run in the future. I think that this feedback is the key that eliminates the race conditions that plague the events! Oct 9, 2020 at 21:50
3

The CancellationToken is not equivalent with the classic events. The differences are numerous, with the most obvious being that the CancellationToken can be triggered (canceled) only once. So in case it makes sense for an event to be raised more than once, there is no dilemma: a classic event is the only option. So the comparison must be narrowed to the cases of one-time-events, where the CancellationToken has many advantages, and only one potential disadvantage. First the advantages:

  1. The CancellationToken notifies its subscribers not only about a cancellation that may happen in the future, but also about a cancellation that has already happened. Trying to do the same in a multithreaded application with a classic event and a bool field creates a race condition. It is possible for the event to be triggered between checking the bool field and subscribing to the event, in which case the notification will be lost.

  2. It is possible to attach and detach an event handler to a CancellationToken, even if the handler is an anonymous lambda function. This is not possible with a classic event. The detach operator (-=) requires the same handler that was passed previously at the subscription (+=), so the handler must be assigned to a variable, or be a named function.

  3. It is possible to pass a CancellationToken as an argument to a method of another class, to allow registering (and optionally unregistering) a callback. This is not possible with the classic events. The C# language does not allow it. The only way to achieve this functionality is by passing attach/detach lambdas as arguments to the method: otherClass.SomeMethod(h => this.MyEvent += h, h => this.MyEvent -= h). This is complicated, awkward, and less readable than otherClass.SomeMethod(this.MyToken).

  4. There are thousands of APIs that accept a CancellationToken parameter. This makes the consumption of this kind of notification very convenient in a multitude of scenarios. On the contrary the APIs that can consume events by accepting addHandler/removeHandler arguments are extremely rare (example: Observable.FromEventPattern).

  5. Unregistering a callback from a CancellationToken with the method Unregister¹ gives a bool feedback whether the callback has already been invoked or not. On the contrary unsubscribing from a classic event with the -= operator gives no feedback. This means that in a multithreaded application the caller has no way of knowing whether the detached handler is already running on another thread, so that it can safely dispose any disposable resources referenced by the handler. This leaves the caller with awkward options like not disposing the resources, or catching possible ObjectDisposedExceptions inside the handler.

The disadvantage of using a CancellationToken as an one-time-notification is purely semantic. This type is strongly associated with the concept of cancellation, so using it to notify that, for example, something started or stopped, has great chances to create confusion.

¹ Not available for the .NET Framework, so this advantage does not apply for this platform.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.