queue: Introducing a general purpose priority queue.

This commit introduces PriorityQueue, which is a general, heap
based priority queue, and PriorityQueueItem which is an interface
that concrete priority queue items must implement.
This implementation is encapsulated, users do not need to use any
other package for full functionality.
PriorityQueue exports the usual public methids: Push, Pop, Top,
Empty and Len. For full documentaton consult the priority_queue.go,
for usage: priority_queue_test.go

queue/priority_queue_test.go

@@ -0,0 +1,67 @@
+package queue
+
+import (
+	"math/rand"
+	"testing"
+	"time"
+)
+
+type testQueueItem struct {
+	Value  int
+	Expiry time.Time
+}
+
+func (e testQueueItem) Less(other PriorityQueueItem) bool {
+	return e.Expiry.Before(other.(*testQueueItem).Expiry)
+}
+
+func TestExpiryQueue(t *testing.T) {
+	// The number of elements we push to the queue.
+	count := 100
+	// Generate a random permutation of a range [0, count)
+	array := rand.Perm(count)
+	// t0 holds a reference time point.
+	t0 := time.Date(1975, time.April, 5, 12, 0, 0, 0, time.UTC)
+
+	var testQueue PriorityQueue
+
+	if testQueue.Len() != 0 && !testQueue.Empty() {
+		t.Fatal("Expected the queue to be empty")
+	}
+
+	// Create elements with expiry of t0 + value * second.
+	for _, value := range array {
+		testQueue.Push(&testQueueItem{
+			Value:  value,
+			Expiry: t0.Add(time.Duration(value) * time.Second),
+		})
+	}
+
+	// Now expect that we can retrieve elements in order of their expiry.
+	for i := 0; i < count; i++ {
+		expectedQueueLen := count - i
+		if testQueue.Len() != expectedQueueLen {
+			t.Fatalf("Expected the queue len %v, got %v",
+				expectedQueueLen, testQueue.Len())
+		}
+
+		if testQueue.Empty() {
+			t.Fatalf("Did not expect the queue to be empty")
+		}
+
+		top := testQueue.Top().(*testQueueItem)
+		if top.Value != i {
+			t.Fatalf("Expected queue top %v, got %v", i, top.Value)
+		}
+
+		popped := testQueue.Pop().(*testQueueItem)
+		if popped != top {
+			t.Fatalf("Expected queue top %v equal to popped: %v",
+				top, popped)
+		}
+	}
+
+	if testQueue.Len() != 0 || !testQueue.Empty() {
+		t.Fatalf("Expected the queue to be empty")
+	}
+}