Add plugin support for alternative name lookup

OTP behaviour instances (gen_server, gen_fsm, gen_event) can currently
register themselves either locally or globally, and the behaviour
libraries (including gen.erl) support both addressing methods, as well
as the normal Pid and {Name, Node}.

However, there are alternative registry implementations - e.g. gproc -
and one can well imagine other ways of locating a behaviour instance,
e.g. on a node connected only via a TCP tunnel, rather than via
Distributed Erlang. In all these cases, one needs to write extra code
to identify the behaviour instance, even though the instance itself
need not be aware of how it is located.

This patch introduces a new way of locating a behaviour instance:
{via, Module, Name}.

Module is expected to export a subset of the functions in global.erl,
namely:

register_name(Name, Pid) -> yes | no
whereis_name(Name)  -> pid() | undefined
unregister_name(Name) -> ok
send(Name, Msg) -> Pid

Semantics are expected to be the same as for global.erl

This can be used in all places where {global, Name} is accepted.

faulty export in gen_fsm_SUITE.erl

await process death in dummy_via:reset()

fix error in gen_[server|fsm]:enter_loop()

fix documentation

1 files changed, 46 insertions, 15 deletions

diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml
index 24bcb419fe..0f50b37de6 100644
--- a/lib/stdlib/doc/src/gen_event.xml
+++ b/lib/stdlib/doc/src/gen_event.xml
@@ -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>
@@ -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
@@ -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>
@@ -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>
@@ -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.
@@ -207,8 +222,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>
@@ -252,8 +269,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>
@@ -277,8 +296,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>
@@ -317,8 +338,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>
@@ -345,8 +368,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>
@@ -389,8 +414,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>
@@ -411,8 +438,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>
@@ -428,8 +457,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