Nuclex.Support/Source/Tracking/Waitable.cs

249 lines
9.7 KiB
C#
Raw Normal View History

#region CPL License
/*
Nuclex Framework
Copyright (C) 2002-2008 Nuclex Development Labs
This library is free software; you can redistribute it and/or
modify it under the terms of the IBM Common Public License as
published by the IBM Corporation; either version 1.0 of the
License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
IBM Common Public License for more details.
You should have received a copy of the IBM Common Public
License along with this library
*/
#endregion
using System;
using System.Collections.Generic;
using System.Threading;
namespace Nuclex.Support.Tracking {
/// <summary>Base class for background processes the user can wait on</summary>
/// <remarks>
/// <para>
/// By encapsulating long-running operations which will ideally be running in
/// a background thread in a class that's derived from <see cref="Waitable" />
/// you can wait for the completion of the operation and optionally even receive
/// feedback on the achieved progress. This is useful for displaying a progress
/// bar, loading screen or some other means of entertaining the user while he
/// waits for the task to complete.
/// </para>
/// <para>
/// You can register callbacks which will be fired once the <see cref="Waitable" />
/// task has completed. This class deliberately does not provide an Execute()
/// method or anything similar to clearly seperate the initiation of an operation
/// from just monitoring it. By omitting an Execute() method, it also becomes
/// possible to construct a Waitable just-in-time when it is explicitely being
/// asked for.
/// </para>
/// </remarks>
public abstract class Waitable {
#region class EndedDummyWaitable
/// <summary>Dummy waitable which always is in the 'ended' state</summary>
private class EndedDummyWaitable : Waitable {
/// <summary>Initializes a new ended dummy waitable</summary>
public EndedDummyWaitable() {
OnAsyncEnded();
}
}
#endregion // class EndedDummyWaitable
/// <summary>A dummy waitable that's always in the 'ended' state</summary>
/// <remarks>
/// Useful if an operation is already complete when it's being asked for or
/// when a waitable that's lazily created is accessed after the original
/// operation has ended already.
/// </remarks>
public static readonly Waitable EndedDummy = new EndedDummyWaitable();
/// <summary>Will be triggered when the Waitable has ended</summary>
/// <remarks>
/// If the process is already finished when a client registers to this event,
/// the registered callback will be invoked synchronously right when the
/// registration takes place.
/// </remarks>
public virtual event EventHandler AsyncEnded {
add {
// If the background process has not yet ended, add the delegate to the
// list of subscribers. This uses the double-checked locking idiom to
// avoid taking the lock when the background process has already ended.
if(!this.ended) {
lock(this) {
if(!this.ended) {
// The subscriber list is also created lazily ;-)
if(ReferenceEquals(this.endedEventSubscribers, null)) {
this.endedEventSubscribers = new List<EventHandler>();
}
// Subscribe the event handler to the list
this.endedEventSubscribers.Add(value);
return;
}
}
}
// If this point is reached, the background process was already finished
// and we have to invoke the subscriber manually as promised.
value(this, EventArgs.Empty);
}
remove {
lock(this) {
// Only try to remove the event handler if the subscriber list was created,
// otherwise, we can be sure that no actual subscribers exist.
if(!ReferenceEquals(this.endedEventSubscribers, null)) {
int eventHandlerIndex = this.endedEventSubscribers.IndexOf(value);
// Unsubscribing a non-subscribed delegate from an event is allowed and should
// not throw an exception.
if(eventHandlerIndex != -1) {
this.endedEventSubscribers.RemoveAt(eventHandlerIndex);
}
}
}
}
}
/// <summary>Waits until the background process finishes</summary>
public virtual void Wait() {
WaitHandle.WaitOne();
}
/// <summary>Waits until the background process finishes or a timeout occurs</summary>
/// <param name="timeout">
/// Time span after which to stop waiting and return immediately
/// </param>
/// <returns>
/// True if the background process completed, false if the timeout was reached
/// </returns>
public virtual bool Wait(TimeSpan timeout) {
return WaitHandle.WaitOne(timeout, false);
}
/// <summary>Waits until the background process finishes or a timeout occurs</summary>
/// <param name="timeoutMilliseconds">
/// Number of milliseconds after which to stop waiting and return immediately
/// </param>
/// <returns>
/// True if the background process completed, false if the timeout was reached
/// </returns>
public virtual bool Wait(int timeoutMilliseconds) {
return WaitHandle.WaitOne(timeoutMilliseconds, false);
}
/// <summary>Whether the Waitable has ended already</summary>
public virtual bool Ended {
get { return this.ended; }
}
/// <summary>WaitHandle that can be used to wait for the Waitable to end</summary>
public virtual WaitHandle WaitHandle {
get {
// The WaitHandle will only be created when someone asks for it!
// We can *not* optimize this lock away since we absolutely must not create
// two doneEvents -- someone might call .WaitOne() on the first one when only
// the second one is referenced by this.doneEvent and thus gets set in the end.
if(this.doneEvent == null) {
lock(this) {
if(this.doneEvent == null) {
this.doneEvent = new ManualResetEvent(this.ended);
}
}
}
// We can be sure the doneEvent has been created now!
return this.doneEvent;
}
}
/// <summary>Fires the AsyncEnded event</summary>
/// <remarks>
/// <para>
/// This event should be fired by the implementing class when its work is completed.
/// It's of no interest to this class whether the outcome of the process was
/// successfull or not, the outcome and results of the process taking place both
/// need to be communicated seperately.
/// </para>
/// <para>
/// Calling this method is mandatory. Implementers need to take care that
/// the OnAsyncEnded() method is called on any instance of Waitable that's
/// being created. This method also must not be called more than once.
/// </para>
/// </remarks>
protected virtual void OnAsyncEnded() {
// Make sure the waitable is not ended more than once. By guaranteeing that
// a waitable can only be ended once, we allow users of this class to
// skip some safeguards against notifications arriving twice.
lock(this) {
// No double lock here, this is an exception that indicates an implementation
// error that will not be triggered under normal circumstances. We don't want
// to waste any effort optimizing the speed at which an implementation fault
// will be noticed.
if(this.ended)
throw new InvalidOperationException("The Waitable has already been ended");
this.ended = true;
// Doesn't really need a lock: if another thread wins the race and creates
// the event after we just saw it being null, it would be created in an already
// set state due to the ended flag (see above) being set to true beforehand!
// But since we've got a lock ready, we can even avoid that 1 in a million
// performance loss and prevent a second doneEvent from being created.
if(this.doneEvent != null)
this.doneEvent.Set();
}
if(!ReferenceEquals(this.endedEventSubscribers, null)) {
// Fire the ended events to all event subscribers. We can freely use the list
// without synchronization at this point on since once this.ended is set to true,
// the subscribers list will not be accessed any longer
for(int index = 0; index < this.endedEventSubscribers.Count; ++index) {
this.endedEventSubscribers[index](this, EventArgs.Empty);
}
}
}
/// <summary>List of event handler which have subscribed to the ended event</summary>
/// <remarks>
/// Does not need to be volatile since it's only accessed inside
/// </remarks>
protected volatile List<EventHandler> endedEventSubscribers;
/// <summary>Whether the operation has completed yet</summary>
protected volatile bool ended;
/// <summary>Event that will be set when the waitable is completed</summary>
/// <remarks>
/// This event is will only be created when it is specifically asked for using
/// the WaitHandle property.
/// </remarks>
protected volatile ManualResetEvent doneEvent;
}
} // namespace Nuclex.Support.Tracking