2007-05-11 21:15:35 +00:00
|
|
|
#region CPL License
|
|
|
|
/*
|
|
|
|
Nuclex Framework
|
2009-01-07 19:05:29 +00:00
|
|
|
Copyright (C) 2002-2009 Nuclex Development Labs
|
2007-05-11 21:15:35 +00:00
|
|
|
|
|
|
|
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
|
2007-07-24 20:15:19 +00:00
|
|
|
|
2007-04-16 17:18:16 +00:00
|
|
|
using System;
|
2008-06-05 19:26:36 +00:00
|
|
|
using System.Collections.Generic;
|
2007-04-16 17:18:16 +00:00
|
|
|
using System.Threading;
|
|
|
|
|
|
|
|
namespace Nuclex.Support.Tracking {
|
|
|
|
|
2008-06-05 19:19:00 +00:00
|
|
|
/// <summary>Base class for background processes the user can wait on</summary>
|
2007-04-16 17:18:16 +00:00
|
|
|
/// <remarks>
|
|
|
|
/// <para>
|
|
|
|
/// By encapsulating long-running operations which will ideally be running in
|
2008-12-03 18:58:20 +00:00
|
|
|
/// a background thread in a class that's derived from <see cref="Transaction" />
|
2008-03-26 21:03:49 +00:00
|
|
|
/// 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.
|
2007-04-16 17:18:16 +00:00
|
|
|
/// </para>
|
|
|
|
/// <para>
|
2008-12-03 18:58:20 +00:00
|
|
|
/// You can register callbacks which will be fired once the <see cref="Transaction" />
|
2008-03-26 21:03:49 +00:00
|
|
|
/// 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
|
2008-12-03 18:58:20 +00:00
|
|
|
/// possible to construct a transaction just-in-time when it is explicitely being
|
2008-03-26 21:03:49 +00:00
|
|
|
/// asked for.
|
2007-04-16 17:18:16 +00:00
|
|
|
/// </para>
|
|
|
|
/// </remarks>
|
2008-12-03 18:58:20 +00:00
|
|
|
public abstract class Transaction {
|
2007-04-16 17:18:16 +00:00
|
|
|
|
2008-12-03 18:58:20 +00:00
|
|
|
#region class EndedDummyTransaction
|
2007-04-16 17:18:16 +00:00
|
|
|
|
2008-12-03 18:58:20 +00:00
|
|
|
/// <summary>Dummy transaction which always is in the 'ended' state</summary>
|
|
|
|
private class EndedDummyTransaction : Transaction {
|
2007-04-16 17:18:16 +00:00
|
|
|
|
2008-12-03 18:58:20 +00:00
|
|
|
/// <summary>Initializes a new ended dummy transaction</summary>
|
|
|
|
public EndedDummyTransaction() {
|
2007-04-16 17:18:16 +00:00
|
|
|
OnAsyncEnded();
|
|
|
|
}
|
|
|
|
|
|
|
|
}
|
|
|
|
|
2008-12-03 18:58:20 +00:00
|
|
|
#endregion // class EndedDummyTransaction
|
2007-04-16 17:18:16 +00:00
|
|
|
|
2008-12-03 18:58:20 +00:00
|
|
|
/// <summary>A dummy transaction that's always in the 'ended' state</summary>
|
2007-04-16 17:18:16 +00:00
|
|
|
/// <remarks>
|
|
|
|
/// Useful if an operation is already complete when it's being asked for or
|
2008-12-03 18:58:20 +00:00
|
|
|
/// when a transaction that's lazily created is accessed after the original
|
2007-04-16 17:18:16 +00:00
|
|
|
/// operation has ended already.
|
|
|
|
/// </remarks>
|
2008-12-03 18:58:20 +00:00
|
|
|
public static readonly Transaction EndedDummy = new EndedDummyTransaction();
|
2007-04-16 17:18:16 +00:00
|
|
|
|
2008-12-03 18:58:20 +00:00
|
|
|
/// <summary>Will be triggered when the transaction has ended</summary>
|
2008-06-05 19:26:36 +00:00
|
|
|
/// <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>
|
2008-06-11 20:06:23 +00:00
|
|
|
public virtual event EventHandler AsyncEnded {
|
2008-06-05 19:26:36 +00:00
|
|
|
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 ;-)
|
2008-06-11 20:06:23 +00:00
|
|
|
if(ReferenceEquals(this.endedEventSubscribers, null)) {
|
|
|
|
this.endedEventSubscribers = new List<EventHandler>();
|
2008-06-05 19:26:36 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
// Subscribe the event handler to the list
|
2008-06-11 20:06:23 +00:00
|
|
|
this.endedEventSubscribers.Add(value);
|
2008-06-05 19:26:36 +00:00
|
|
|
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 {
|
|
|
|
|
2009-04-01 20:32:22 +00:00
|
|
|
if(!this.ended) {
|
|
|
|
lock(this) {
|
|
|
|
if(!this.ended) {
|
|
|
|
|
|
|
|
// 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);
|
2008-06-05 19:26:36 +00:00
|
|
|
|
2009-04-01 20:32:22 +00:00
|
|
|
// Unsubscribing a non-subscribed delegate from an event is allowed and
|
|
|
|
// should not throw an exception.
|
|
|
|
if(eventHandlerIndex != -1) {
|
|
|
|
this.endedEventSubscribers.RemoveAt(eventHandlerIndex);
|
|
|
|
}
|
|
|
|
}
|
2008-06-11 20:06:23 +00:00
|
|
|
|
2008-06-05 19:26:36 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
}
|
|
|
|
}
|
2007-04-16 17:18:16 +00:00
|
|
|
|
2008-06-11 20:06:23 +00:00
|
|
|
/// <summary>Waits until the background process finishes</summary>
|
|
|
|
public virtual void Wait() {
|
2009-05-28 19:55:48 +00:00
|
|
|
if(!this.ended) {
|
|
|
|
WaitHandle.WaitOne();
|
|
|
|
}
|
2008-06-11 20:06:23 +00:00
|
|
|
}
|
|
|
|
|
2009-01-13 18:50:52 +00:00
|
|
|
#if !COMPACTFRAMEWORK
|
|
|
|
|
2008-06-11 20:06:23 +00:00
|
|
|
/// <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) {
|
2009-05-28 19:55:48 +00:00
|
|
|
if(this.ended) {
|
|
|
|
return true;
|
|
|
|
}
|
|
|
|
|
2008-06-11 20:06:23 +00:00
|
|
|
return WaitHandle.WaitOne(timeout, false);
|
|
|
|
}
|
|
|
|
|
2009-01-13 18:50:52 +00:00
|
|
|
#endif // !COMPACTFRAMEWORK
|
|
|
|
|
2008-06-11 20:06:23 +00:00
|
|
|
/// <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) {
|
2009-05-28 19:55:48 +00:00
|
|
|
if(this.ended) {
|
|
|
|
return true;
|
|
|
|
}
|
|
|
|
|
2008-06-11 20:06:23 +00:00
|
|
|
return WaitHandle.WaitOne(timeoutMilliseconds, false);
|
|
|
|
}
|
|
|
|
|
2008-12-03 18:58:20 +00:00
|
|
|
/// <summary>Whether the transaction has ended already</summary>
|
2008-06-11 20:06:23 +00:00
|
|
|
public virtual bool Ended {
|
2007-04-16 18:31:59 +00:00
|
|
|
get { return this.ended; }
|
2007-04-16 17:18:16 +00:00
|
|
|
}
|
|
|
|
|
2008-12-03 18:58:20 +00:00
|
|
|
/// <summary>WaitHandle that can be used to wait for the transaction to end</summary>
|
2008-06-11 20:06:23 +00:00
|
|
|
public virtual WaitHandle WaitHandle {
|
2007-04-16 17:18:16 +00:00
|
|
|
get {
|
2007-04-19 18:18:34 +00:00
|
|
|
|
2007-04-16 18:31:59 +00:00
|
|
|
// The WaitHandle will only be created when someone asks for it!
|
2007-04-19 18:18:34 +00:00
|
|
|
// 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
|
2007-09-25 19:37:45 +00:00
|
|
|
// the second one is referenced by this.doneEvent and thus gets set in the end.
|
2008-06-05 19:19:00 +00:00
|
|
|
if(this.doneEvent == null) {
|
|
|
|
lock(this) {
|
2008-06-05 19:26:36 +00:00
|
|
|
if(this.doneEvent == null) {
|
2007-04-16 18:31:59 +00:00
|
|
|
this.doneEvent = new ManualResetEvent(this.ended);
|
2008-06-05 19:26:36 +00:00
|
|
|
}
|
2007-04-16 18:31:59 +00:00
|
|
|
}
|
2007-04-16 17:18:16 +00:00
|
|
|
}
|
|
|
|
|
2008-06-05 19:26:36 +00:00
|
|
|
// We can be sure the doneEvent has been created now!
|
2007-04-16 17:18:16 +00:00
|
|
|
return this.doneEvent;
|
2008-06-05 19:26:36 +00:00
|
|
|
|
2007-04-16 17:18:16 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
/// <summary>Fires the AsyncEnded event</summary>
|
|
|
|
/// <remarks>
|
2007-07-01 19:27:40 +00:00
|
|
|
/// <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
|
2008-12-03 18:58:20 +00:00
|
|
|
/// the OnAsyncEnded() method is called on any instance of transaction that's
|
2007-07-01 19:27:40 +00:00
|
|
|
/// being created. This method also must not be called more than once.
|
|
|
|
/// </para>
|
2007-04-16 17:18:16 +00:00
|
|
|
/// </remarks>
|
|
|
|
protected virtual void OnAsyncEnded() {
|
2007-07-01 19:27:40 +00:00
|
|
|
|
2008-12-03 18:58:20 +00:00
|
|
|
// Make sure the transaction is not ended more than once. By guaranteeing that
|
|
|
|
// a transaction can only be ended once, we allow users of this class to
|
2007-04-20 18:04:19 +00:00
|
|
|
// skip some safeguards against notifications arriving twice.
|
2008-06-05 19:19:00 +00:00
|
|
|
lock(this) {
|
2007-04-19 18:18:34 +00:00
|
|
|
|
2007-07-01 19:27:40 +00:00
|
|
|
// No double lock here, this is an exception that indicates an implementation
|
2009-04-01 20:32:22 +00:00
|
|
|
// error that will not be triggered under normal circumstances. We don't need
|
2007-07-01 19:27:40 +00:00
|
|
|
// to waste any effort optimizing the speed at which an implementation fault
|
2009-04-01 20:32:22 +00:00
|
|
|
// will be reported ;-)
|
2008-06-05 19:19:00 +00:00
|
|
|
if(this.ended)
|
2008-12-03 18:58:20 +00:00
|
|
|
throw new InvalidOperationException("The transaction has already been ended");
|
2007-04-19 18:18:34 +00:00
|
|
|
|
2007-04-20 18:04:19 +00:00
|
|
|
this.ended = true;
|
|
|
|
|
2008-06-05 19:26:36 +00:00
|
|
|
// 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
|
2009-04-01 20:32:22 +00:00
|
|
|
// performance loss and prevent the doneEvent from being signalled needlessly.
|
2008-06-05 19:26:36 +00:00
|
|
|
if(this.doneEvent != null)
|
|
|
|
this.doneEvent.Set();
|
2007-04-16 17:18:16 +00:00
|
|
|
|
2008-06-05 19:26:36 +00:00
|
|
|
}
|
2007-04-16 17:18:16 +00:00
|
|
|
|
2009-04-01 20:32:22 +00:00
|
|
|
// 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
|
2008-06-11 20:06:23 +00:00
|
|
|
if(!ReferenceEquals(this.endedEventSubscribers, null)) {
|
|
|
|
for(int index = 0; index < this.endedEventSubscribers.Count; ++index) {
|
|
|
|
this.endedEventSubscribers[index](this, EventArgs.Empty);
|
|
|
|
}
|
2009-04-01 20:32:22 +00:00
|
|
|
this.endedEventSubscribers = null;
|
2008-06-05 19:26:36 +00:00
|
|
|
}
|
2007-04-19 18:18:34 +00:00
|
|
|
|
2007-04-16 17:18:16 +00:00
|
|
|
}
|
|
|
|
|
2008-06-05 19:26:36 +00:00
|
|
|
/// <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>
|
2008-06-11 20:06:23 +00:00
|
|
|
protected volatile List<EventHandler> endedEventSubscribers;
|
2008-06-05 19:26:36 +00:00
|
|
|
/// <summary>Whether the operation has completed yet</summary>
|
2008-06-11 20:06:23 +00:00
|
|
|
protected volatile bool ended;
|
2008-12-03 18:58:20 +00:00
|
|
|
/// <summary>Event that will be set when the transaction is completed</summary>
|
2007-04-16 17:18:16 +00:00
|
|
|
/// <remarks>
|
|
|
|
/// This event is will only be created when it is specifically asked for using
|
|
|
|
/// the WaitHandle property.
|
|
|
|
/// </remarks>
|
2008-06-11 20:06:23 +00:00
|
|
|
protected volatile ManualResetEvent doneEvent;
|
2007-04-16 17:18:16 +00:00
|
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
} // namespace Nuclex.Support.Tracking
|