/// <summary>
/// <para>Starts execution of your operation, which is a sequence of asynchronous steps, identified by a <see cref="AsynchronousExecutionPlan"/> delegate object. The timeout of this operation indicates one of the operations created by the exection plan timed out, which stops the operation whenever the timeout occurred.</para>
/// </summary>
/// <example> This example shows how to start an execution plan.
/// <code>
/// var waitHandle = new ManualResetEvent(false);
/// try
/// {
/// Operation operation = Operation.Start(MyExecutionPlan, op => waitHandle.Set(), MyContextEntryDelegate, MyContextExitDelegate);
/// waitHandle.WaitOne(TimeSpan.FromSeconds(5)); // wait 5 seconds for the execution plan to complete
/// }
/// finally
/// {
/// waitHandle.Close();
/// }
/// </code>
/// </example>
/// <param name="executionPlan">
/// <para>The delegate object, that is the simplified approach to expressing a chain of asynchronous steps. This parameter cannot be null.</para>
/// </param>
/// <param name="doneCallback">
/// <para>The callback that the operation will call when the operation completes. doneCallback cannot be null.</para>
/// </param>
/// <param name="contextSwitchEntryDelegate">
/// <para>The context switch entry delegate. Whenever the operation may change threads, this delegate will be called before executing your code. Must be non-null if the exit delegate is non-null.</para>
/// </param>
/// <param name="contextSwitchExitDelegate">
/// <para>The context switch exit delegate. Whenever the operation may change threads, this delegate will be called after executing your code. Must be non-null if the entry delegate is non-null.</para>
/// </param>
/// <returns>
/// <para>An operation that manages the asynchrnous execution and timeouts of the opeartions from Create().</para>
/// </returns>
/// <exception cref="ArgumentNullException">
/// <para>The argument <paramref name="executionPlan"/> is <see langword="null"/>.</para>
/// <para>-or-</para>
/// <para>The argument <paramref name="doneCallback"/> is <see langword="null"/>.</para>
/// <para>-or-</para>
/// <para>The argument <paramref name="contextSwitchEntryDelegate"/> is <see langword="null"/> while the argument <paramref name="contextSwitchExitDelegate"/> was not null.</para>
/// <para>-or-</para>
/// <para>The argument <paramref name="contextSwitchExitDelegate"/> is <see langword="null"/> while the argument <paramref name="contextSwitchEntryDelegate"/> was not null.</para>
/// </exception>
public static Operation Start(AsynchronousExecutionPlan executionPlan, Action <Operation> doneCallback, Action contextSwitchEntryDelegate, Action contextSwitchExitDelegate)
{
if (executionPlan == null)
{
throw new ArgumentNullException("executionPlan");
}
if (doneCallback == null)
{
throw new ArgumentNullException("doneCallback");
}
if (contextSwitchEntryDelegate == null && contextSwitchExitDelegate != null)
{
throw new ArgumentNullException("contextSwitchEntryDelegate");
}
if (contextSwitchEntryDelegate != null && contextSwitchExitDelegate == null)
{
throw new ArgumentNullException("contextSwitchExitDelegate");
}
var headOperation = CreateStartOperation(doneCallback,
contextSwitchEntryDelegate, contextSwitchExitDelegate);
var operationSteps = executionPlan(headOperation);
headOperation.BeginNextStep(operationSteps.GetEnumerator());
return(headOperation);
}
/// <summary>
/// Starts execution of your operation, which is a sequence of asynchronous steps, identified by a <see cref="AsynchronousExecutionPlan"/> delegate object.
/// The timeout of this operation indicates one of the operations created by the exection plan timed out, which stops the
/// operation whenever the timeout occurred.
/// </summary>
/// <example> This example shows how to start an execution plan.
/// <code>
/// var waitHandle = new ManualResetEvent(false);
/// try
/// {
/// Operation operation = Operation.Start(MyExecutionPlan, op => waitHandle.Set());
/// waitHandle.WaitOne(TimeSpan.FromSeconds(5)); // wait 5 seconds for the execution plan to complete
/// }
/// finally
/// {
/// waitHandle.Close();
/// }
/// </code>
/// </example>
/// <param name="executionPlan">The delegate object, that is the simplified approach to expressing a chain of asynchronous steps. This parameter cannot be null.</param>
/// <param name="doneCallback">The callback that the operation will call when the operation completes. doneCallback cannot be null.</param>
/// <returns>
/// An <see cref="Operation"/> that manages the asynchrnous execution and timeouts of the opeartions from Create().
/// </returns>
/// <exception cref="ArgumentNullException">
/// <para>The argument <paramref name="executionPlan"/> is <see langword="null"/>.</para>
/// <para>-or-</para>
/// <para>The argument <paramref name="doneCallback"/> is <see langword="null"/>.</para>
/// </exception>
public static Operation Start(AsynchronousExecutionPlan executionPlan, Action <Operation> doneCallback)
{
return(Start(executionPlan, doneCallback, null, null));
}