eventpp/doc/orderedqueuelist.md

# Class OrderedQueueList reference

<!--begintoc-->
## Table Of Contents

* [Description](#a2_1)
* [API reference](#a2_2)
  * [Header](#a3_1)
  * [Template parameters](#a3_2)
  * [Sample code](#a3_3)
<!--endtoc-->

<a id="a2_1"></a>
## Description

`OrderedQueueList` is a utility class that sorts the events in an EventQueue in certain order.  
With `OrderedQueueList`, we can dispatch events in certain order such as in priority order.  
This class is used with the `QueueList` policy. See [document of policies](policies.md) for details and how to implement new `QueueList`.  

Warning: `OrderedQueueList` is not efficient since it simply inherits from `std::list` and sorts the full list on each `splice`.
To use it in performance critical applications, you should implement your own version with sophisticated algorithm.

<a id="a2_2"></a>
## API reference

<a id="a3_1"></a>
### Header

eventpp/utilities/orderedqueuelist.h

<a id="a3_2"></a>
### Template parameters

```c++
template <typename Item, typename Compare = OrderedQueueListCompare>
class OrderedQueueList;
```

`Item` is used by the policies.  
`Compare` is the comparison function object.  
Its default implementation `OrderedQueueListCompare` looks like,  

```c++
struct OrderedQueueListCompare
{
	template <typename T>
	bool operator() (const T & a, const T & b) const {
		return a.event < b.event;
	}
};
```
The typename T is actually the `EventQueue::QueuedEvent`. But since `OrderedQueueList` is used in the policies that are used to construct the EventQueue, it's not possible to specify the actual type in `OrderedQueueListCompare`, so here we use a template operator.  

`EventQueue::QueuedEvent` is declared as,  

```c++
struct QueuedEvent
{
	EventType event;
	std::tuple<Args> arguments;
};
```
`event` is the event sent to the queue.  
`arguments` are the arguments that passed to `EventQueue::enqueue`.  

<a id="a3_3"></a>
### Sample code

```c++
// First let's define the event struct. e is the event type, priority determines the priority.
struct MyEvent
{
	int e;
	int priority;
};

// The comparison function object used by eventpp::OrderedQueueList.
// The function compares the event by priority.
struct MyCompare
{
	template <typename T>
	bool operator() (const T & a, const T & b) const {
		return std::get<0>(a.arguments).priority > std::get<0>(b.arguments).priority;
	}
};

// Define the EventQueue policy
struct MyPolicy
{
	template <typename Item>
	using QueueList = eventpp::OrderedQueueList<Item, MyCompare >;

	static int getEvent(const MyEvent & event) {
		return event.e;
	}
};

void main()
{
	using EQ = eventpp::EventQueue<int, void(const MyEvent &), MyPolicy>;
	EQ queue;

	queue.appendListener(3, [](const MyEvent & event) {
		std::cout << "Get event " << event.e << "(should be 3)." << " priority: " << event.priority << std::endl;
	});
	queue.appendListener(5, [](const MyEvent & event) {
		std::cout << "Get event " << event.e << "(should be 5)." << " priority: " << event.priority << std::endl;
	});
	queue.appendListener(7, [](const MyEvent & event) {
		std::cout << "Get event " << event.e << "(should be 7)." << " priority: " << event.priority << std::endl;
	});

	// Add an event, the first number 5 is the event type, the second number 100 is the priority.
	// After the queue processes, the events will be processed from higher priority to lower priority.
	queue.enqueue(MyEvent{ 5, 100 });
	queue.enqueue(MyEvent{ 5, 200 });
	queue.enqueue(MyEvent{ 7, 300 });
	queue.enqueue(MyEvent{ 7, 400 });
	queue.enqueue(MyEvent{ 3, 500 });
	queue.enqueue(MyEvent{ 3, 600 });

	queue.process();
}

```