event

Documentation

Overview

Package event 高效的本地事件系统，适用于单线程环境，需要使用go:generate功能来生成代码。

Index

• Variables
• func Clean(hooks []Hook)
• func DeclareEventId(eventTab IEventTab, pos int32) int
• func DeclareEventTabId(eventTab IEventTab) int
• func MakeEventId(eventTab IEventTab, pos int32) int
• func MakeEventTabId(eventTab IEventTab) int
• func Unbind(event IEvent, subscriber any)
• func UnsafeEvent(event IEvent) _UnsafeEvent
• type Event
  • func (event *Event) Clean()
  • func (event *Event) Close()
  • func (event *Event) Init(autoRecover bool, reportError chan error, eventRecursion EventRecursion)
  • func (event *Event) Open()
• type EventRecursion
• type Hook
  • func Bind[T any](event IEvent, subscriber T, priority ...int32) Hook
  • func (hook *Hook) IsBound() bool
  • func (hook *Hook) Unbind()
• type IEvent
• type IEventCtrl
• type IEventTab

Variables

var (
	ErrEvent = fmt.Errorf("%w: event", exception.ErrCore) // 事件错误
	ErrArgs  = exception.ErrArgs                          // 参数错误
)

var (
	// EventRecursionLimit 事件递归次数上限，超过此上限会panic
	EventRecursionLimit = int32(128)
)

Functions

func Clean

func Clean(hooks []Hook)

Clean 清理Hooks

func DeclareEventId

func DeclareEventId(eventTab IEventTab, pos int32) int

DeclareEventId 声明事件Id

func DeclareEventTabId

func DeclareEventTabId(eventTab IEventTab) int

DeclareEventTabId 声明事件表Id

func MakeEventId

func MakeEventId(eventTab IEventTab, pos int32) int

MakeEventId 创建事件Id

func MakeEventTabId

func MakeEventTabId(eventTab IEventTab) int

MakeEventTabId 创建事件表Id

func Unbind

func Unbind(event IEvent, subscriber any)

Unbind 解绑定事件与订阅者，比使用事件绑定句柄解绑定性能差，且在同个订阅者多次绑定事件的情况下，只能从最后依次解除，无法指定解除哪一个

func UnsafeEvent

func UnsafeEvent(event IEvent) _UnsafeEvent

Deprecated: UnsafeEvent 访问本地事件内部方法

Types

type Event

type Event struct {
	// contains filtered or unexported fields
}

Event 本地事件

func (*Event) Clean

func (event *Event) Clean()

Clean 清除全部订阅者

func (*Event) Close

func (event *Event) Close()

Close 关闭事件

func (*Event) Init

func (event *Event) Init(autoRecover bool, reportError chan error, eventRecursion EventRecursion)

Init 初始化事件

func (*Event) Open

func (event *Event) Open()

Open 打开事件

type EventRecursion

type EventRecursion int32

EventRecursion 发生事件递归时的处理方式（事件递归：事件发送过程中，在订阅者的逻辑中，再次发送这个事件）

const (
	EventRecursion_Allow    EventRecursion = iota // 允许事件递归，可能会无限递归
	EventRecursion_Disallow                       // 不允许事件递归，递归时会panic
	EventRecursion_Discard                        // 丢弃递归的事件，不会再发送给任何订阅者
	EventRecursion_Truncate                       // 截断递归的事件，不会再发送给当前订阅者，但是会发送给其他订阅者
	EventRecursion_Deepest                        // 深度优先处理递归的事件，会中断当前事件发送过程，并在新的事件发送过程中，不会再次发送给这个订阅者
)

type Hook

type Hook struct {
	// contains filtered or unexported fields
}

Hook 事件绑定句柄，主要用于重新绑定或解除绑定事件，由BindEvent()创建并返回，请勿自己创建

func Bind

func Bind[T any](event IEvent, subscriber T, priority ...int32) Hook

Bind 绑定事件与订阅者，可以设置优先级调整回调先后顺序（升序）

func (*Hook) IsBound

func (hook *Hook) IsBound() bool

IsBound 是否已绑定事件

func (*Hook) Unbind

func (hook *Hook) Unbind()

Unbind 解绑定事件与订阅者

type IEvent

type IEvent interface {
	// contains filtered or unexported methods
}

IEvent 本地事件接口

定义事件：

1.按以下格式编写一个接口，即完成事件的定义：
type Event{事件名} interface {
	On{事件名}({参数列表})
}

2.在定义事件的源码文件（.go）头部添加以下注释，在编译前自动化生成代码：
//go:generate go run git.golaxy.org/core/event/eventcode --decl_file=$GOFILE gen_event --package=$GOPACKAGE

定义事件的选项（添加到定义事件的注释里）：

1.发送事件的辅助代码的可见性
	[EmitExport]：不可见
	[EmitUnExport]：可见

2.是否生成简化绑定事件的辅助代码
	[EmitAuto]：生成
	[EmitManual]：不生成

使用事件：

1.事件一般作为组件的成员，在组件Awake时初始化，组件Dispose时关闭，示例如下：
type Comp struct {
	ec.ComponentBehavior
	event{事件名} event.Event
}
func (c *Comp) Awake() {
	runtime.Current(c).ActivateEvent(&c.event{事件名}, event.EventRecursion_Discard)
}
func (c *Comp) Dispose() {
	c.event{事件名}.Close()
}

订阅事件：

1.在组件的成员函数，编写以下代码：
func (c *Comp) On{事件名}({参数列表}) {
	...
}

2.在需要订阅事件时，编写以下代码：
func (c *Comp) MethodXXX() {
	{事件定义包名}.Bind{事件名}({发布者}, c)
}

3.如果订阅者生命周期小于发布者，那么需要记录hook并且在Dispose时解除绑定，示例如下：
type Comp struct {
	ec.ComponentBehavior
	hook event.Hook
}
func (c *Comp) MethodXXX() {
	c.hook = {事件定义包名}.Bind{事件名}({发布者}, c)
}
func (c *Comp) Dispose() {
	c.hook.Unbind()
}

4.如果不想写代码记录hook，可以使用ComponentBehavior的AutoHooks()来记录hook，在组件销毁时会自动解除绑定

type IEventCtrl

type IEventCtrl interface {
	// Init 初始化事件
	Init(autoRecover bool, reportError chan error, recursion EventRecursion)
	// Open 打开事件
	Open()
	// Close 关闭事件
	Close()
	// Clean 清除全部订阅者
	Clean()
}

IEventCtrl 事件控制接口

type IEventTab

type IEventTab interface {
	IEventCtrl
	// Get 获取事件
	Get(id int) IEvent
}

IEventTab 本地事件表接口，方便管理多个事件

使用方式：

1.在定义事件的源码文件（.go）头部添加以下注释，在编译前自动化生成代码：
//go:generate go run git.golaxy.org/core/event/eventcode --decl_file=$GOFILE gen_eventtab --package=$GOPACKAGE --name={事件表名称}

定义事件的选项（添加到定义事件的注释里）：

1.事件表初始化时，该事件使用的递归处理方式，不填表示使用事件表初始化参数值
	[EventRecursion_Allow]
	[EventRecursion_Disallow]
	[EventRecursion_Discard]
	[EventRecursion_Truncate]
	[EventRecursion_Deepest]