Merge branch 'sa/callback-attr'

* sa/callback-attr:
  Add callback specs into 'application' module in kernel
  Add callback specs to tftp module following internet documentation
  Add callback specs to inets_service module following possibly deprecated comments
  Add '-callback' attributes in stdlib's behaviours
  Update primary bootstrap
  Update the documentation with information on the callback attribute
  Automatically generate 'behaviour_info' function from '-callback' attributes
  Add '-callback' attribute to language syntax

OTP-9621

7 files changed, 150 insertions, 84 deletions

diff --git a/lib/stdlib/src/erl_lint.erl b/lib/stdlib/src/erl_lint.erl
index dd0b9bc2ab..78b996d94b 100644
--- a/lib/stdlib/src/erl_lint.erl
+++ b/lib/stdlib/src/erl_lint.erl
@@ -123,6 +123,7 @@ value_option(Flag, Default, On, OnVal, Off, OffVal, Opts) ->
                called= [] :: [{fa(),line()}],		%Called functions
                usage = #usage{}		:: #usage{},
 	       specs = dict:new()	:: dict(),	%Type specifications
+	       callbacks = dict:new()   :: dict(),      %Callback types
 	       types = dict:new()	:: dict(),	%Type definitions
 	       exp_types=gb_sets:empty():: gb_set()	%Exported types
               }).
@@ -310,8 +311,6 @@ format_error({conflicting_behaviours,{Name,Arity},B,FirstL,FirstB}) ->
 format_error({undefined_behaviour_func, {Func,Arity}, Behaviour}) ->
     io_lib:format("undefined callback function ~w/~w (behaviour '~w')",
 		  [Func,Arity,Behaviour]);
-format_error({undefined_behaviour_func, {Func,Arity,_Spec}, Behaviour}) ->
-    format_error({undefined_behaviour_func, {Func,Arity}, Behaviour});
 format_error({undefined_behaviour,Behaviour}) ->
     io_lib:format("behaviour ~w undefined", [Behaviour]);
 format_error({undefined_behaviour_callbacks,Behaviour}) ->
@@ -320,6 +319,9 @@ format_error({undefined_behaviour_callbacks,Behaviour}) ->
 format_error({ill_defined_behaviour_callbacks,Behaviour}) ->
     io_lib:format("behaviour ~w callback functions erroneously defined",
 		  [Behaviour]);
+format_error({behaviour_info, {_M,F,A}}) ->
+    io_lib:format("cannot define callback attibute for ~w/~w when "
+                  "behaviour_info is defined",[F,A]);
 %% --- types and specs ---
 format_error({singleton_typevar, Name}) ->
     io_lib:format("type variable ~w is only used once (is unbound)", [Name]);
@@ -348,12 +350,16 @@ format_error({type_syntax, Constr}) ->
     io_lib:format("bad ~w type", [Constr]);
 format_error({redefine_spec, {M, F, A}}) ->
     io_lib:format("spec for ~w:~w/~w already defined", [M, F, A]);
+format_error({redefine_callback, {M, F, A}}) ->
+    io_lib:format("callback ~w:~w/~w already defined", [M, F, A]);
 format_error({spec_fun_undefined, {M, F, A}}) ->
     io_lib:format("spec for undefined function ~w:~w/~w", [M, F, A]);
 format_error({missing_spec, {F,A}}) ->
     io_lib:format("missing specification for function ~w/~w", [F, A]);
 format_error(spec_wrong_arity) ->
     "spec has the wrong arity";
+format_error(callback_wrong_arity) ->
+    "callback has the wrong arity";
 format_error({imported_predefined_type, Name}) ->
     io_lib:format("referring to built-in type ~w as a remote type; "
 		  "please take out the module name", [Name]);
@@ -747,6 +753,8 @@ attribute_state({attribute,L,opaque,{TypeName,TypeDef,Args}}, St) ->
     type_def(opaque, L, TypeName, TypeDef, Args, St);
 attribute_state({attribute,L,spec,{Fun,Types}}, St) ->
     spec_decl(L, Fun, Types, St);
+attribute_state({attribute,L,callback,{Fun,Types}}, St) ->
+    callback_decl(L, Fun, Types, St);
 attribute_state({attribute,L,on_load,Val}, St) ->
     on_load(L, Val, St);
 attribute_state({attribute,_L,_Other,_Val}, St) -> % Ignore others
@@ -840,7 +848,8 @@ post_traversal_check(Forms, St0) ->
     StB = check_unused_types(Forms, StA),
     StC = check_untyped_records(Forms, StB),
     StD = check_on_load(StC),
-    check_unused_records(Forms, StD).
+    StE = check_unused_records(Forms, StD),
+    check_callback_information(StE).
 
 %% check_behaviour(State0) -> State
 %% Check that the behaviour attribute is valid.
@@ -1139,6 +1148,23 @@ check_unused_records(Forms, St0) ->
             St0
     end.
 
+check_callback_information(#lint{callbacks = Callbacks,
+				 defined = Defined} = State) ->
+    case gb_sets:is_member({behaviour_info,1}, Defined) of
+	false -> State;
+	true ->
+	    case dict:size(Callbacks) of
+		0 -> State;
+		_ ->
+		    CallbacksList = dict:to_list(Callbacks),
+		    FoldL =
+			fun({Fa,Line},St) ->
+				add_error(Line, {behaviour_info, Fa}, St)
+			end,
+		    lists:foldl(FoldL, State, CallbacksList)
+	    end
+    end.
+
 %% For storing the import list we use the orddict module.
 %% We know an empty set is [].
 
@@ -2770,6 +2796,20 @@ spec_decl(Line, MFA0, TypeSpecs, St0 = #lint{specs = Specs, module = Mod}) ->
 	false -> check_specs(TypeSpecs, Arity, St1)
     end.
 
+%% callback_decl(Line, Fun, Types, State) -> State.
+
+callback_decl(Line, MFA0, TypeSpecs,
+	      St0 = #lint{callbacks = Callbacks, module = Mod}) ->
+    MFA = case MFA0 of
+	      {F, Arity} -> {Mod, F, Arity};
+	      {_M, _F, Arity} -> MFA0
+	  end,
+    St1 = St0#lint{callbacks = dict:store(MFA, Line, Callbacks)},
+    case dict:is_key(MFA, Callbacks) of
+	true -> add_error(Line, {redefine_callback, MFA}, St1);
+	false -> check_specs(TypeSpecs, Arity, St1)
+    end.
+
 check_specs([FunType|Left], Arity, St0) ->
     {FunType1, CTypes} =
 	case FunType of
@@ -3275,6 +3315,8 @@ modify_line1({attribute,L,record,{Name,Fields}}, Mf) ->
     {attribute,Mf(L),record,{Name,modify_line1(Fields, Mf)}};
 modify_line1({attribute,L,spec,{Fun,Types}}, Mf) ->
     {attribute,Mf(L),spec,{Fun,modify_line1(Types, Mf)}};
+modify_line1({attribute,L,callback,{Fun,Types}}, Mf) ->
+    {attribute,Mf(L),callback,{Fun,modify_line1(Types, Mf)}};
 modify_line1({attribute,L,type,{TypeName,TypeDef,Args}}, Mf) ->
     {attribute,Mf(L),type,{TypeName,modify_line1(TypeDef, Mf),
 			   modify_line1(Args, Mf)}};
diff --git a/lib/stdlib/src/erl_parse.yrl b/lib/stdlib/src/erl_parse.yrl
index bd5d65a1e1..709bd83e6f 100644
--- a/lib/stdlib/src/erl_parse.yrl
+++ b/lib/stdlib/src/erl_parse.yrl
@@ -62,7 +62,7 @@ char integer float atom string var
 '==' '/=' '=<' '<' '>=' '>' '=:=' '=/=' '<='
 '<<' '>>'
 '!' '=' '::' '..' '...'
-'spec' % helper
+'spec' 'callback' % helper
 dot.
 
 Expect 2.
@@ -77,6 +77,7 @@ attribute -> '-' atom attr_val               : build_attribute('$2', '$3').
 attribute -> '-' atom typed_attr_val         : build_typed_attribute('$2','$3').
 attribute -> '-' atom '(' typed_attr_val ')' : build_typed_attribute('$2','$4').
 attribute -> '-' 'spec' type_spec            : build_type_spec('$2', '$3').
+attribute -> '-' 'callback' type_spec        : build_type_spec('$2', '$3').
 
 type_spec -> spec_fun type_sigs : {'$1', '$2'}.
 type_spec -> '(' spec_fun type_sigs ')' : {'$2', '$3'}.
@@ -549,6 +550,8 @@ Erlang code.
       ErrorInfo :: error_info().
 parse_form([{'-',L1},{atom,L2,spec}|Tokens]) ->
     parse([{'-',L1},{'spec',L2}|Tokens]);
+parse_form([{'-',L1},{atom,L2,callback}|Tokens]) ->
+    parse([{'-',L1},{'callback',L2}|Tokens]);
 parse_form(Tokens) ->
     parse(Tokens).
 
@@ -603,7 +606,8 @@ build_typed_attribute({atom,La,Attr},_) ->
         _      -> ret_err(La, "bad attribute")
     end.
 
-build_type_spec({spec,La}, {SpecFun, TypeSpecs}) ->
+build_type_spec({Kind,La}, {SpecFun, TypeSpecs})
+  when (Kind =:= spec) or (Kind =:= callback) ->
     NewSpecFun =
 	case SpecFun of
 	    {atom, _, Fun} ->
@@ -617,7 +621,7 @@ build_type_spec({spec,La}, {SpecFun, TypeSpecs}) ->
 		%% Old style spec. Allow this for now.
 		{Mod,Fun,Arity}
 	    end,
-    {attribute,La,spec,{NewSpecFun, TypeSpecs}}.
+    {attribute,La,Kind,{NewSpecFun, TypeSpecs}}.
 
 find_arity_from_specs([Spec|_]) ->
     %% Use the first spec to find the arity. If all are not the same,
diff --git a/lib/stdlib/src/gen_event.erl b/lib/stdlib/src/gen_event.erl
index d1dd074fba..9879b76391 100644
--- a/lib/stdlib/src/gen_event.erl
+++ b/lib/stdlib/src/gen_event.erl
@@ -36,8 +36,6 @@
 	 add_handler/3, add_sup_handler/3, delete_handler/3, swap_handler/3,
 	 swap_sup_handler/3, which_handlers/1, call/3, call/4, wake_hib/4]).
 
--export([behaviour_info/1]).
-
 -export([init_it/6,
 	 system_continue/3,
 	 system_terminate/4,
@@ -60,14 +58,6 @@
 %%%  API
 %%%=========================================================================
 
--spec behaviour_info(atom()) -> 'undefined' | [{atom(), arity()}].
-
-behaviour_info(callbacks) ->
-    [{init,1},{handle_event,2},{handle_call,2},{handle_info,2},
-     {terminate,2},{code_change,3}];
-behaviour_info(_Other) ->
-    undefined.
-
 %% gen_event:start(Handler) -> {ok, Pid} | {error, What}
 %%   gen_event:add_handler(Handler, Mod, Args) -> ok | Other
 %%      gen_event:notify(Handler, Event) -> ok
@@ -78,41 +68,36 @@ behaviour_info(_Other) ->
 %%   gen_event:which_handler(Handler) -> [Mod]
 %% gen_event:stop(Handler) -> ok 
 
-
-%% handlers must export
-%% Mod:init(Args) -> {ok, State} | Other
-%% Mod:handle_event(Event, State) -> 
-%%    {ok, State'} | remove_handler | {swap_handler,Args1,State1,Mod2,Args2}
-%% Mod:handle_info(Info, State) ->
-%%    {ok, State'} | remove_handler | {swap_handler,Args1,State1,Mod2,Args2}
-%% Mod:handle_call(Query, State) -> 
-%%    {ok, Reply, State'} | {remove_handler, Reply} | 
-%%    {swap_handler, Reply, Args1,State1,Mod2,Args2}
-%% Mod:terminate(Args, State) -> Val
-
-
-%% add_handler(H, Mod, Args) -> ok | Other
-%%    Mod:init(Args) -> {ok, State} | Other
-
-%% delete_handler(H, Mod, Args) -> Val
-%%    Mod:terminate(Args, State) -> Val
-
-%% notify(H, Event) 
-%%    Mod:handle_event(Event, State) ->
-%%         {ok, State1}
-%%         remove_handler
-%%               Mod:terminate(remove_handler, State) is called
-%%               the return value is ignored
-%%         {swap_handler, Args1, State1, Mod2, Args2}
-%%               State2 = Mod:terminate(Args1, State1) is called
-%%               the return value is chained into the new module and
-%%               Mod2:init({Args2, State2}) is called
-%%         Other
-%%               Mod:terminate({error, Other}, State) is called
-%%               The return value is ignored
-%% call(H, Mod, Query) -> Val
-%% call(H, Mod, Query, Timeout) -> Val
-%%      Mod:handle_call(Query, State) -> as above
+-callback init(InitArgs :: term()) ->
+    {ok, State :: term()} |
+    {ok, State :: term(), hibernate}.
+-callback handle_event(Event :: term(), State :: term()) ->
+    {ok, NewState :: term()} |
+    {ok, NewState :: term(), hibernate} |
+    {swap_handler, Args1 :: term(), NewState :: term(),
+     Handler2 :: (atom() | {atom(), Id :: term()}), Args2 :: term()} |
+    remove_handler.
+-callback handle_call(Request :: term(), State :: term()) ->
+    {ok, Reply :: term(), NewState :: term()} |
+    {ok, Reply :: term(), NewState :: term(), hibernate} |
+    {swap_handler, Reply :: term(), Args1 :: term(), NewState :: term(),
+     Handler2 :: (atom() | {atom(), Id :: term()}), Args2 :: term()} |
+    {remove_handler, Reply :: term()}.
+-callback handle_info(Info :: term(), State :: term()) ->
+    {ok, NewState :: term()} |
+    {ok, NewState :: term(), hibernate} |
+    {swap_handler, Args1 :: term(), NewState :: term(),
+     Handler2 :: (atom() | {atom(), Id :: term()}), Args2 :: term()} |
+    remove_handler.
+-callback terminate(Args :: (term() | {stop, Reason :: term()} |
+                             stop | remove_handler |
+                             {error, {'EXIT', Reason :: term()}} |
+                             {error, term()}),
+                    State :: term()) ->
+    term().
+-callback code_change(OldVsn :: (term() | {down, term()}),
+                      State :: term(), Extra :: term()) ->
+    {ok, NewState :: term()}.
 
 %%---------------------------------------------------------------------------
 
diff --git a/lib/stdlib/src/gen_fsm.erl b/lib/stdlib/src/gen_fsm.erl
index ea21136bdb..3db8c9f4f2 100644
--- a/lib/stdlib/src/gen_fsm.erl
+++ b/lib/stdlib/src/gen_fsm.erl
@@ -113,8 +113,6 @@
 	 start_timer/2,send_event_after/2,cancel_timer/1,
 	 enter_loop/4, enter_loop/5, enter_loop/6, wake_hib/6]).
 
--export([behaviour_info/1]).
-
 %% Internal exports
 -export([init_it/6,
 	 system_continue/3,
@@ -128,13 +126,38 @@
 %%% Interface functions.
 %%% ---------------------------------------------------
 
--spec behaviour_info(atom()) -> 'undefined' | [{atom(), arity()}].
-
-behaviour_info(callbacks) ->
-    [{init,1},{handle_event,3},{handle_sync_event,4},{handle_info,3},
-     {terminate,3},{code_change,4}];
-behaviour_info(_Other) ->
-    undefined.
+-callback init(Args :: term()) ->
+    {ok, StateName :: atom(), StateData :: term()} |
+    {ok, StateName :: atom(), StateData :: term(), timeout() | hibernate} |
+    {stop, Reason :: term()} | ignore.
+-callback handle_event(Event :: term(), StateName :: atom(),
+                       StateData :: term()) ->
+    {next_state, NextStateName :: atom(), NewStateData :: term()} |
+    {next_state, NextStateName :: atom(), NewStateData :: term(),
+     timeout() | hibernate} |
+    {stop, Reason :: term(), NewStateData :: term()}.
+-callback handle_sync_event(Event :: term(), From :: {pid(), Tag :: term()},
+                            StateName :: atom(), StateData :: term()) ->
+    {reply, Reply :: term(), NextStateName :: atom(), NewStateData :: term()} |
+    {reply, Reply :: term(), NextStateName :: atom(), NewStateData :: term(),
+     timeout() | hibernate} |
+    {next_state, NextStateName :: atom(), NewStateData :: term()} |
+    {next_state, NextStateName :: atom(), NewStateData :: term(),
+     timeout() | hibernate} |
+    {stop, Reason :: term(), Reply :: term(), NewStateData :: term()} |
+    {stop, Reason :: term(), NewStateData :: term()}.
+-callback handle_info(Info :: term(), StateName :: atom(),
+                      StateData :: term()) ->
+    {next_state, NextStateName :: atom(), NewStateData :: term()} |
+    {next_state, NextStateName :: atom(), NewStateData :: term(),
+     timeout() | hibernate} |
+    {stop, Reason :: normal | term(), NewStateData :: term()}.
+-callback terminate(Reason :: normal | shutdown | {shutdown, term()}
+		    | term(), StateName :: atom(), StateData :: term()) ->
+    term().
+-callback code_change(OldVsn :: term() | {down, term()}, StateName :: atom(),
+		      StateData :: term(), Extra :: term()) ->
+    {ok, NextStateName :: atom(), NewStateData :: term()}.
 
 %%% ---------------------------------------------------
 %%% Starts a generic state machine.
diff --git a/lib/stdlib/src/gen_server.erl b/lib/stdlib/src/gen_server.erl
index b8ea3a4de2..dd0ef74f30 100644
--- a/lib/stdlib/src/gen_server.erl
+++ b/lib/stdlib/src/gen_server.erl
@@ -94,8 +94,6 @@
 	 multi_call/2, multi_call/3, multi_call/4,
 	 enter_loop/3, enter_loop/4, enter_loop/5, wake_hib/5]).
 
--export([behaviour_info/1]).
-
 %% System exports
 -export([system_continue/3,
 	 system_terminate/4,
@@ -111,13 +109,32 @@
 %%%  API
 %%%=========================================================================
 
--spec behaviour_info(atom()) -> 'undefined' | [{atom(), arity()}].
-
-behaviour_info(callbacks) ->
-    [{init,1},{handle_call,3},{handle_cast,2},{handle_info,2},
-     {terminate,2},{code_change,3}];
-behaviour_info(_Other) ->
-    undefined.
+-callback init(Args :: term()) ->
+    {ok, State :: term()} | {ok, State :: term(), timeout() | hibernate} |
+    {stop, Reason :: term()} | ignore.
+-callback handle_call(Request :: term(), From :: {pid(), Tag :: term()},
+                      State :: term()) ->
+    {reply, Reply :: term(), NewState :: term()} |
+    {reply, Reply :: term(), NewState :: term(), timeout() | hibernate} |
+    {noreply, NewState :: term()} |
+    {noreply, NewState :: term(), timeout() | hibernate} |
+    {stop, Reason :: term(), Reply :: term(), NewState :: term()} |
+    {stop, Reason :: term(), NewState :: term()}.
+-callback handle_cast(Request :: term(), State :: term()) ->
+    {noreply, NewState :: term()} |
+    {noreply, NewState :: term(), timeout() | hibernate} |
+    {stop, Reason :: term(), NewState :: term()}.
+-callback handle_info(Info :: timeout() | term(), State :: term()) ->
+    {noreply, NewState :: term()} |
+    {noreply, NewState :: term(), timeout() | hibernate} |
+    {stop, Reason :: term(), NewState :: term()}.
+-callback terminate(Reason :: (normal | shutdown | {shutdown, term()} |
+                               term()),
+                    State :: term()) ->
+    term().
+-callback code_change(OldVsn :: (term() | {down, term()}), State :: term(),
+                      Extra :: term()) ->
+    {ok, NewState :: term()}.
 
 %%%  -----------------------------------------------------------------
 %%% Starts a generic server.
diff --git a/lib/stdlib/src/supervisor.erl b/lib/stdlib/src/supervisor.erl
index 36cc7f4f4b..9da0d52f8c 100644
--- a/lib/stdlib/src/supervisor.erl
+++ b/lib/stdlib/src/supervisor.erl
@@ -27,8 +27,6 @@
 	 which_children/1, count_children/1,
 	 check_childspecs/1]).
 
--export([behaviour_info/1]).
-
 %% Internal exports
 -export([init/1, handle_call/3, handle_info/2, terminate/2, code_change/3]).
 -export([handle_cast/2]).
@@ -90,14 +88,12 @@
 
 -define(is_simple(State), State#state.strategy =:= simple_one_for_one).
 
-%%--------------------------------------------------------------------------
-
--spec behaviour_info(atom()) -> 'undefined' | [{atom(), arity()}].
-
-behaviour_info(callbacks) ->
-    [{init,1}];
-behaviour_info(_Other) ->
-    undefined.
+-callback init(Args :: term()) ->
+    {ok, {{RestartStrategy :: strategy(),
+           MaxR            :: non_neg_integer(),
+           MaxT            :: non_neg_integer()},
+           [ChildSpec :: child_spec()]}}
+    | ignore.
 
 %%% ---------------------------------------------------
 %%% This is a general process supervisor built upon gen_server.erl.
diff --git a/lib/stdlib/src/supervisor_bridge.erl b/lib/stdlib/src/supervisor_bridge.erl
index 555cb5a66f..e8405ab9a4 100644
--- a/lib/stdlib/src/supervisor_bridge.erl
+++ b/lib/stdlib/src/supervisor_bridge.erl
@@ -22,15 +22,14 @@
 
 %% External exports
 -export([start_link/2, start_link/3]).
--export([behaviour_info/1]).
 %% Internal exports
 -export([init/1, handle_call/3, handle_cast/2, handle_info/2, terminate/2]).
 -export([code_change/3]).
 
-behaviour_info(callbacks) ->
-    [{init,1},{terminate,2}];
-behaviour_info(_Other) ->
-    undefined.
+-callback init(Args :: term()) ->
+    {ok, Pid :: pid(), State :: term()} | ignore | {error, Error :: term()}.
+-callback terminate(Reason :: (shutdown | term()), State :: term()) ->
+    Ignored :: term().
 
 %%%-----------------------------------------------------------------
 %%% This is a rewrite of supervisor_bridge from BS.3.