From a447b904cff36fa2d690f1d0068eb28589369787 Mon Sep 17 00:00:00 2001 From: Raimo Niskanen Date: Mon, 5 Nov 2018 16:40:52 +0100 Subject: Document system_events better --- lib/stdlib/doc/src/sys.xml | 166 ++++++++++++++++++++++++++++++++++++++++ lib/stdlib/src/otp_internal.erl | 8 ++ lib/stdlib/src/sys.erl | 12 ++- 3 files changed, 184 insertions(+), 2 deletions(-) diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml index 9fe816e33a..78ae4b5c38 100644 --- a/lib/stdlib/doc/src/sys.xml +++ b/lib/stdlib/doc/src/sys.xml @@ -114,6 +114,154 @@ + + + {in,Msg} + +

+ Is produced by gen_server and gen_event + when the message Msg arrives. +

+ + {in,Msg,State} + +

+ Is produced by gen_statem + when the message Msg arrives in state State. +

+

+ For gen_statem the Msg term is + an {EventType,EventContent} tuple. +

+ + {out,Msg,To} + +

+ Is produced by gen_statem when the reply Msg + is sent back to To by returning + a {reply,To,Msg} action from the callback module. +

+

+ To is of the same type + as the first argument to gen_statem:reply/2. +

+ + + {out,Msg,To,State} + + +

+ Is produced by gen_server + when the reply Msg + is sent back to To + by returning a {reply,...} tuple + from the callback module. +

+

+ To is of the same type + as the first argument to gen_server:reply/2. +

+

+ State is the new server state. +

+ + + {noreply,State} + + +

+ Is produced by gen_server + when a {noreply,...} tuple is returned + from the callback module. +

+

+ State is the new server state. +

+ + + {continue,Continuation} + + +

+ Is produced by gen_server + when a {continue,Continuation} + tuple is returned from the callback module. +

+ + + {code_change,Event,State} + + +

+ Is produced by gen_statem + when the message Event + arrives in state State + as the first event after a code change. +

+

+ Event is + an {EventType,EventContent} tuple. +

+ + + + {postpone,Event,State,NextState} + + + +

+ Is produced by gen_statem + when the message Event + is postponed in state State. + NextState is the new state. +

+

+ Event is + an {EventType,EventContent} tuple. +

+ + + + {consume,Event,State,NextState} + + + +

+ Is produced by gen_statem + when the message Event + is consumed in state State. + NextState is the new state. +

+

+ Event is + an {EventType,EventContent} tuple. +

+ + + + {enter,State} + + + +

+ Is produced by gen_statem + when the first state State is entered. +

+ + + + {terminate,Reason,State} + + + +

+ Is produced by gen_statem + when it terminates with reason Reason + in state State. +

+ + + @@ -532,6 +680,12 @@ Get the data associated with a debug option. + +

+ get_debug/3 is deprecated since it returns + data of an internal type only useful for debugging. +

+

Gets the data associated with a debug option. Default is returned if Item is not found. Can be @@ -604,6 +758,18 @@ + + + Return the logged events in the debug structure. + +

+ Returns the logged system events in the debug structure, + that is the last argument to + handle_debug/4. +

+ + + Module:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc} diff --git a/lib/stdlib/src/otp_internal.erl b/lib/stdlib/src/otp_internal.erl index aaed13ba3a..a0fbd259e2 100644 --- a/lib/stdlib/src/otp_internal.erl +++ b/lib/stdlib/src/otp_internal.erl @@ -55,6 +55,14 @@ obsolete_1(erlang, now, 0) -> obsolete_1(calendar, local_time_to_universal_time, 1) -> {deprecated, {calendar, local_time_to_universal_time_dst, 1}}; +%% *** STDLIB added in OTP 22 *** + +obsolete_1(sys, get_debug, 3) -> + {deprecated, + "Deprecated function. " + "Incorrectly documented and in fact only for internal use. " + "Can often be replaced with sys:get_log/1."}; + %% *** STDLIB added in OTP 20 *** obsolete_1(gen_fsm, start, 3) -> diff --git a/lib/stdlib/src/sys.erl b/lib/stdlib/src/sys.erl index 09fe497d11..11513b3482 100644 --- a/lib/stdlib/src/sys.erl +++ b/lib/stdlib/src/sys.erl @@ -31,6 +31,7 @@ install/2, install/3, remove/2, remove/3]). -export([handle_system_msg/6, handle_system_msg/7, handle_debug/4, print_log/1, get_log/1, get_debug/3, debug_options/1, suspend_loop_hib/6]). +-deprecated([{get_debug,3,eventually}]). %%----------------------------------------------------------------- %% Types @@ -42,10 +43,17 @@ | {'global', term()} | {'via', module(), term()}. -type system_event() :: {'in', Msg :: _} - | {'in', Msg :: _, From :: _} + | {'in', Msg :: _, State :: _} | {'out', Msg :: _, To :: _} | {'out', Msg :: _, To :: _, State :: _} - | term(). + | {'noreply', State :: _} + | {'continue', Continuation :: _} + | {'code_change', Event :: _, State :: _} + | {'postpone', Event :: _, State :: _, NextState :: _} + | {'consume', Event :: _, State :: _, NextState :: _} + | {'enter', State :: _} + | {'terminate', Reason :: _, State :: _} + | term(). -opaque dbg_opt() :: {'trace', 'true'} | {'log', {N :: non_neg_integer(), -- cgit v1.2.3