Cues

bool IsDone

The IsDone property is used to check if a cue has already been marked as 'done'.  Once a cue is done, subsequent attempts to send messages or mark the cue as 'done' will throw an InvalidOperationException.

if(cue.IsDone) {
    Console.WriteLine("Cue is marked as 'done'");
} else {
    Console.WriteLine("Cue is 'ready'");
}

event Action<bool> OnCompletion

The OnCompletion event is triggered when a cue is marked as 'done'.  The boolean parameter to the event handler indicates if the cue as marked as 'done' using Done (=true) or Fail (=false).

cue.OnCompletion += delegate(bool success) {
    if(success) {
        Console.WriteLine("Cue closed with Done()");
    } else {
        Console.WriteLine("Cue closed with Fail()");
    }
}

IOutCue<T> Add(T item)

The Add() method adds an item to a cue.  An InvalidOperationException is thrown if the cue has already been marked as 'done'.  The Add() method returns a reference to the out-cue so that multiple calls can be chained.

cue.Add(1).Add(2).Add(3).Done();

void Done()

The Done() method marks a cue as 'done'.  Registered OnCompletion event handlers are triggered with 'true' as their argument.  As soon as a cue is marked as 'done', all subsequent attempts to send messages or mark the cue as 'done' will throw an InvalidOperationException.

cue.Done();

void Fail()

The Fail() method marks a cue as 'done'.  Registered OnCompletion event handlers are triggered with 'false' as their argument.  As soon as a cue is marked as 'done', all subsequent attempts to send messages or mark the cue as 'done' will throw an InvalidOperationException.

Note: The difference between Done() and Fail() is subtle. Done() must be called when all items have been added successfully.  Fail() can be called if the sender can't add more items, because of a failure.  If the Fail() method is not called on failure, then the receiver will wait until it times out (since no further Add() or Done() calls occur).  If the Fail() method is called, the receiver will timeout immediately since it now knows that no additional items will ever be added.  Therefore, calling Fail() is an optional, but optimizes clean-up of runtime resources.

cue.Fail();

Let's illustrate this point with a slightly more involved example.  Let's say we have a method that processes a batch of floating-point numbers by computing their inverse and sending them to a cue.  Here is how we might deal with a division by zero error which would halt processing:

void ComputeInverse(float[] numbers, Cue<float> resultCue) {
    foreach(float number in numbers) {
        try {
            resultCue.Add(1.0 / number);
        } catch {
            resultCue.Fail();
            throw;
        }
    }
    resultCue.Done();
}

bool HasPending

The HasPending property is used to check if a cue might still contain more items.  This property will return 'true' if the cue has not been marked as 'done' or it has been marked as 'done', but there are still unreceived items in it.

if(cue.HasPending) {
    Console.WriteLine("Cue could contain more items");
} else {
    Console.WriteLine("Cue has no more items");
}

event Action<Exception> OnAsyncException

The OnAsyncException event is triggered when an exception occurs during the invocation of an asynchronous handler.  It is equivalent to a generic catch statement around the invoked handler.  The event includes the exception that was thrown as an argument.

cue.OnAsyncException += delegate(Exception e) {
    Console.WriteLine("An exception was thrown " + e);
}

CueState Wait(int millisecondsTimeout, out T item)

This Wait() method blocks the current thread until an item is received or the specified amount of time has elapsed.

Warning: This method should only be used when the receiving thread is not running on a threadpool thread.  Blocking threadpool threads may lead to an unresponsive system.  Whenever possible, use the asynchronous or iterative implementations of this method.

Returns: This method returns either 'Success', 'Done', or 'Timeout'.  'Success' indicates that the method received an item successfully.  'Done' indicates that no item was received because the cue is marked as 'done'.  And 'Timeout' indicates that no item was received because the alloted time has elapsed.

int item;
CueState state = cue.Wait(1000, out item);
switch(state) {
case CueState.Success:
    Console.WriteLine("An item was received: " + item);
    break;
case CueState.Done:
    Console.WriteLine("No item was received because the cue is marked as 'done'");
    break;
case CueState.Timeout:
    Console.WriteLine("No item was received because the operation timed out");
    break;
}

CueState WaitMany(int count, int millisecondsTimeout, out IList<T> list)

This WaitMany() method blocks the current thread until the specified number of items are received or the specified amount of time has elapsed.

Warning: This method should only be used when the receiving thread is not running on a threadpool thread.  Blocking threadpool threads may lead to an unresponsive system.  Whenever possible, use the asynchronous or iterative implementations of this method.

Exceptions: An ArgumentException is thrown if 'count' is zero or less.

Returns: This method returns either 'Success', 'Done', or 'Timeout'.  'Success' indicates that the method received all requested items.  'Done' indicates that less items than requested were received because the cue is marked as 'done'.  And 'Timeout' indicates that less items than requested were received because the alloted time has elapsed.

IList<int> items;
CueState state = cue.WaitMany(10, 1000, out items);
switch(state) {
case CueState.Success:
    Console.WriteLine("All items were received.");
    break;
case CueState.Done:
    Console.WriteLine("Less items than expected were received because the cue is marked as 'done'");
    break;
case CueState.Timeout:
    Console.WriteLine("Less items than expected were received because the operation timed out");
    break;
}
Console.WriteLine("Items received: " + items.Count);

CueState WaitAll(int millisecondsTimeout, out IList<T> list)

This WaitAll() method blocks the current thread until all items are received or the specified amount of time has elapsed.

Warning: This method should only be used when the receiving thread is not running on a threadpool thread.  Blocking threadpool threads may lead to an unresponsive system.  Whenever possible, use the asynchronous or iterative alternative to this method.

Returns: This method returns either 'Done' or 'Timeout'.  'Done' indicates all items were received and that the cue is now marked as 'done'.  'Timeout' indicates that the operation finished early because the alloted time has elapsed.

IList<int> items;
CueState state = cue.WaitAll(1000, out items);
switch(state) {
case CueState.Done:
    Console.WriteLine("All items were received");
    break;
case CueState.Timeout:
    Console.WriteLine("Operation timed out with a partial result");
    break;
}
Console.WriteLine("Items received: " + items.Count);

CueState WaitAll(int millisecondsTimeout, Predicate<T> handler)

This WaitAll() method blocks the current thread, invoking the 'handler' for each item it receives or the specified amount of time has elapsed between receiving any two items.  Processing is aborted if the 'handler' returns 'false'.

Warning: This method should only be used when the receiving thread is not running on a threadpool thread.  Blocking threadpool threads may lead to an unresponsive system.  Whenever possible, use the asynchronous or iterative alternative to this method.

Returns: This method returns either 'Success', 'Done', or 'Timeout'.  'Success' indicates that processing was interrupted by the 'handler'. 'Done' indicates all items were processed and that the cue is now marked as 'done'.  'Timeout' indicates that the operation finished early because the alloted time elapsed between two items.

CueState state = cue.WaitAll(1000, delegate(int i) {
    Console.WriteLine("Received " + i);
    return true;
});
switch(state) {
case CueState.Success:
    Console.WriteLine("Processing stopped and cue may contain additional items");
    break;
case CueState.Done:
    Console.WriteLine("All items were received");
    break;
case CueState.Timeout:
    Console.WriteLine("Operation timed out");
    break;
}

void Wait(int millisecondsTimeout, CueHandler<T> handler)

This Wait() method invokes the 'handler' when an item is received or the specified amount of time has elapsed.  Since this method does not block and wait, the 'handler' may be invoked at any time during the application's execution.

Note: The CueState argument take on the same values as the return value for the synchronous Wait() method.

cue.Wait(1000, delegate(int item, CueState state) {
    switch(state) {
    case CueState.Success:
        Console.WriteLine("An item was received: " + item);
        break;
    case CueState.Done:
        Console.WriteLine("The cue is now marked as 'done'");
        break;
    case CueState.Timeout:
        Console.WriteLine("The operation has timed out");
        break;
    }
});

void WaitMany(int count, int millisecondsTimeout, CueListHandler<T> handler)

This WaitMany() method invokes the 'handler' when the specified number of items have been received or the specified amount of time has elapsed.  Since this method does not block and wait, the 'handler' may be invoked at any time during the application's execution.

Exceptions: An ArgumentException is thrown if 'count' is zero or less.

Note: The CueState argument take on the same values as the return value for the synchronous WaitMany() method.

cue.WaitMany(10, 1000, delegate(IList<int> items, int expectedCount, CueState state) {
    switch(state) {
    case CueState.Success:
        Console.WriteLine("All items were received.");
        break;
    case CueState.Done:
        Console.WriteLine("Less items than expected were received because the cue is marked as 'done'");
        break;
    case CueState.Timeout:
        Console.WriteLine("Less items than expected were received because the operation timed out");
        break;
    }
    Console.WriteLine("Items received: " + items.Count);
    Console.WriteLine("Items expected: " + expectedCount);
});

void WaitAll(int millisecondsTimeout, CueListHandler<T> handler)

This WaitAll() method invokes the 'handler' when all items have been received or the specified amount of time has elapsed.  Since this method does not block and wait, the 'handler' may be invoked at any time during the application's execution.

Note: This method is very similar to WaitMany() except that the 'expectedCount' is always equal to the actual count of items received.

Note: The CueState argument take on the same values as the return value for the synchronous WaitAll() method.

cue.WaitAll(1000, delegate(IList<int> items, int expectedCount, CueState state) {
    switch(state) {
    case CueState.Success:
        Console.WriteLine("All items were received.");
        break;
    case CueState.Done:
        Console.WriteLine("Less items than expected were received because the cue is marked as 'done'");
        break;
    case CueState.Timeout:
        Console.WriteLine("Less items than expected were received because the operation timed out");
        break;
    }
    Console.WriteLine("Items received: " + items.Count);
});

void WaitAll(int millisecondsTimeout, CueHandlerPredicate<T> handler)

This WaitAll() method invokes the 'handler' each time an item is received or the specified amount of time has elapsed between receiving any two items.  Processing is aborted if the 'handler' returns 'false'.  Since this method does not block and wait, the 'handler' may be invoked at any time during the application's execution.

cue.WaitAll(1000, delegate(int i, CueState state) {
    switch(state) {
    case CueState.Success:
        Console.WriteLine("Received " + i);
        break;
    case CueState.Done:
        Console.WriteLine("All items were received");
        break;
    case CueState.Timeout:
        Console.WriteLine("Operation timed out");
        break;
    }
    return true;
});

CueYield<T> Wait(int millisecondsTimeout)

This Wait() method suspends the current execution context using the 'yield' statement.  The context is restored when an item is received or the specified amount of time has elapsed.  This technique is called iterative programming and has the advantage of combining the best of synchronous and asynchronous programming.

Returns: This method returns a CueYield<T> instance where T is of the same type as in Cue<T>.  The CueYield.State returns the state of the cue when the operation completed.  It can be either 'Success', 'Done', or 'Timeout'.  'Success' indicates that the method received an item successfully.  'Done' indicates that no item was received because the cue is marked as 'done'.  And 'Timeout' indicates that no item was received because the alloted time has elapsed.  Received items can be accessed with the Items property ([] in C#).

IEnumerator<ITask> MyIterativeMethod(Cue<int> cue) {
    CueYield<int> cy;
    while(true) {
        yield return cy = cue.Wait(1000);
        switch(cy.State) {
            case CueState.Success:
            Console.WriteLine("An item was received: " + cy[0]);
            break;
        case CueState.Done:
            Console.WriteLine("The cue is now marked as 'done'");
            yield break;
        case CueState.Timeout:
            Console.WriteLine("The operation has timed out");
            yield break;
        }
    }
}

CueYield<T> WaitMany(int count, int millisecondsTimeout)

This WaitMany() method suspends the current execution context using the 'yield' statement.  The context is restored when the specified number of items have been received or the specified amount of time has elapsed.  This technique is called iterative programming and has the advantage of combining the best of synchronous and asynchronous programming.

Returns: This method returns a CueYield<T> instance where T is of the same type as in Cue<T>.  The CueYield.State returns the state of the cue when the operation completed.  It can be either be 'Success', 'Done', or 'Timeout'.  'Success' indicates that the method received all requested items.  'Done' indicates that less items than requested were received because the cue has been marked as 'done'.  And 'Timeout' indicates that less items than requested were received because the alloted time elapsed.  Received items can be accessed with the Items property ([] in C#).  The expected number of items can be read with CueYield.ExpectedCount.  The actual number of received items can be read with CueYield.Count.  'Success' always means that the expected count matches the actual count.

IEnumerator<ITask> MyIterativeMethod(Cue<int> cue) {
    CueYield<int> cy;
    yield return cy = cue.WaitMany(10, 1000);
    switch(cy.State) {
    case CueState.Success:
        Console.WriteLine("All items were received.");
        break;
    case CueState.Done:
        Console.WriteLine("Less items than expected were received because the cue is marked as 'done'");
        break;
    case CueState.Timeout:
        Console.WriteLine("Less items than expected were received because the operation timed out");
        break;
    }
    Console.WriteLine("Items received: " + cy.Count);
}

CueYield<T> WaitAll(int millisecondsTimeout)

This WaitAll() method suspends the current execution context using the 'yield' statement.  The context is restored when all items have been received or the specified amount of time has elapsed. This technique is called iterative programming and has the advantage of combining the best of synchronous and asynchronous programming.

Returns: This method returns a CueYield<T> instance where T is of the same type as in Cue<T>.  The CueYield.State returns the state of the cue when the operation completed.  It can be either be 'Done' or 'Timeout'.  'Done' indicates that all items were received and that the cue is now marked as 'done'.  'Timeout' indicates that the operation finished because the alloted time elapsed.  Received items can be accessed with the Items property ([] in C#).  The number of received items can be read with CueYield.Count.

IEnumerator<ITask> MyIterativeMethod(Cue<int> cue) {
    CueYield<int> cy;
    yield return cy = cue.WaitAll(1000);
    switch(cy.State) {
    case CueState.Done:
        Console.WriteLine("All items were received");
        break;
    case CueState.Timeout:
        Console.WriteLine("Operation timed out with a partial result");
        break;
    }
    Console.WriteLine("Items received: " + cy.Count);
}