Priorities are measured with an enumerated type, or enum, named Priority. The Priority enum looks like this:

//Priority -- Instead of priorities like 1, 2, 3, they have names.
enum Priority      // See the article "Enumerating the Charms
                   // of the Enum" on this book's Web site.
{
  Low, Medium, High
}

Any object going into the PriorityQueue must "know" its own priority. (A general object-oriented principle states that objects should be responsible for themselves.)

One way to enforce this requirement is to insist that all shippable objects implement the IPrioritizable interface, which follows:

//IPrioritizable -- Define a custom interface: Classes that can be added to
//                 PriorityQueue must implement this interface.
interface IPrioritizable  // Any class can implement this interface.
{
  Priority Priority { get; }
}

Class Package implements the interface by providing a fleshed-out implementation for the Priority property:

public Priority Priority
{
  get { return _priority; }
}

You encounter the other side of this enforceable requirement in the declaration of class PriorityQueue, in the later section "Saving PriorityQueue for last."

PriorityQueue is a wrapper class that hides three ordinary Queue<T> objects, one for each priority level. Here's the first part of PriorityQueue, showing the three underlying queues (now generic):

//PriorityQueue -- A generic priority queue class
//   Types to be added to the queue *must* implement IPrioritizable interface.
class PriorityQueue<T> where T : IPrioritizable
{
  // Queues -- the three underlying queues: all generic!
  private Queue<T> _queueHigh = new Queue<T>();
  private Queue<T> _queueMedium = new Queue<T>();
  private Queue<T> _queueLow = new Queue<T>();
  // The rest will follow shortly ...

These lines declare three private data members of type Queue<T> and initialize them by creating the Queue<T> objects. I say more later in this chapter about that odd-looking class declaration line above the "subqueue" declarations.

Enqueue() adds an item of type T to the PriorityQueue. This method's job is to look at the item's priority and put it into the correct underlying queue. In the first line, it gets the item's Priority property and switches based on that value. To add the item to the high-priority queue, for example, Enqueue() turns around and enqueues the item in the underlying queueHigh. Here's PriorityQueue's Enqueue() method:

//Enqueue -- Prioritize T and add it to correct queue; an item of type T.
//   The item must know its own priority.
public void Enqueue(T item)
{
  switch (item.Priority) // Require IPrioritizable to ensure this property.
  {
    case Priority.High:
      _queueHigh.Enqueue(item);
      break;
    case Priority.Medium:
      _queueMedium.Enqueue(item);
      break;
    case Priority.Low:
      _queueLow.Enqueue(item);
      break;
    default:
      throw new ArgumentOutOfRangeException(
        item.Priority.ToString(),
        "bad priority in PriorityQueue.Enqueue");
  }
}

Dequeue()'s job is a bit trickier than Enqueue()'s: It must locate the highest-priority underlying queue that has contents and then retrieve the front item from that subqueue. Dequeue() delegates the first part of the task, finding the highest-priority queue that isn't empty, to a private TopQueue() method (described in the next section). Then Dequeue() calls the underlying queue's Dequeue() method to retrieve the frontmost object, which it returns. Here's how Dequeue() works:

//Dequeue -- Get T from highest-priority queue available.
public T Dequeue()
{
  // Find highest-priority queue with items.
  Queue<T> queueTop = TopQueue();
  // If a non-empty queue is found
  if (queueTop != null & queueTop.Count > 0)
  {
    return queueTop.Dequeue(); // Return its front item.
  }
  // If all queues empty, return null (you could throw exception).
  return default(T); // What's this? See discussion.
}

A difficulty arises only if none of the underlying queues have any packages — in other words, the whole PriorityQueue is empty. What do you return in that case? Dequeue() returns null. The client — the code that calls PriorityQueue.Dequeue() — should check the Dequeue() return value in case it's null. Where's the null it returns? It's that odd duck, default(T), at the end. I deal with default(T) a little later in this chapter.

Dequeue() relies on the private method TopQueue() to find the highest-priority, nonempty underlying queue. TopQueue() just starts with queueHigh and asks for its Count property. If it's greater than zero, the queue contains items, so TopQueue() returns a reference to the whole underlying queue that it found. (The TopQueue() return type is Queue<T>.) On the other hand, if queueHigh is empty, TopQueue() tries queueMedium and then queueLow.

What happens if all subqueues are empty? TopQueue() could return null, but it's more useful to simply return one of the empty queues. When Dequeue() then calls the returned queue's Dequeue() method, it returns null. TopQueue() works like this:

//TopQueue -- What's the highest-priority underlying queue with items?
private Queue<T> TopQueue()
{
  if (_queueHigh.Count > 0)   // Anything in high-priority queue?
    return _queueHigh;
  if (_queueMedium.Count > 0) // Anything in medium-priority queue?
    return _queueMedium;
  if (_queueLow.Count > 0)    // Anything in low-priority queue?
    return _queueLow;
  return _queueLow;           // All empty, so return an empty queue.
}

PriorityQueue is useful when it knows whether it's empty and, if not, how many items it contains. (An object should be responsible for itself.) Look at PriorityQueue's IsEmpty() method and Count property in the earlier listing. You might also find it useful to include methods that return the number of items in each of the underlying queues. Be careful: Doing so may reveal too much about how the priority queue is implemented. Keep your implementation private.

To generate a randomly prioritized Package object, you call your factory object's CreatePackage() method this way:

PackageFactory fact = new PackageFactory();
IPrioritizable pack = fact.CreatePackage(); // Note the interface here.

CreatePackage() tells its random-number generator to generate a number from 0 to 2 (inclusive) and uses the number to set the priority of a new Package, which the method returns (to a Package or, better, to an IPrioritizable variable).

Programmers have long known that they should avoid tight coupling. (One of the more decoupled approaches is to use the factory indirectly via an interface, such as IPrioritizable, rather than a concrete class, such as Package.) Programmers still create objects directly all the time, using the new operator, and that's fine. But factories can make code less coupled — and therefore more flexible.

PriorityQueue must be able to ask an object what its priority is. To make it work, all classes that are storable in PriorityQueue must implement the IPrioritizable interface, as Package does. Package lists IPrioritizable in its class declaration heading, like this:

class Package : IPrioritizable

Then it implements IPrioritizable's Priority property.

class PriorityQueue<T> where T: IPrioritizable

Did you notice the where clause earlier? This boldfaced where clause specifies that T must implement IPrioritizable. That's the enforcer. It means, "Make sure that T implements the IPrioritizable interface — or else!"

For information about these constraints, look up Generics [C#], constraints in the Help index.

Note the struct and class options in particular. Specifying struct means that T can be any value type: a numeric type, a char, a bool, or any object declared with the struct keyword. Specifying class means that T can be any reference type: any class type.

These constraint options give you quite a bit of flexibility for making your new generic class behave just as you want. And a well-behaved class is a pearl beyond price.

You aren't limited to just one constraint, either. Here's an example of a hypothetical generic class declared with multiple constraints on T:

class MyClass<T> : where T: class, IPrioritizable, new()
{ ... }

In this line, T must be a class, not a value type; it must implement IPrioritizable; and it must contain a constructor without parameters. Strict!

class MyClass<T, U> : where T: IPrioritizable, where U: new()

You see two where clauses, separated by a comma. The first constrains T to any object that implements the IPrioritizable interface. The second constrains U to any object that has a default (parameterless) constructor.

In case you read the last paragraph in the previous section and are confused, well, each type has (as mentioned earlier) a default value that signifies "nothing" for that type. For ints, doubles, and other types of numbers, it's 0 (or 0.0). For bool, it's false. And, for all reference types, such as Package, it's null. As with all reference types, the default for string is null.

But because a generic class such as PriorityQueue can be instantiated for almost any data type, C# can't predict the proper null value to use in the generic class's code. For example, if you use the Dequeue() method of PriorityQueue, you may face this situation: You call Dequeue() to get a package, but none is available. What do you return to signify "nothing"? Because Package is a class type, it should return null. That signals the caller of Dequeue() that there was nothing to return (and the caller must check for a null return value).

return default(T);  // Return the right null for whatever T is.

This line tells the compiler to look at T and return the right kind of null value for that type. In the case of Package, which as a class is a reference type, the right null to return is, well, null. But, for some other T, it may be different and the compiler can figure out what to use.