Skip to content

Latest commit

 

History

History
423 lines (299 loc) · 12.9 KB

policies.md

File metadata and controls

423 lines (299 loc) · 12.9 KB
Raw

策略（Policies）

目录

介绍

eventpp 使用了基于策略的设计来配置和扩展各个组件的行为。EventDispatcher、EventQueue、CallbackList 的最后一个模板参数就是策略类。这三个类都有名为 DefaultPolicies 的默认策略类。

一项策略可以是策略类中的一个类型或一个静态成员函数。所有策略都必须是 public 的，所以通常可以用 struct 来定义策略类。

所有策略都是可选的。若省略了一个策略，那么这项策略就将使用其默认值。实际上，DefaultPolicies 本身就是一个空结构体。

EventDispatcher、EventQueue、CallbackList 这三个类使用了相同的策略机制，尽管不是所有的类都需要相同的策略。

策略

函数： getEvent

原型：static EventKey getEvent(const Args &...) 。该函数接收与 EventDispatcher::dispatch 和 EventQueue::enqueue 相同的参数，且必须返回一个事件类型。

默认值：默认实现是返回 getEvent 的第一个实参。

适用于：EventDispatcher, EventQueue

evetpp 将 EventDispatcher::dispatch 和 EventQueue::enqueue 的所有实参（这两个函数的参数相同）都转发给 getEvent 以获取事件类型，然后再触发执行该事件对应的回调函数列表。

getEvnet 既可以是模板函数，也可以是非模板函数。只要 getEvent 能够使用与 EventDispatcher::dispatch 和 EventQueue::enqueue 相同的参数调用即可。

示例代码如下：

// 定义用于保存所有参数的事件结构
struct MyEvent {
    int type;
    std::string message;
    int param;
};

// 为调度器定义如何分解事件类型的策略
struct MyEventPolicies
{
    static int getEvent(const MyEvent & e, bool /*b*/) {
        return e.type;
    }
};

// 将 MyEventPolicies 作为 EventDispatcher 的第三个模板参数
// 注意：第一个模板参数是整型的事件类型，而非 MyEvent。
eventpp::EventDispatcher<
    int,
    void (const MyEvent &, bool),
    MyEventPolicies
> dispatcher;

// 添加一个监听器。
// 注意：第一个参数是整型的事件类型，而非 MyEvent。
dispatcher.appendListener(3, [](const MyEvent & e, bool b) {
    std::cout
        << std::boolalpha
        << "Got event 3" << std::endl
        << "Event::type is " << e.type << std::endl
        << "Event::message is " << e.message << std::endl
        << "Event::param is " << e.param << std::endl
        << "b is " << b << std::endl
    ;
});

// 调度事件。第一个参数是 Event
dispatcher.dispatch(MyEvent { 3, "Hello world", 38 }, true);

函数： canContinueInvoking

原型：static bool canContinueInvoking(const Args &...) 。该函数接收与 EventDispatcher::dispatch 和 EventQueue::enqueue 相同的参数，且必须在事件调度或回调列表调用可以继续进行的时候返回 true ，在调用需要停止的时候返回 false 。

默认值：默认实现总是返回 true 。

适用于：CallbackList, EventDispatcher, EventQueue

示例代码如下：

struct MyEvent {
    MyEvent() : type(0), canceled(false) {
    }
    explicit MyEvent(const int type)
        : type(type), canceled(false) {
    }

    int type;
    mutable bool canceled;
};

struct MyEventPolicies
{
    static int getEvent(const MyEvent & e) {
        return e.type;
    }

    static bool canContinueInvoking(const MyEvent & e) {
        return ! e.canceled;
    }
};

eventpp::EventDispatcher<int, void (const MyEvent &), MyEventPolicies> dispatcher;

dispatcher.appendListener(3, [](const MyEvent & e) {
    std::cout << "Got event 3" << std::endl;
    e.canceled = true;
});
dispatcher.appendListener(3, [](const MyEvent & e) {
    std::cout << "Should not get this event 3" << std::endl;
});

dispatcher.dispatch(MyEvent(3));

类型： Mixins

默认值：using Mixins = eventpp::MixinList<> 。未启用任何 mixin 。

适用于：CallbackList, EventDispatcher, EventQueue

Mixin 用于向 EventDispatcher / EventQueue 继承层次中注入代码，以扩展它们的功能。更多细节请参阅 https://github.com/wqking/eventpp/blob/master/doc/mixins.md

类型： Callback

默认值：using Callback = std::function<Parameters of callback> 。

适用于：CallbackList, EventDispatcher, EventQueue

Callback 是用于在底层维护回调函数。默认是 std::function

类型： Threading

默认值：using Threading = eventpp::MultipleThreading 。

适用于：CallbackList, EventDispatcher, EventQueue, HeterCallbackList, HeterEventDispatcher, HeterEventQueue.

Threading 控制线程执行模型。默认是“多线程”（ Multiple Threading ）。可取值：

  • MultipleThreading ： 使用 mutex 保护核心数据。该选项为默认值。
  • SingleThreading ： 不保护核心数据，且这些数据无法从其他线程访问

一个典型的 Threading 类型如下：

struct MultipleThreading
{
    using Mutex = std::mutex;
    
    template <typename T>
    using Atomic = std::atomic<T>;
    
    using ConditionVariable = std::condition_variable;
};

对于 SingleThreading 而言，所有的 Mutex 、 Atomic 和 ConditionVariable 类型都是不会起任何作用的假类型。

对于多线程而言，默认的 Mutex 是 std::mutex 。 eventpp 也提供了一个使用自旋锁作为互斥量的 SpinLock 类。

当只有较少的线程时（和 CPU 核心数差不多的线程数），eventpp::SpinLock 的性能比 std::mutex 更高一些。当线程数超过 CPU 核心数时， eventpp::SpinLock 的性能弱于 std::mutex 。

基准测试相关数据请参阅：https://github.com/wqking/eventpp/blob/master/doc/benchmark.md

下面是使用 SpinLock 的示例代码：

struct MultipleThreadingSpinLock
{
	using Mutex = eventpp::SpinLock;
    
    template <typename T>
    using Atomic = std::atomic<T>;
    
    using ConditionVariable = std::condition_variable;
};
struct MyEventPolicies {
    using Threading = MultipleThreadingSpinLock;
};
eventpp::EventDispatcher<int, void (), MyEventPolicies> dispatcher;
eventpp::CallbackList<void (), MyEventPolicies> callbackList;

eventpp 还提供了一个简化易用的自定义线程管理的模板类。

template <
	typename Mutex_,
	template <typename > class Atomic_ = sd::atomic,
    typename ConditionVariable_ = std::condition_variable
>
struct GeneralThreading
{
    using Mutex = Mutex_;
    
    template <typename T>
    using Atomic = Atomic_<T>;
    
    using ConditionVariable = ConditionVariable_;
};

因此前面自旋锁的示例代码可以重写为

struct MyEventPolicies {
    using Threading = eventpp::GeneralThreading<eventpp::SpinLock>;
};
eventpp::EventDispatcher<int, void (), MyEventPolicies> dispatcher;
eventpp::CallbackList<void (), MyEventPolicies> callbackList;

类型： ArgumentPassingMode

默认值：using ArgumentPassingMode = ArgumentPassingAutoDetect 。

适用于：EventDispatcher, EventQueue

ArgumentPassingMode 是实参传递的模式。默认值是 ArgumentPassingAutoDetect 。

示例代码如下。假设我们有一个调度器

eventpp::EventDispatcher<int, void(int, const std::string &)> dispatcher;

事件类型是 int 。

监听器的第一个参数也是 int 。根据具体的事件调度方式，监听器的第一个参数可以是事件类型，也可以是一个额外的参数。

dispatcher.dispatch(3, "hello");

事件 3 会被使用一个参数 "hello" 调度，监听器将会被使用参数 (3, "hello") 触发执行，第一个参数是事件类型。

dispatcher.dispatch(3, 8, "hello");

事件 3 会被使用两个参数 8 和 "hello" 调度，监听器将会被使用参数 (8, "hello") 触发执行，第一个参数就是额外参数，此时的事件类型参数将被忽略。

因此，在默认情况下，EventDispatcher 会自动监测 dispatch 的参数数量和监听器原型，以决定是否使用事件类型来调用监听器。

默认规则简便、宽松但容易出错。可以通过 ArgumentPassingMode 策略控制具体的行为

struct ArgumentPassingAutoDetect;
struct ArgumentPassingIncludeEvent;
struct ArgumentPassingExcludeEvent;

ArgumentPassingAutoDetect：默认策略。自动检查是否要传递事件类型。

ArgumentPassingIncludeEvent：总是传递事件类型。参数数量不符会导致编译失败。

ArgumentPassingExcludeEvent：总是忽略且不会传递事件类型。参数数量不符会导致编译失败。

假设监听器原型有 P 个参数，dispatch 中的参数数量（包括事件类型在内）为 D ，则 P 和 D 的关系为：

对于 ArgumentPassingAutoDetect：P == D 或 P + 1 == D

对于 ArgumentPassingIncludeEvent：P == D

对于 ArgumentPassingExcludeEvent： P + 1 == D

注意：同样的规则也适用于 EventQueue::enqueue ，因为 enqueue 的参数与 dispatch 相同。

参数传递模式的示例代码如下：

struct MyPolicies
{
    using ArgumentPassingMode = ArgumentPassingAutoDetect;
};
eventpp::EventDispatcher<
    int,
    void(int, const std::string &),
    MyPolicies
> dispatcher;
// 或用下面的简便写法
//eventpp::EventDispatcher<int, void(int, const std::string &)> dispatcher;
dispatcher.dispatch(3, "hello"); // 编译通过
dispatcher.dispatch(3, 8, "hello"); // 编译通过
struct MyPolicies
{
    using ArgumentPassingMode = ArgumentPassingIncludeEvent;
};
eventpp::EventDispatcher<
    int,
    void(int, const std::string &),
    MyPolicies
> dispatcher;
dispatcher.dispatch(3, "hello"); // 编译通过
//dispatcher.dispatch(3, 8, "hello"); // 编译失败
struct MyPolicies
{
    using ArgumentPassingMode = ArgumentPassingExcludeEvent;
};
eventpp::EventDispatcher<
    int,
    void(int, const std::string &),
    MyPolicies
> dispatcher;
//dispatcher.dispatch(3, "hello"); // 编译失败
dispatcher.dispatch(3, 8, "hello"); // 编译通过

模板： Map

原型：

template <typename Key, typename T>
using Map = // std::map <Key, T> 或其他 map 类型

默认值：自动确定

应用于：EventDispatcher, EventQueue

Map 是 EventDispatcher 和 EventQueue 用于维护底层键值对（事件类型，CallbackList）的关联容器类型。

Map 是有两个参数的模板，两个参数分别是键和值。

Map 必须能够支持 []、find()、end() 操作。

若没有指定 Map ，eventpp 会自动确定类型。若事件类型支持 std::hash 会使用 std::unordered_map ，否则会使用 std::map

模板： QueueList

原型：

template <typename Item>
using QueueList = std::list<Item>;

默认值：std::list

应用于：EventQueue

QueueList 用于管理 EventQueue 内部的事件，作为队列使用。事件会被追加到 QueueList 的末尾，当被处理时，事件会从 QueueList 的头部弹出。

使用不同的 QueueList 能够更好地控制队列。例如，若 QueueList 能够管理事件的顺序，那么队列中的事件就能以不同于加入顺序的新顺序被处理。

一个 QueueList 不需要实现 std::list 的所有成员，其只需要实现下面的类型和函数即可：

type iterator;
type const_iterator;
bool empty() const;
iterator begin();
const_iterator begin() const;
iterator end();
const_iterator end() const;
const_reference front() const;
void swap(QueueList & other);
void emplace_back();
void splice(const_iterator pos, QueueList & other );
void splice(const_iterator pos, QueueList & other, const_iterator it);

eventpp 中的有序队列列表 OrderedQueueList 就是一个应用实例。详细内容请阅 https://github.com/wqking/eventpp/blob/master/doc/orderedqueuelist.md

如何使用策略

想要使用策略，只需要声明一个结构体，在其中定义策略然后传递给 CallbackList, EventDispatcher 或 EventQueue 即可。

struct MyPolicies // 结构体的名字并不重要
{
    template <typename ...Args>
    static int getEvent(const MyEvent & e, const Args &...) {
        return e.type;
    }
};
EventDispatcher<int, void(const MyEvent &), MyPolicies> dispatcher;

上面的示例代码展示了一个重定义了 getEvent 策略类，除该策略外的其他策略都保持默认值。