Skip to content

Commit

Permalink
Merge branch 'uw/extending_gen' into maint
Browse files Browse the repository at this point in the history 
* uw/extending_gen:
  Add plugin support for alternative name lookup

OTP-9945
  • Loading branch information
Gustav Simonsson committed Feb 24, 2012
2 parents dbb30eb + b042673 commit d9ee75f
Show file tree
Hide file tree
Showing 14 changed files with 436 additions and 72 deletions.
61 changes: 46 additions & 15 deletions lib/stdlib/doc/src/gen_event.xml
View file
Expand Up @@ -120,8 +120,10 @@ gen_event:stop -----> Module:terminate/2
<name>start_link(EventMgrName) -> Result</name>
<fsummary>Create a generic event manager process in a supervision tree.</fsummary>
<type>
<v>EventMgrName = {local,Name} | {global,Name}</v>
<v>EventMgrName = {local,Name} | {global,GlobalName}
| {via,Module,ViaName}</v>
<v>&nbsp;Name = atom()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Result = {ok,Pid} | {error,{already_started,Pid}}</v>
<v>&nbsp;Pid = pid()</v>
</type>
Expand All @@ -132,10 +134,17 @@ gen_event:stop -----> Module:terminate/2
the event manager is linked to the supervisor.</p>
<p>If <c>EventMgrName={local,Name}</c>, the event manager is
registered locally as <c>Name</c> using <c>register/2</c>.
If <c>EventMgrName={global,Name}</c>, the event manager is
registered globally as <c>Name</c> using
If <c>EventMgrName={global,GlobalName}</c>, the event manager is
registered globally as <c>GlobalName</c> using
<c>global:register_name/2</c>. If no name is provided,
the event manager is not registered.</p>
the event manager is not registered.
If <c>EventMgrName={via,Module,ViaName}</c>, the event manager will
register with the registry represented by <c>Module</c>.
The <c>Module</c> callback should export the functions
<c>register_name/2</c>, <c>unregister_name/1</c>,
<c>whereis_name/1</c> and <c>send/2</c>, which should behave like the
corresponding functions in <c>global</c>. Thus,
<c>{via,global,GlobalName}</c> is a valid reference.</p>
<p>If the event manager is successfully created the function
returns <c>{ok,Pid}</c>, where <c>Pid</c> is the pid of
the event manager. If there already exists a process with
Expand All @@ -149,8 +158,10 @@ gen_event:stop -----> Module:terminate/2
<name>start(EventMgrName) -> Result</name>
<fsummary>Create a stand-alone event manager process.</fsummary>
<type>
<v>EventMgrName = {local,Name} | {global,Name}</v>
<v>EventMgrName = {local,Name} | {global,GlobalName}
| {via,Module,ViaName}</v>
<v>&nbsp;Name = atom()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Result = {ok,Pid} | {error,{already_started,Pid}}</v>
<v>&nbsp;Pid = pid()</v>
</type>
Expand All @@ -166,8 +177,10 @@ gen_event:stop -----> Module:terminate/2
<name>add_handler(EventMgrRef, Handler, Args) -> Result</name>
<fsummary>Add an event handler to a generic event manager.</fsummary>
<type>
<v>EventMgr = Name | {Name,Node} | {global,Name} | pid()</v>
<v>EventMgr = Name | {Name,Node} | {global,GlobalName}
| {via,Module,ViaName} | pid()</v>
<v>&nbsp;Name = Node = atom()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Handler = Module | {Module,Id}</v>
<v>&nbsp;Module = atom()</v>
<v>&nbsp;Id = term()</v>
Expand All @@ -185,8 +198,10 @@ gen_event:stop -----> Module:terminate/2
<item><c>Name</c>, if the event manager is locally registered,</item>
<item><c>{Name,Node}</c>, if the event manager is locally
registered at another node, or</item>
<item><c>{global,Name}</c>, if the event manager is globally
<item><c>{global,GlobalName}</c>, if the event manager is globally
registered.</item>
<item><c>{via,Module,ViaName}</c>, if the event manager is registered
through an alternative process registry.</item>
</list>
<p><c>Handler</c> is the name of the callback module <c>Module</c> or
a tuple <c>{Module,Id}</c>, where <c>Id</c> is any term.
Expand All @@ -208,8 +223,10 @@ gen_event:stop -----> Module:terminate/2
<name>add_sup_handler(EventMgrRef, Handler, Args) -> Result</name>
<fsummary>Add a supervised event handler to a generic event manager.</fsummary>
<type>
<v>EventMgr = Name | {Name,Node} | {global,Name} | pid()</v>
<v>EventMgr = Name | {Name,Node} | {global,GlobalName}
| {via,Module,ViaName} | pid()</v>
<v>&nbsp;Name = Node = atom()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Handler = Module | {Module,Id}</v>
<v>&nbsp;Module = atom()</v>
<v>&nbsp;Id = term()</v>
Expand Down Expand Up @@ -253,8 +270,10 @@ gen_event:stop -----> Module:terminate/2
<name>sync_notify(EventMgrRef, Event) -> ok</name>
<fsummary>Notify an event manager about an event.</fsummary>
<type>
<v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v>
<v>EventMgrRef = Name | {Name,Node} | {global,GlobalName}
| {via,Module,ViaName} | pid()</v>
<v>&nbsp;Name = Node = atom()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Event = term()</v>
</type>
<desc>
Expand All @@ -278,8 +297,10 @@ gen_event:stop -----> Module:terminate/2
<name>call(EventMgrRef, Handler, Request, Timeout) -> Result</name>
<fsummary>Make a synchronous call to a generic event manager.</fsummary>
<type>
<v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v>
<v>EventMgrRef = Name | {Name,Node} | {global,GlobalName}
| {via,Module,ViaName} | pid()</v>
<v>&nbsp;Name = Node = atom()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Handler = Module | {Module,Id}</v>
<v>&nbsp;Module = atom()</v>
<v>&nbsp;Id = term()</v>
Expand Down Expand Up @@ -318,8 +339,10 @@ gen_event:stop -----> Module:terminate/2
<name>delete_handler(EventMgrRef, Handler, Args) -> Result</name>
<fsummary>Delete an event handler from a generic event manager.</fsummary>
<type>
<v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v>
<v>EventMgrRef = Name | {Name,Node} | {global,GlobalName}
| {via,Module,ViaName} | pid()</v>
<v>&nbsp;Name = Node = atom()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Handler = Module | {Module,Id}</v>
<v>&nbsp;Module = atom()</v>
<v>&nbsp;Id = term()</v>
Expand All @@ -346,8 +369,10 @@ gen_event:stop -----> Module:terminate/2
<name>swap_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) -> Result</name>
<fsummary>Replace an event handler in a generic event manager.</fsummary>
<type>
<v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v>
<v>EventMgrRef = Name | {Name,Node} | {global,GlobalName}
| {via,Module,ViaName} | pid()</v>
<v>&nbsp;Name = Node = atom()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Handler1 = Handler2 = Module | {Module,Id}</v>
<v>&nbsp;Module = atom()</v>
<v>&nbsp;Id = term()</v>
Expand Down Expand Up @@ -390,8 +415,10 @@ gen_event:stop -----> Module:terminate/2
<name>swap_sup_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) -> Result</name>
<fsummary>Replace an event handler in a generic event manager.</fsummary>
<type>
<v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v>
<v>EventMgrRef = Name | {Name,Node} | {global,GlobalName}
| {via,Module,ViaName} | pid()</v>
<v>&nbsp;Name = Node = atom()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Handler1 = Handler 2 = Module | {Module,Id}</v>
<v>&nbsp;Module = atom()</v>
<v>&nbsp;Id = term()</v>
Expand All @@ -412,8 +439,10 @@ gen_event:stop -----> Module:terminate/2
<name>which_handlers(EventMgrRef) -> [Handler]</name>
<fsummary>Return all event handlers installed in a generic event manager.</fsummary>
<type>
<v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v>
<v>EventMgrRef = Name | {Name,Node} | {global,GlobalName}
| {via,Module,ViaName} | pid()</v>
<v>&nbsp;Name = Node = atom()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Handler = Module | {Module,Id}</v>
<v>&nbsp;Module = atom()</v>
<v>&nbsp;Id = term()</v>
Expand All @@ -429,8 +458,10 @@ gen_event:stop -----> Module:terminate/2
<name>stop(EventMgrRef) -> ok</name>
<fsummary>Terminate a generic event manager.</fsummary>
<type>
<v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v>
<v>EventMgrRef = Name | {Name,Node} | {global,GlobalName}
| {via,Module,ViaName} | pid()</v>
<v>Name = Node = atom()</v>
<v>GlobalName = ViaName = term()</v>
</type>
<desc>
<p>Terminates the event manager <c>EventMgrRef</c>. Before
Expand Down
55 changes: 36 additions & 19 deletions lib/stdlib/doc/src/gen_fsm.xml
View file
Expand Up @@ -84,9 +84,10 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
<name>start_link(FsmName, Module, Args, Options) -> Result</name>
<fsummary>Create a gen_fsm process in a supervision tree.</fsummary>
<type>
<v>FsmName = {local,Name} | {global,GlobalName}</v>
<v>FsmName = {local,Name} | {global,GlobalName}
| {via,Module,ViaName}</v>
<v>&nbsp;Name = atom()</v>
<v>&nbsp;GlobalName = term()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Module = atom()</v>
<v>Args = term()</v>
<v>Options = [Option]</v>
Expand All @@ -113,8 +114,16 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
locally as <c>Name</c> using <c>register/2</c>.
If <c>FsmName={global,GlobalName}</c>, the gen_fsm is
registered globally as <c>GlobalName</c> using
<c>global:register_name/2</c>. If no name is provided,
the gen_fsm is not registered.</p>
<c>global:register_name/2</c>.
If <c>EventMgrName={via,Module,ViaName}</c>, the event manager will
register with the registry represented by <c>Module</c>.
The <c>Module</c> callback should export the functions
<c>register_name/2</c>, <c>unregister_name/1</c>,
<c>whereis_name/1</c> and <c>send/2</c>, which should behave like the
corresponding functions in <c>global</c>. Thus,
<c>{via,global,GlobalName}</c> is a valid reference.</p>
<p>If no name is provided,
the gen_fsm is not registered.</p>
<p><c>Module</c> is the name of the callback module.</p>
<p><c>Args</c> is an arbitrary term which is passed as
the argument to <c>Module:init/1</c>.</p>
Expand Down Expand Up @@ -154,9 +163,10 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
<name>start(FsmName, Module, Args, Options) -> Result</name>
<fsummary>Create a stand-alone gen_fsm process.</fsummary>
<type>
<v>FsmName = {local,Name} | {global,GlobalName}</v>
<v>FsmName = {local,Name} | {global,GlobalName}
| {via,Module,ViaName}</v>
<v>&nbsp;Name = atom()</v>
<v>&nbsp;GlobalName = term()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Module = atom()</v>
<v>Args = term()</v>
<v>Options = [Option]</v>
Expand All @@ -180,9 +190,10 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
<name>send_event(FsmRef, Event) -> ok</name>
<fsummary>Send an event asynchronously to a generic FSM.</fsummary>
<type>
<v>FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()</v>
<v>FsmRef = Name | {Name,Node} | {global,GlobalName}
| {via,Module,ViaName} | pid()</v>
<v>&nbsp;Name = Node = atom()</v>
<v>&nbsp;GlobalName = term()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Event = term()</v>
</type>
<desc>
Expand All @@ -196,9 +207,11 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
<item>the pid,</item>
<item><c>Name</c>, if the gen_fsm is locally registered,</item>
<item><c>{Name,Node}</c>, if the gen_fsm is locally
registered at another node, or</item>
<item><c>{global,GlobalName}</c>, if the gen_fsm is globally
registered.</item>
registered at another node, or</item>
<item><c>{global,GlobalName}</c>, if the gen_fsm is globally
registered.</item>
<item><c>{via,Module,ViaName}</c>, if the event manager is registered
through an alternative process registry.</item>
</list>
<p><c>Event</c> is an arbitrary term which is passed as one of
the arguments to <c>Module:StateName/2</c>.</p>
Expand All @@ -208,9 +221,10 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
<name>send_all_state_event(FsmRef, Event) -> ok</name>
<fsummary>Send an event asynchronously to a generic FSM.</fsummary>
<type>
<v>FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()</v>
<v>FsmRef = Name | {Name,Node} | {global,GlobalName}
| {via,Module,ViaName} | pid()</v>
<v>&nbsp;Name = Node = atom()</v>
<v>&nbsp;GlobalName = term()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Event = term()</v>
</type>
<desc>
Expand All @@ -232,9 +246,10 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
<name>sync_send_event(FsmRef, Event, Timeout) -> Reply</name>
<fsummary>Send an event synchronously to a generic FSM.</fsummary>
<type>
<v>FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()</v>
<v>FsmRef = Name | {Name,Node} | {global,GlobalName}
| {via,Module,ViaName} | pid()</v>
<v>&nbsp;Name = Node = atom()</v>
<v>&nbsp;GlobalName = term()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Event = term()</v>
<v>Timeout = int()>0 | infinity</v>
<v>Reply = term()</v>
Expand Down Expand Up @@ -264,9 +279,10 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
<name>sync_send_all_state_event(FsmRef, Event, Timeout) -> Reply</name>
<fsummary>Send an event synchronously to a generic FSM.</fsummary>
<type>
<v>FsmRef = Name | {Name,Node} | {global,GlobalName} | pid()</v>
<v>FsmRef = Name | {Name,Node} | {global,GlobalName}
| {via,Module,ViaName} | pid()</v>
<v>&nbsp;Name = Node = atom()</v>
<v>&nbsp;GlobalName = term()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Event = term()</v>
<v>Timeout = int()>0 | infinity</v>
<v>Reply = term()</v>
Expand Down Expand Up @@ -388,9 +404,10 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
<v>&nbsp;&nbsp;&nbsp;&nbsp;| {log_to_file,FileName} | {install,{Func,FuncState}}</v>
<v>StateName = atom()</v>
<v>StateData = term()</v>
<v>FsmName = {local,Name} | {global,GlobalName}</v>
<v>FsmName = {local,Name} | {global,GlobalName}
| {via,Module,ViaName}</v>
<v>&nbsp;Name = atom()</v>
<v>&nbsp;GlobalName = term()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Timeout = int() | infinity</v>
</type>
<desc>
Expand Down
39 changes: 27 additions & 12 deletions lib/stdlib/doc/src/gen_server.xml
View file
Expand Up @@ -83,9 +83,10 @@ gen_server:abcast -----> Module:handle_cast/2
<name>start_link(ServerName, Module, Args, Options) -> Result</name>
<fsummary>Create a gen_server process in a supervision tree.</fsummary>
<type>
<v>ServerName = {local,Name} | {global,GlobalName}</v>
<v>ServerName = {local,Name} | {global,GlobalName}
| {via,Module,ViaName}</v>
<v>&nbsp;Name = atom()</v>
<v>&nbsp;GlobalName = term()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Module = atom()</v>
<v>Args = term()</v>
<v>Options = [Option]</v>
Expand All @@ -111,14 +112,22 @@ gen_server:abcast -----> Module:handle_cast/2
If <c>ServerName={global,GlobalName}</c> the gen_server is
registered globally as <c>GlobalName</c> using
<c>global:register_name/2</c>. If no name is provided,
the gen_server is not registered.</p>
the gen_server is not registered.
If <c>EventMgrName={via,Module,ViaName}</c>, the event manager will
register with the registry represented by <c>Module</c>.
The <c>Module</c> callback should export the functions
<c>register_name/2</c>, <c>unregister_name/1</c>,
<c>whereis_name/1</c> and <c>send/2</c>, which should behave like the
corresponding functions in <c>global</c>. Thus,
<c>{via,global,GlobalName}</c> is a valid reference.</p>
<p><c>Module</c> is the name of the callback module.</p>
<p><c>Args</c> is an arbitrary term which is passed as
the argument to <c>Module:init/1</c>.</p>
<p>If the option <c>{timeout,Time}</c> is present,
the gen_server is allowed to spend <c>Time</c> milliseconds
initializing or it will be terminated and the start function
will return <c>{error,timeout}</c>.</p>
will return <c>{error,timeout}</c>.
</p>
<p>If the option <c>{debug,Dbgs}</c> is present,
the corresponding <c>sys</c> function will be called for each
item in <c>Dbgs</c>. See
Expand Down Expand Up @@ -151,9 +160,10 @@ gen_server:abcast -----> Module:handle_cast/2
<name>start(ServerName, Module, Args, Options) -> Result</name>
<fsummary>Create a stand-alone gen_server process.</fsummary>
<type>
<v>ServerName = {local,Name} | {global,GlobalName}</v>
<v>ServerName = {local,Name} | {global,GlobalName}
| {via,Module,ViaName}</v>
<v>&nbsp;Name = atom()</v>
<v>&nbsp;GlobalName = term()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Module = atom()</v>
<v>Args = term()</v>
<v>Options = [Option]</v>
Expand All @@ -178,9 +188,10 @@ gen_server:abcast -----> Module:handle_cast/2
<name>call(ServerRef, Request, Timeout) -> Reply</name>
<fsummary>Make a synchronous call to a generic server.</fsummary>
<type>
<v>ServerRef = Name | {Name,Node} | {global,GlobalName} | pid()</v>
<v>ServerRef = Name | {Name,Node} | {global,GlobalName}
| {via,Module,ViaName} | pid()</v>
<v>&nbsp;Node = atom()</v>
<v>&nbsp;GlobalName = term()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Request = term()</v>
<v>Timeout = int()>0 | infinity</v>
<v>Reply = term()</v>
Expand All @@ -198,6 +209,8 @@ gen_server:abcast -----> Module:handle_cast/2
registered at another node, or</item>
<item><c>{global,GlobalName}</c>, if the gen_server is
globally registered.</item>
<item><c>{via,Module,ViaName}</c>, if the gen_server is
registered through an alternative process registry.</item>
</list>
<p><c>Request</c> is an arbitrary term which is passed as one of
the arguments to <c>Module:handle_call/3</c>.</p>
Expand Down Expand Up @@ -281,9 +294,10 @@ gen_server:abcast -----> Module:handle_cast/2
<name>cast(ServerRef, Request) -> ok</name>
<fsummary>Send an asynchronous request to a generic server.</fsummary>
<type>
<v>ServerRef = Name | {Name,Node} | {global,GlobalName} | pid()</v>
<v>ServerRef = Name | {Name,Node} | {global,GlobalName}
| {via,Module,ViaName} | pid()</v>
<v>&nbsp;Node = atom()</v>
<v>&nbsp;GlobalName = term()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Request = term()</v>
</type>
<desc>
Expand Down Expand Up @@ -355,9 +369,10 @@ gen_server:abcast -----> Module:handle_cast/2
<v>&nbsp;&nbsp;&nbsp;Dbg = trace | log | statistics</v>
<v>&nbsp;&nbsp;&nbsp;&nbsp;| {log_to_file,FileName} | {install,{Func,FuncState}}</v>
<v>State = term()</v>
<v>ServerName = {local,Name} | {global,GlobalName}</v>
<v>ServerName = {local,Name} | {global,GlobalName}
| {via,Module,ViaName}</v>
<v>&nbsp;Name = atom()</v>
<v>&nbsp;GlobalName = term()</v>
<v>&nbsp;GlobalName = ViaName = term()</v>
<v>Timeout = int() | infinity</v>
</type>
<desc>
Expand Down

0 comments on commit d9ee75f

Please sign in to comment.