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

5 files changed, 241 insertions, 13 deletions

diff --git a/lib/stdlib/test/Makefile b/lib/stdlib/test/Makefile
index aa6a660c34..b36265302c 100644
--- a/lib/stdlib/test/Makefile
+++ b/lib/stdlib/test/Makefile
@@ -20,6 +20,7 @@ MODULES= \
 	digraph_utils_SUITE \
 	dummy1_h \
 	dummy_h \
+	dummy_via \
 	edlin_expand_SUITE \
 	epp_SUITE \
 	erl_eval_helper \
diff --git a/lib/stdlib/test/dummy_via.erl b/lib/stdlib/test/dummy_via.erl
new file mode 100644
index 0000000000..e405811cbe
--- /dev/null
+++ b/lib/stdlib/test/dummy_via.erl
@@ -0,0 +1,94 @@
+-module(dummy_via).
+-export([reset/0,
+	 register_name/2,
+	 whereis_name/1,
+	 unregister_name/1,
+	 send/2]).
+
+
+reset() ->
+    P = whereis(?MODULE),
+    catch unlink(P),
+    Ref = erlang:monitor(process, P),
+    catch exit(P, kill),
+    receive {'DOWN',Ref,_,_,_} -> ok end,
+    Me = self(),
+    Pid = spawn_link(fun() ->
+			     register(?MODULE, self()),
+			     Me ! {self(), started},
+			     loop([])
+		     end),
+    receive
+	{Pid, started} ->
+	    Pid
+    after 10000 ->
+	    exit(timeout)
+    end.
+
+register_name(Name, Pid) when is_pid(Pid) ->
+    call({register_name, Name, Pid}).
+
+unregister_name(Name) ->
+    call({unregister_name, Name}).
+
+whereis_name(Name) ->
+    call({whereis_name, Name}).
+
+send(Name, Msg) ->
+    case whereis_name(Name) of
+	undefined ->
+	    exit({badarg, {Name, Msg}});
+	Pid when is_pid(Pid) ->
+	    Pid ! Msg,
+	    Pid
+    end.
+
+call(Req) ->
+    MRef = erlang:monitor(process, ?MODULE),
+    ?MODULE ! {self(), MRef, Req},
+    receive
+	{'DOWN', MRef, _, _, _} ->
+	    erlang:error(badarg);
+	{MRef, badarg} ->
+	    erlang:error(badarg);
+	{MRef, Reply} ->
+	    Reply
+    after 5000 ->
+	    erlang:error(timeout)
+    end.
+
+loop(Reg) ->
+    receive
+	{'DOWN', _, _, P, _} when is_pid(P) ->
+	    loop([X || {_,Pid,_} = X <- Reg, Pid =/= P]);
+	{From, Ref, Request} when is_pid(From), is_reference(Ref) ->
+	    {Reply, NewReg} = handle_request(Request, Reg),
+	    From ! {Ref, Reply},
+	    loop(NewReg)
+    end.
+
+handle_request({register_name, Name, Pid}, Reg) when is_pid(Pid) ->
+    case lists:keyfind(Name, 1, Reg) of
+	false ->
+	    Ref = erlang:monitor(process, Pid),
+	    {yes, [{Name, Pid, Ref}|Reg]};
+	_ ->
+	    {no, Reg}
+    end;
+handle_request({whereis_name, Name}, Reg) ->
+    case lists:keyfind(Name, 1, Reg) of
+	{_, Pid, _} ->
+	    {Pid, Reg};
+	false ->
+	    {undefined, Reg}
+    end;
+handle_request({unregister_name, Name}, Reg) ->
+    case lists:keyfind(Name, 1, Reg) of
+	{_, _, Ref} ->
+	    catch erlang:demonitor(Ref);
+	_ ->
+	    ok
+    end,
+    {ok, lists:keydelete(Name, 1, Reg)};
+handle_request(_, Reg) ->
+    {badarg, Reg}.
diff --git a/lib/stdlib/test/gen_event_SUITE.erl b/lib/stdlib/test/gen_event_SUITE.erl
index b3a7edc140..5c51e12e35 100644
--- a/lib/stdlib/test/gen_event_SUITE.erl
+++ b/lib/stdlib/test/gen_event_SUITE.erl
@@ -62,6 +62,8 @@ start(suite) -> [];
 start(Config) when is_list(Config) ->
     OldFl = process_flag(trap_exit, true),
 
+    ?line dummy_via:reset(),
+
     ?line {ok, Pid0} = gen_event:start(), %anonymous
     ?line [] = gen_event:which_handlers(Pid0),
     ?line ok = gen_event:stop(Pid0),
@@ -85,6 +87,11 @@ start(Config) when is_list(Config) ->
     ?line [] = gen_event:which_handlers(Pid4),
     ?line ok = gen_event:stop({global, my_dummy_name}),
 
+    ?line {ok, Pid5} = gen_event:start_link({via, dummy_via, my_dummy_name}),
+    ?line [] = gen_event:which_handlers({via, dummy_via, my_dummy_name}),
+    ?line [] = gen_event:which_handlers(Pid5),
+    ?line ok = gen_event:stop({via, dummy_via, my_dummy_name}),
+
     ?line {ok, _} = gen_event:start_link({local, my_dummy_name}),
     ?line {error, {already_started, _}} =
 	gen_event:start_link({local, my_dummy_name}),
@@ -92,15 +99,28 @@ start(Config) when is_list(Config) ->
 	gen_event:start({local, my_dummy_name}),
     ?line ok = gen_event:stop(my_dummy_name),
 
-    ?line {ok, Pid5} = gen_event:start_link({global, my_dummy_name}),
+    ?line {ok, Pid6} = gen_event:start_link({global, my_dummy_name}),
     ?line {error, {already_started, _}} =
 	gen_event:start_link({global, my_dummy_name}),
     ?line {error, {already_started, _}} =
 	gen_event:start({global, my_dummy_name}),
 
-    exit(Pid5, shutdown),
+    exit(Pid6, shutdown),
+    receive
+	{'EXIT', Pid6, shutdown} -> ok
+    after 10000 ->
+	    ?t:fail(exit_gen_event)
+    end,
+
+    ?line {ok, Pid7} = gen_event:start_link({via, dummy_via, my_dummy_name}),
+    ?line {error, {already_started, _}} =
+	gen_event:start_link({via, dummy_via, my_dummy_name}),
+    ?line {error, {already_started, _}} =
+	gen_event:start({via, dummy_via, my_dummy_name}),
+
+    exit(Pid7, shutdown),
     receive
-	{'EXIT', Pid5, shutdown} -> ok
+	{'EXIT', Pid7, shutdown} -> ok
     after 10000 ->
 	    ?t:fail(exit_gen_event)
     end,
diff --git a/lib/stdlib/test/gen_fsm_SUITE.erl b/lib/stdlib/test/gen_fsm_SUITE.erl
index d60629d841..bdb4ea65b5 100644
--- a/lib/stdlib/test/gen_fsm_SUITE.erl
+++ b/lib/stdlib/test/gen_fsm_SUITE.erl
@@ -21,11 +21,11 @@
 -include_lib("test_server/include/test_server.hrl").
 
 %% Test cases
--export([all/0, suite/0,groups/0,init_per_suite/1, end_per_suite/1, 
+-export([all/0, suite/0,groups/0,init_per_suite/1, end_per_suite/1,
 	 init_per_group/2,end_per_group/2]).
 
--export([ start1/1, start2/1, start3/1, start4/1 , start5/1, start6/1,
-	 start7/1, start8/1, start9/1, start10/1, start11/1]).
+-export([start1/1, start2/1, start3/1, start4/1, start5/1, start6/1,
+	 start7/1, start8/1, start9/1, start10/1, start11/1, start12/1]).
 
 -export([ abnormal1/1, abnormal2/1]).
 
@@ -56,14 +56,14 @@
 
 suite() -> [{ct_hooks,[ts_install_cth]}].
 
-all() -> 
+all() ->
     [{group, start}, {group, abnormal}, shutdown,
      {group, sys}, hibernate, enter_loop].
 
-groups() -> 
+groups() ->
     [{start, [],
       [start1, start2, start3, start4, start5, start6, start7,
-       start8, start9, start10, start11]},
+       start8, start9, start10, start11, start12]},
      {abnormal, [], [abnormal1, abnormal2]},
      {sys, [],
       [sys1, call_format_status, error_format_status]}].
@@ -258,6 +258,25 @@ start11(Config) when is_list(Config) ->
     test_server:messages_get(),
     ok.
 
+%% Via register linked
+start12(Config) when is_list(Config) ->
+    ?line dummy_via:reset(),
+    ?line {ok, Pid} =
+	gen_fsm:start_link({via, dummy_via, my_fsm}, gen_fsm_SUITE, [], []),
+    ?line {error, {already_started, Pid}} =
+	gen_fsm:start_link({via, dummy_via, my_fsm}, gen_fsm_SUITE, [], []),
+    ?line {error, {already_started, Pid}} =
+	gen_fsm:start({via, dummy_via, my_fsm}, gen_fsm_SUITE, [], []),
+
+    ?line ok = do_func_test(Pid),
+    ?line ok = do_sync_func_test(Pid),
+    ?line ok = do_func_test({via, dummy_via, my_fsm}),
+    ?line ok = do_sync_func_test({via, dummy_via, my_fsm}),
+    ?line stop_it({via, dummy_via, my_fsm}),
+
+    test_server:messages_get(),
+    ok.
+
 
 %% Check that time outs in calls work
 abnormal1(suite) -> [];
@@ -362,7 +381,25 @@ call_format_status(Config) when is_list(Config) ->
     ?line Status4 = sys:get_status(GlobalName2),
     ?line {status, Pid4, _Mod, [_PDict4, running, _, _, Data4]} = Status4,
     ?line [format_status_called | _] = lists:reverse(Data4),
-    ?line stop_it(Pid4).
+    ?line stop_it(Pid4),
+
+    %% check that format_status can handle a name being a term other than a
+    %% pid or atom
+    ?line dummy_via:reset(),
+    ViaName1 = {via, dummy_via, "CallFormatStatus"},
+    ?line {ok, Pid5} = gen_fsm:start(ViaName1, gen_fsm_SUITE, [], []),
+    ?line Status5 = sys:get_status(ViaName1),
+    ?line {status, Pid5, _Mod, [_PDict5, running, _, _, Data5]} = Status5,
+    ?line [format_status_called | _] = lists:reverse(Data5),
+    ?line stop_it(Pid5),
+    ViaName2 = {via, dummy_via, {name, "term"}},
+    ?line {ok, Pid6} = gen_fsm:start(ViaName2, gen_fsm_SUITE, [], []),
+    ?line Status6 = sys:get_status(ViaName2),
+    ?line {status, Pid6, _Mod, [_PDict6, running, _, _, Data6]} = Status6,
+    ?line [format_status_called | _] = lists:reverse(Data6),
+    ?line stop_it(Pid6).
+
+
 
 error_format_status(Config) when is_list(Config) ->
     ?line error_logger_forwarder:register(),
@@ -520,6 +557,8 @@ enter_loop(doc) ->
 enter_loop(Config) when is_list(Config) ->
     OldFlag = process_flag(trap_exit, true),
 
+    ?line dummy_via:reset(),
+
     %% Locally registered process + {local, Name}
     ?line {ok, Pid1a} =
 	proc_lib:start_link(?MODULE, enter_loop, [local, local]),
@@ -623,10 +662,22 @@ enter_loop(Config) when is_list(Config) ->
 	{'EXIT', Pid6b, process_not_registered_globally} ->
 	    ok
     after 1000 ->
-	    ?line test_server:fail(gen_server_started)
+	    ?line test_server:fail(gen_fsm_started)
     end,
     global:unregister_name(armitage),
 
+    dummy_via:register_name(armitage, self()),
+    ?line {ok, Pid6c} =
+	proc_lib:start_link(?MODULE, enter_loop, [anon, via]),
+    receive
+	{'EXIT', Pid6c, {process_not_registered_via, dummy_via}} ->
+	    ok
+    after 1000 ->
+	    ?line test_server:fail({gen_fsm_started, process_info(self(),
+								 messages)})
+    end,
+    dummy_via:unregister_name(armitage),
+
     process_flag(trap_exit, OldFlag),
     ok.
 
@@ -635,6 +686,7 @@ enter_loop(Reg1, Reg2) ->
     case Reg1 of
 	local -> register(armitage, self());
 	global -> global:register_name(armitage, self());
+	via -> dummy_via:register_name(armitage, self());
 	anon -> ignore
     end,
     proc_lib:init_ack({ok, self()}),
@@ -643,6 +695,9 @@ enter_loop(Reg1, Reg2) ->
 	    gen_fsm:enter_loop(?MODULE, [], state0, [], {local,armitage});
 	global ->
 	    gen_fsm:enter_loop(?MODULE, [], state0, [], {global,armitage});
+	via ->
+	    gen_fsm:enter_loop(?MODULE, [], state0, [],
+			       {via, dummy_via, armitage});
 	anon ->
 	    gen_fsm:enter_loop(?MODULE, [], state0, [])
     end.
diff --git a/lib/stdlib/test/gen_server_SUITE.erl b/lib/stdlib/test/gen_server_SUITE.erl
index 7fb8d54f2d..cdf15ba017 100644
--- a/lib/stdlib/test/gen_server_SUITE.erl
+++ b/lib/stdlib/test/gen_server_SUITE.erl
@@ -36,7 +36,7 @@
 	]).
 
 % spawn export
--export([spec_init_local/2, spec_init_global/2, 
+-export([spec_init_local/2, spec_init_global/2, spec_init_via/2,
 	 spec_init_default_timeout/2, spec_init_anonymous/1,
 	 spec_init_anonymous_default_timeout/1,
 	 spec_init_not_proc_lib/1, cast_fast_messup/0]).
@@ -199,6 +199,35 @@ start(Config) when is_list(Config) ->
 		  test_server:fail(not_stopped)
 	  end,
 
+    %% via register
+    ?line dummy_via:reset(),
+    ?line {ok, Pid6} =
+	gen_server:start({via, dummy_via, my_test_name},
+			 gen_server_SUITE, [], []),
+    ?line ok = gen_server:call({via, dummy_via, my_test_name}, started_p),
+    ?line {error, {already_started, Pid6}} =
+	gen_server:start({via, dummy_via, my_test_name},
+			 gen_server_SUITE, [], []),
+    ?line ok = gen_server:call({via, dummy_via, my_test_name}, stop),
+    test_server:sleep(1),
+    ?line {'EXIT', {noproc,_}} = (catch gen_server:call(Pid6, started_p, 10)),
+
+    %% via register linked
+    ?line dummy_via:reset(),
+    ?line {ok, Pid7} =
+	gen_server:start_link({via, dummy_via, my_test_name},
+			      gen_server_SUITE, [], []),
+    ?line ok = gen_server:call({via, dummy_via, my_test_name}, started_p),
+    ?line {error, {already_started, Pid7}} =
+	gen_server:start({via, dummy_via, my_test_name},
+			 gen_server_SUITE, [], []),
+    ?line ok = gen_server:call({via, dummy_via, my_test_name}, stop),
+    ?line receive
+	      {'EXIT', Pid7, stopped} ->
+		  ok
+	  after 5000 ->
+		  test_server:fail(not_stopped)
+	  end,
     test_server:messages_get(),
 
     %% Must wait for all error messages before going to next test.
@@ -853,6 +882,8 @@ otp_5854(doc) ->
 otp_5854(Config) when is_list(Config) ->
     OldFlag = process_flag(trap_exit, true),
 
+    ?line dummy_via:reset(),
+
     %% Make sure gen_server:enter_loop does not accept {local,Name}
     %% when it's another process than the calling one which is
     %% registered under that name
@@ -881,6 +912,18 @@ otp_5854(Config) when is_list(Config) ->
     end,
     global:unregister_name(armitage),
 
+    %% (same for {via, Mod, Name})
+    dummy_via:register_name(armitage, self()),
+    ?line {ok, Pid3} =
+	start_link(spec_init_via, [{not_ok, armitage}, []]),
+    receive
+	{'EXIT', Pid3, {process_not_registered_via, dummy_via}} ->
+	    ok
+    after 1000 ->
+	    ?line test_server:fail(gen_server_started)
+    end,
+    dummy_via:unregister_name(armitage),
+
     process_flag(trap_exit, OldFlag),
     ok.
 
@@ -1060,7 +1103,22 @@ spec_init_global({not_ok, Name}, Options) ->
     %% Supervised init can occur here  ...
     gen_server:enter_loop(?MODULE, Options, {}, {global, Name}, infinity).
 
-spec_init_default_timeout({ok, Name}, Options) -> 
+spec_init_via({ok, Name}, Options) ->
+    process_flag(trap_exit, true),
+    dummy_via:register_name(Name, self()),
+    proc_lib:init_ack({ok, self()}),
+    %% Supervised init can occur here  ...
+    gen_server:enter_loop(?MODULE, Options, {},
+			  {via, dummy_via, Name}, infinity);
+
+spec_init_via({not_ok, Name}, Options) ->
+    process_flag(trap_exit, true),
+    proc_lib:init_ack({ok, self()}),
+    %% Supervised init can occur here  ...
+    gen_server:enter_loop(?MODULE, Options, {},
+			  {via, dummy_via, Name}, infinity).
+
+spec_init_default_timeout({ok, Name}, Options) ->
     process_flag(trap_exit, true),
     register(Name, self()),
     proc_lib:init_ack({ok, self()}),