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, 27 insertions, 12 deletions

diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml
index 1045766e01..90b77d5cb6 100644
--- a/lib/stdlib/doc/src/gen_server.xml
+++ b/lib/stdlib/doc/src/gen_server.xml
@@ -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>
@@ -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
@@ -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>
@@ -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>
@@ -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>
@@ -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>
@@ -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>