Erlang OTP gen_event
转自：http://www.myexception.cn/program/1569725.html
Erlang OTP gen_event (0)
原英文文档：http://www.erlang.org/erldoc?q=&x=0&y=0
Tips:看到网页右边的搜索功能了么，保存这个实用网页吧。
一个实现事件处理功能行为模块，可以动态的删除和增加任意数量事件的事件管理器（event_manager），事件管理器使用这个模块将实现一套标准的接口功能,包括跟踪和错误报告功能。同样他也适合OTP 监控树(supervision tree)
每个事件处理程序被实现为一个回调模块导出一组预定义的功能:
每一个事件处理程序都是一个回调模块，一个事件管理器必可以动态的增加和删除事件回调，所以gen_event 会比其它behaviours（gen_server,gen_fsm)容错更新好，如果安装好的事件处理回调失败(fails with Reason or returns a bad value Term),这个事件管理器是不会失败的，他会删除这个事件回调，并调用对应事件的terminate/2.如果给的参数如：{error, {'EXIT',Reasion}} or {error,Term},其它事件是不会受到影响的。
事件管理不会自动处理（trap）exit signals,%%手动调用 process_flag(trap_exit, true).
如果事件管理器回调返回值里面hibernation有可以进入休眠状态(hibernation)，这对于长期处于空闲状态的server来说非常好， 不过此特性会使用2个垃圾回收器（when hibernating and shortly after waking up）,不适合处理非常多的事件管理器。只要其中一个事件处理返回hibernate就会使event manager进入休眠状态。
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
start_link() -> Result
start_link(EventMgrName) -> Result
Types:EventMgrName = {local,Name} | {global,GlobalName} | {via,Module,ViaName}
Name = atom()
GlobalName = ViaName = term()
Result = {ok,Pid} | {error,{already_started,Pid}}
Pid = pid()
创建一个事件管理器进程（event_manager）这个函数会被supervisor调用创建，保证event_manager与supervisor相连接(link)，
如果EventMrName=｛local,Name},event manager 会像用register/2注册一样本地注册。
如果EventMrName=｛global,GlobalName},event manager 会像用global:register_name/2注册一样本地注册。
如果不提供Name就不会注册。
如果EventMrName = {via,Module,ViaName} event manager会使用Module里面自己定义的register_name/2,unregister_name/1,whereis_name/1 and send/2,这些函数的功能和global里面功能一致，否则{via,Module,ViaName}无用
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
start() -> Result
start(EventMgrName) -> Result
Types:
EventMgrName = {local,Name} | {global,GlobalName} | {via,Module,ViaName}
Name = atom()
GlobalName = ViaName = term()
Result = {ok,Pid} | {error,{already_started,Pid}}
Pid = pid()
创建一个独立的event manager 进程,例如没有监控树，其它参见start_link/0
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
a
add_handler(EventMgrRef, Handler, Args) -> Result
Types:
EventMgr = Name | {Name,Node} | {global,GlobalName} | {via,Module,ViaName} | pid()
Name = Node = atom()
GlobalName = ViaName = term()
Handler = Module | {Module,Id}
Module = atom()
Id = term()
Args = term()
Result = ok | {'EXIT',Reason} | term()
Reason = term()
给event manager 增加一个新的事件回调(event handler),会调用Module:init/1来初始化他的状态
EventMgr 参数可以：pid(),Name,{Name,Node}（如果这个事件管理注册在其它节点上）{global,GlobalName}｛via,Module,ViaName}
Args 参数是传给Module:init/1使用的
如果Module:init/1返回一个正确的值，event manager会增加event handler，此函数也会返回ok.
如果Module:init/1带Reason的失败或返回｛error,Reasion｝ 这具event hander会被忽略，此函数会返回{'EXIT',Reason}或{error,Reason}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
add_sup_handler(EventMgrRef, Handler, Args) -> Result
Types:
EventMgr = Name | {Name,Node} | {global,GlobalName} | {via,Module,ViaName} | pid()
Name = Node = atom()
GlobalName = ViaName = term()
Handler = Module | {Module,Id}
Module = atom()
Id = term()
Args = term()
Result = ok | {'EXIT',Reason} | term()
Reason = term()
和add_handler/3一样添加一个event handler，但会在event handler 和被调用的进程之间添加监控连接(supervise ther connection),
如果这个进程terminateswith Reason event manager 会用Module:terminate/2 {stop,Reason} 把这个event handler 删除
如果event handler 被删除，event manager 会发{gen_event_EXIT,Handler,Reason}给进程（the calling process）：这时的Reason会有以下：
- 1）normal ----使用delete_handler/3或remove_handler
- 2）shutdown ---event_manager 终结了：is terminating
- 3){swapped,NewHandler,Pid} 如果使用swap_handler/3或swap_sup_handler/3替换原event handler
- 4)一个term如果由于一个错误被移除
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
notify(EventMgrRef, Event) -> ok
sync_notify(EventMgrRef, Event) -> ok
Types:
EventMgrRef = Name | {Name,Node} | {global,GlobalName} | {via,Module,ViaName} | pid()
Name = Node = atom()
GlobalName = ViaName = term()
Event = term()
向已增加在event manager里面所有的event handler都发一个Event(MSG).event manager会调用所有的event handler的Module:handler_event/2.
notify 是异步的:在消息发出后立即返回，sync_notify同步的，会在所有的event_handler处理完消息后返回ok.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
call(EventMgrRef, Handler, Request) -> Result
call(EventMgrRef, Handler, Request, Timeout) -> Result
Types:
EventMgrRef = Name | {Name,Node} | {global,GlobalName} | {via,Module,ViaName} | pid()
Name = Node = atom()
GlobalName = ViaName = term()
Handler = Module | {Module,Id}
Module = atom()
Id = term()
Request = term()
Timeout = int()>0 | infinity
Result = Reply | {error,Error}
Reply = term()
Error = bad_module | {'EXIT',Reason} | term()
Reason = term()
一个同步call（和gen_server:call差不多）不过会指定对应的Hander来处理Request.Handler内使用handler_call/2来处理Request.
TimeOut 是一个比0大的毫秒级或infinity.默认值为50000ms.如果规定时间内没有返回，就会call fails.
Repeal会返回Module:handle_call/2返回，如果 event handler没有安装，会返回{error,bad_module}.callback会分别返回Reason Term ，这个函数就会返回{error,{'EXIT',Reason},{error,Term}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
delete_handler(EventMgrRef, Handler, Args) -> Result
Types:
EventMgrRef = Name | {Name,Node} | {global,GlobalName} | {via,Module,ViaName} | pid()
Name = Node = atom()
GlobalName = ViaName = term()
Handler = Module | {Module,Id}
Module = atom()
Id = term()
Args = term()
Result = term() | {error,module_not_found} | {'EXIT',Reason}
Reason = term()
删除event manager(EvenMgrRef）里面对应的Handler,调用Handler：terminate(Args,State).来终结这个事件.
Result：返回Handler：terminate(Args,State)的返回值，如果没有找到安装的事件返回{error,module_not_found}.
如果失败了就会回调返回Reason.此函数返回：{'EXIT',Reason}.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
swap_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) -> Result
Types:
EventMgrRef = Name | {Name,Node} | {global,GlobalName} | {via,Module,ViaName} | pid()
Name = Node = atom()
GlobalName = ViaName = term()
Handler1 = Handler2 = Module | {Module,Id}
Module = atom()
Id = term()
Args1 = Args2 = term()
Result = ok | {error,Error}
Error = {'EXIT',Reason} | term()
Reason = term()
在event manager (EventMgrRef)用Handler1代替Handler2
- 1）删除Handler1-----与调用delete_handler一致：
- 2）增加Handler2-----与调用add_handler一致：【init里面调用{Args2,Term}：Term是Handler1:terminate里面返回的】
- 3）这2个操作没有原子性，1，2的成功没有关系的。
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
swap_sup_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) -> Result
Types:
EventMgrRef = Name | {Name,Node} | {global,GlobalName} | {via,Module,ViaName} | pid()
Name = Node = atom()
GlobalName = ViaName = term()
Handler1 = Handler 2 = Module | {Module,Id}
Module = atom()
Id = term()
Args1 = Args2 = term()
Result = ok | {error,Error}
Error = {'EXIT',Reason} | term()
Reason = term()
与swap_handler/3一致，但是会Handler2和the calling process里面建立连接.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
which_handlers(EventMgrRef) -> [Handler]
Types:
EventMgrRef = Name | {Name,Node} | {global,GlobalName} | {via,Module,ViaName} | pid()
Name = Node = atom()
GlobalName = ViaName = term()
Handler = Module | {Module,Id}
Module = atom()
Id = term()
返回event manager的事件Event handler列表
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
stop(EventMgrRef) -> ok
Types:
EventMgrRef = Name | {Name,Node} | {global,GlobalName} | {via,Module,ViaName} | pid()
Name = Node = atom()
GlobalName = ViaName = term()
terminates the event manager 在此之前会对安装好的事件调用Module:terminate(stop,...).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
event handler里面的callback函数
Module:init(InitArgs) -> {ok,State} | {ok,State,hibernate} | {error,Reason}
Types:
InitArgs = Args | {Args,Term}
Args = Term = term()
State = term()
Reason = term()
当一个新的event handler被加入event manager时，这个函数会被调用.
调用gen_event:add_sup_handler/3，swap_handler/3 swap_sup_handler
返回{ok,State,hibernate}时event manager会进入休眠状态：等待下次事件发生
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Module:handle_event(Event, State) -> Result
Types:
Event = term()
State = term()
Result = {ok,NewState} | {ok,NewState,hibernate} | {swap_handler,Args1,NewState,Handler2,Args2} | remove_handler
NewState = term()
Args1 = Args2 = term()
Handler2 = Module2 | {Module2,Id}
Module2 = atom()
Id = term
当event manager收到用notify/2或sync_notify/2发送的消息时会调用：所有安装过的事件的Handler:handler_event/2
返回{swap_handler,Args1,NewState,Handler2,Args2}时会调用Term = Module:terminate(Args1,NewState),Module2:init(Args2,Term) 【基本和swap_handler/3相同】
返回remove_handler 时会调用Module:terminate(remove_handler,State).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Module:handle_call(Request, State) -> Result
Types:
Request = term()
State = term()
Result = {ok,Reply,NewState} | {ok,Reply,NewState,hibernate}| {swap_handler,Reply,Args1,NewState,Handler2,Args2}| {remove_handler, Reply}
Reply = term()
NewState = term()
Args1 = Args2 = term()
Handler2 = Module2 | {Module2,Id}
Module2 = atom()
Id = term()
使用gen_event:call/3发出的信息，与handle_event类似，不过是同步的。
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Module:handle_info(Info, State) -> Result
Types:
Info = term()
State = term()
Result = {ok,NewState} | {ok,NewState,hibernate}
| {swap_handler,Args1,NewState,Handler2,Args2} | remove_handler
NewState = term()
Args1 = Args2 = term()
Handler2 = Module2 | {Module2,Id}
Module2 = atom()
Id = term()
收到除用gen_event:call/3,gen_event:notify/3,gen_event:sync_notify/3之外的任何消息。
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Module:terminate(Arg, State) -> term()
Types:
Arg = Args | {stop,Reason} | stop | remove_handler
| {error,{'EXIT',Reason}} | {error,Term}
Args = Reason = Term = term()
在要完成删除，清理工作时会调用。
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Module:code_change(OldVsn, State, Extra) -> {ok, NewState}
Types:
OldVsn = Vsn | {down, Vsn}
Vsn = term()
State = NewState = term()
Extra = term()