Calendar queue

A calendar queue (CQ) is a priority queue (queue in which every element has associated priority and the dequeue operation removes the highest priority element). It is analogous to desk calendar, which is used by humans for ordering future events by date. Discrete event simulations require a future event list (FEL) structure that sorts pending events according to their time. Such simulators require a good and efficient data structure as time spent on queue management can be significant. The calendar queue (with optimum bucket size) can approach O(1) average performance. Calendar queues are closely related to bucket queues but differ from them in how they are searched and in being dynamically resized.

Implementation
Theoretically, like a bucket queue, a calendar queue consists of an array of linked lists. Sometimes each index in the array is also referred to as a bucket. The bucket has specified width and its linked list holds events whose timestamp maps to that bucket. A desk calendar has 365 buckets for each day with a width of one day. Each array element contains one pointer that is the head of the corresponding linked list. If the array name is "month" then month[11] is a pointer to the list of events scheduled for the 12th month of the year (the vector index starts from 0). The complete calendar thus consists of an array of 12 pointers and a collection of up to 12 linked lists. In calendar queue, enqueue (addition in a queue) and dequeue (deleting from a queue) of events in FEL is based on event time.

Let the calendar queue with n buckets with w width. Then enqueue of an event with time t operates on bucket $$\frac{t}{w} \mod n$$. And more than two events scheduled in the bucket according to the increased timestamp. To dequeue events from the calendar queue, it keeps track of current year and day. Then it searches for the earliest event within that bucket and dequeue it. (In contrast, a bucket queue would merely return any element from the first nonempty bucket, without determining which element in that bucket is earliest.)

Calendar queue resize operation
If the number of events in the queue is much smaller or much larger than the number of buckets, it will not function efficiently. The solution is to allow the number of buckets to correspondingly grow and shrink as the queue grows and shrinks. To simplify the resize operation, the Nb (number of buckets) in a CQ is often chosen to be the power of two, i.e., $$Nb=2^n$$;↵

The number of buckets is doubled or halved each time the Ne (number of events) exceeds 2Nb or decreases below Nb/2 respectively. When Nb is resized, the new width w has to be calculated as well. The new w that is adopted will be estimated by sampling the average inter-event time gap from the first few hundred events starting at the current bucket position. Thereafter, a new Calendar queue is created and all the events in the old calendar will be recopied over.