File 0964-Add-missing-specs-for-et.patch of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 0964-Add-missing-specs-for-et.patch of Package erlang (Revision 0c95bdcb413813ad538c04f6e313b575)

Currently displaying revision 0c95bdcb413813ad538c04f6e313b575 , Show latest

From 8a16f3b50fd39d36e5e59214e0a399b983ad0a63 Mon Sep 17 00:00:00 2001
From: Dan Gudmundsson <dgud@erlang.org>
Date: Fri, 5 Jan 2024 15:30:52 +0100
Subject: [PATCH 4/4] Add missing specs for et

---
 lib/et/src/et.erl           |  37 ++++++++++
 lib/et/src/et_collector.erl | 136 +++++++++++++++++++++++++++++++-----
 lib/et/src/et_selector.erl  |  26 ++++++-
 lib/et/src/et_viewer.erl    |  39 +++++++++--
 4 files changed, 214 insertions(+), 24 deletions(-)

diff --git a/lib/et/src/et.erl b/lib/et/src/et.erl
index b951439ef3..220a2c884b 100644
--- a/lib/et/src/et.erl
+++ b/lib/et/src/et.erl
@@ -89,6 +89,10 @@
 	 trace_me/5, phone_home/5, report_event/5
         ]).
 
+
+-type actor() :: term().
+-type level() :: 0..100.
+
 %%----------------------------------------------------------------------
 %% Reports an event, such as a message
 %%
@@ -126,26 +130,59 @@
 %% Other events (termed actions) may be undirected and only have one actor.
 %%----------------------------------------------------------------------
 
+-spec trace_me(DetailLevel, FromTo, Label, Contents) -> hopefully_traced when
+      DetailLevel :: level(),
+      FromTo :: actor(),
+      Label :: atom() | string() | term(),
+      Contents :: [{Key::term(), Value::term()}] | term().
 trace_me(DetailLevel, FromTo, Label, Contents)
   when is_integer(DetailLevel) ->
     ?MODULE:trace_me(DetailLevel, FromTo, FromTo, Label, Contents).
 
+-spec trace_me(DetailLevel, From, To, Label, Contents) -> hopefully_traced when
+      DetailLevel :: level(),
+      From :: actor(),
+      To :: actor(),
+      Label :: atom() | string() | term(),
+      Contents :: [{Key::term(), Value::term()}] | term().
 trace_me(DetailLevel, _From, _To, _Label, _Contents)
   when is_integer(DetailLevel) ->
     hopefully_traced.
 
+-spec phone_home(DetailLevel, FromTo, Label, Contents) -> hopefully_traced when
+      DetailLevel :: level(),
+      FromTo :: actor(),
+      Label :: atom() | string() | term(),
+      Contents :: [{Key::term(), Value::term()}] | term().
 phone_home(DetailLevel, FromTo, Label, Contents) ->
     %% N.B External call
     ?MODULE:trace_me(DetailLevel, FromTo, FromTo, Label, Contents).
 
+-spec phone_home(DetailLevel, From, To, Label, Contents) -> hopefully_traced when
+      DetailLevel :: level(),
+      From :: actor(),
+      To :: actor(),
+      Label :: atom() | string() | term(),
+      Contents :: [{Key::term(), Value::term()}] | term().
 phone_home(DetailLevel, From, To, Label, Contents) ->
     %% N.B External call
     ?MODULE:trace_me(DetailLevel, From, To, Label, Contents).
 
+-spec report_event(DetailLevel, FromTo, Label, Contents) -> hopefully_traced when
+      DetailLevel :: level(),
+      FromTo :: actor(),
+      Label :: atom() | string() | term(),
+      Contents :: [{Key::term(), Value::term()}] | term().
 report_event(DetailLevel, FromTo, Label, Contents) ->
     %% N.B External call
     ?MODULE:trace_me(DetailLevel, FromTo, FromTo, Label, Contents).
 
+-spec report_event(DetailLevel, From, To, Label, Contents) -> hopefully_traced when
+      DetailLevel :: level(),
+      From :: actor(),
+      To :: actor(),
+      Label :: atom() | string() | term(),
+      Contents :: [{Key::term(), Value::term()}] | term().
 report_event(DetailLevel, From, To, Label, Contents)
   when is_integer(DetailLevel) ->
     %% N.B External call
diff --git a/lib/et/src/et_collector.erl b/lib/et/src/et_collector.erl
index 835bb380b8..058e7f473f 100644
--- a/lib/et/src/et_collector.erl
+++ b/lib/et/src/et_collector.erl
@@ -87,6 +87,44 @@
 -record(trace_ts, {trace_ts, event_ts}).
 -record(event_ts, {event_ts, trace_ts}).
 
+-type event() :: #event{}.
+-type table_handle() :: #table_handle{}.
+-type event_ts() :: #event_ts{}.
+-type trace_ts() :: #trace_ts{}.
+
+-type collector_fun() :: trace_filter_fun() | event_filter_fun().
+
+-type trace_filter_fun() :: fun((TraceData::tuple()) -> boolean() | {true, event()}).
+-type event_filter_fun() :: fun((Event::event()) -> boolean() | {true, event()}).
+
+-type dbg_match_spec() :: [tuple()].  %% See dbg match specs
+-type dbg_trace_type() :: ip | file | follow_file.   %% See dbg:trace_client
+-type dbg_trace_parameters() :: file:filename() | integer() | {string(), integer()}. %% See dbg:trace_client
+
+-type ets_match_object_pattern() :: term(). %% See ets:match_object()
+
+-type level() :: 0..100.
+
+-type option()::
+        {parent_pid, pid() | undefined} |
+        {event_order, trace_ts | event_ts} |
+        {dict_insert, {filter, all}, collector_fun()} |
+        {dict_insert, {filter, EventFilterName::atom()}, event_filter_fun()} |
+        {dict_insert, {subscriber, pid()}, Val::term()} |
+        {dict_insert, Key::term(), Val::term()} |
+        {dict_delete, Key::term()} |
+        {trace_client, {event_file, file:filename()} |
+         {dbg_trace_type(), dbg_trace_parameters()}} |
+        {trace_global, boolean()} |
+        {trace_pattern, {module() | undefined, Level::level() | dbg_match_spec()} |
+         undefined} |
+        {trace_port, integer()} |
+        {trace_max_queue, integer()}.
+
+-type actor() :: term().
+
+-export_type([option/0]).
+
 %%%----------------------------------------------------------------------
 %%% Client side
 %%%----------------------------------------------------------------------
@@ -163,7 +201,8 @@
 %% CollectorPid = pid()
 %% Reason = term()
 %%----------------------------------------------------------------------
-
+-spec start_link(Options) -> {ok, Pid::pid()} | {error, term()} when
+      Options :: [option()].
 start_link(Options) ->
     case parse_opt(Options, default_state(), [], []) of
 	{ok, S, Dict2, Clients} ->
@@ -266,7 +305,7 @@ start_clients(CollectorPid, []) ->
 %%
 %% CollectorPid = pid()
 %%----------------------------------------------------------------------
-
+-spec stop(CollectorPid::pid()) -> ok.
 stop(CollectorPid) ->
     call(CollectorPid, stop).
 
@@ -295,7 +334,10 @@ stop(CollectorPid) ->
 %% 
 %% The options defaults to existing, write and keep.
 %%----------------------------------------------------------------------
-
+-spec save_event_file(CollectorPid, FileName, [Option]) -> ok | {error, term()} when
+      CollectorPid :: pid(),
+      FileName :: file:filename(),
+      Option :: existing | write | append | keep | clear.
 save_event_file(CollectorPid, FileName, Options) ->
     call(CollectorPid, {save_event_file, FileName, Options}).
 
@@ -309,7 +351,10 @@ save_event_file(CollectorPid, FileName, Options) ->
 %% BadBytes = integer(X) where X >= 0
 %% Reason = term()
 %%----------------------------------------------------------------------
-
+-spec load_event_file(CollectorPid, FileName) ->{ok, BadBytes} when
+      CollectorPid :: pid(),
+      FileName :: file:filename(),
+      BadBytes :: pos_integer().
 load_event_file(CollectorPid, FileName) ->
     Fd = make_ref(),
     Args = [{file, FileName}, {name, Fd}, {repair, true}, {mode, read_only}],
@@ -359,6 +404,11 @@ do_load_event_file(Fun, Fd, Cont, Acc, FileName, BadBytes) ->
 %% Returns: {ok, Continuation} | exit(Reason)
 %%----------------------------------------------------------------------
 
+-spec report(Handle, TraceOrEvent) -> {ok, Continuation} when
+      Handle :: table_handle() | CollectorPid::pid(),
+      TraceOrEvent :: event() | TraceData | end_of_trace,
+      TraceData :: tuple(),
+      Continuation :: table_handle().
 report(CollectorPid, TraceOrEvent) when is_pid(CollectorPid) ->
     case get_table_handle(CollectorPid) of
         {ok, TH} when is_record(TH, table_handle) ->
@@ -411,9 +461,24 @@ report(TH, TraceOrEvent) when is_record(TH, table_handle) ->
 report(_, Bad) ->
     exit({bad_event, Bad}).
 
+-spec report_event(CollectorPid, DetailLevel, FromTo, Label, Contents) -> {ok, Continuation} when
+      CollectorPid :: pid(),
+      DetailLevel :: level(),
+      FromTo :: actor(),
+      Label  :: term(),
+      Contents :: [{Key::term(), Value::term()}] | term(),
+      Continuation :: table_handle().
 report_event(CollectorPid, DetailLevel, FromTo, Label, Contents) ->
     report_event(CollectorPid, DetailLevel, FromTo, FromTo, Label, Contents).
 
+-spec report_event(CollectorPid, DetailLevel, From, To, Label, Contents) -> {ok, Continuation} when
+      CollectorPid :: pid(),
+      DetailLevel :: level(),
+      From :: actor(),
+      To :: actor(),
+      Label  :: term(),
+      Contents :: [{Key::term(), Value::term()}] | term(),
+      Continuation :: table_handle().
 report_event(CollectorPid, DetailLevel, From, To, Label, Contents)
   when is_integer(DetailLevel), 
        DetailLevel >= ?detail_level_min,
@@ -438,6 +503,10 @@ report_event(CollectorPid, DetailLevel, From, To, Label, Contents)
 %% Key = record(event_ts) | record(trace_ts)
 %%----------------------------------------------------------------------
 
+-spec make_key(Handle, Stuff) -> Key when
+      Handle :: table_handle() | trace_ts | event_ts,
+      Stuff :: event() | Key,
+      Key :: event_ts() | trace_ts().
 make_key(TH, Stuff) when is_record(TH, table_handle) ->
     make_key(TH#table_handle.event_order, Stuff);
 make_key(trace_ts, Stuff) ->
@@ -490,7 +559,7 @@ get_table_handle(CollectorPid) when is_pid(CollectorPid) ->
 %% CollectorPid = pid()
 %% Reason = term()
 %%----------------------------------------------------------------------
-
+-spec get_global_pid() -> CollectorPid :: pid().
 get_global_pid() ->
     case global:whereis_name(?MODULE) of
         CollectorPid when is_pid(CollectorPid) ->
@@ -512,7 +581,10 @@ get_global_pid() ->
 %% detail_level() = min | max | integer(X) when X =< 0, X >= 100
 %% TracePattern = {report_module(), dbg_match_spec_match_spec()}
 %%----------------------------------------------------------------------
-
+-spec change_pattern(CollectorPid, RawPattern) -> {old_pattern, TracePattern} when
+      CollectorPid :: pid(),
+      RawPattern :: {module(), min | max | level()},
+      TracePattern :: [{[term()] | '_' | atom(), [term()], [term()]}].
 change_pattern(CollectorPid, RawPattern) ->
     Pattern = et_selector:make_pattern(RawPattern),
     call(CollectorPid, {change_pattern, Pattern}).
@@ -542,7 +614,11 @@ change_pattern(CollectorPid, RawPattern) ->
 %% Key = term()
 %% Val = term()
 %%----------------------------------------------------------------------
-
+-spec dict_insert(CollectorPid, What, Value) -> ok when
+      CollectorPid :: pid(),
+      What :: {filter, atom()} | {subscriber, pid()} | Key,
+      Key  :: term(),
+      Value :: collector_fun() | term().
 dict_insert(CollectorPid, Key = {filter, Name}, Fun) ->
     if
 	is_atom(Name), is_function(Fun) ->
@@ -569,14 +645,14 @@ dict_insert(CollectorPid, Key, Val) ->
 %% Key = term()
 %% Val = term()
 %%----------------------------------------------------------------------
-
+-spec dict_lookup(CollectorPid::pid(), Key::term()) -> [Val::term()].
 dict_lookup(CollectorPid, Key) ->
     call(CollectorPid, {dict_lookup, Key}).
 
 %%----------------------------------------------------------------------
-%% Ddict_delete(CollectorPid, Key) -> ok
+%% dict_delete(CollectorPid, Key) -> ok
 %%
-%% elete a dictionary entry
+%% Delete a dictionary entry
 %% and send a {et, {dict_delete, Key}} tuple
 %% to all registered subscribers.
 %%
@@ -591,7 +667,7 @@ dict_lookup(CollectorPid, Key) ->
 %% SubscriberPid = pid()
 %% Key = term()
 %%----------------------------------------------------------------------
-
+-spec dict_delete(CollectorPid::pid(), Key::term()) -> ok.
 dict_delete(CollectorPid, Key) ->
     call(CollectorPid, {dict_delete, Key}).
 
@@ -608,7 +684,10 @@ dict_delete(CollectorPid, Key) ->
 %% key() = term()
 %% val() = term()
 %%----------------------------------------------------------------------
-
+-spec dict_match(CollectorPid::pid(), {KeyPattern, ValPattern}) -> [Match] when
+      KeyPattern :: ets_match_object_pattern(),
+      ValPattern :: ets_match_object_pattern(),
+      Match :: {Key::term(), Val::term()}.
 dict_match(CollectorPid, Pattern)  ->
     call(CollectorPid, {dict_match, Pattern}).
 
@@ -620,7 +699,7 @@ dict_match(CollectorPid, Pattern)  ->
 %% CollectorPid = pid()
 %% Msg = term()
 %%----------------------------------------------------------------------
-
+-spec multicast(CollectorPid :: pid(), Msg::term()) -> ok.
 multicast(_CollectorPid, Msg = {dict_insert, _Key, _Val}) ->
     exit({badarg, Msg});
 multicast(_CollectorPid, Msg = {dict_delete, _Key}) ->
@@ -638,7 +717,10 @@ multicast(CollectorPid, Msg) ->
 %% Parameters = dbg_trace_client_parameters()
 %% Pid        = dbg_trace_client_pid()
 %%----------------------------------------------------------------------
-
+-spec start_trace_client(CollectorPid, Type, Parameter) -> file_loaded | {trace_client_pid, pid()} when
+      CollectorPid :: pid(),
+      Type :: event_file | dbg_trace_type(),
+      Parameter :: dbg_trace_parameters().
 start_trace_client(CollectorPid, Type, FileName) when Type =:= event_file ->
     load_event_file(CollectorPid, FileName);
 start_trace_client(CollectorPid, Type, FileName) when Type =:= file -> 
@@ -697,7 +779,15 @@ monitor_trace_port(CollectorPid, Parameters) ->
 %% 
 %% Short for iterate/5.
 %%----------------------------------------------------------------------
-
+-spec iterate(Handle, Prev, Limit) -> NewAcc when
+      Handle :: CollectorPid | table_handle(),
+      CollectorPid :: pid(),
+      Prev :: first | last | term(),
+      Limit :: Done | Forward | Backward,
+      Done :: 0,
+      Forward :: pos_integer(),
+      Backward :: neg_integer(),
+      NewAcc :: term().
 iterate(Handle, Prev, Limit) ->
     iterate(Handle, Prev, Limit, undefined, Prev).
 
@@ -720,7 +810,17 @@ iterate(Handle, Prev, Limit) ->
 %% Fun = fun(Event, Acc) -> NewAcc
 %% Acc = NewAcc = term()
 %%----------------------------------------------------------------------
-
+-spec iterate(Handle, Prev, Limit, Fun, Acc) -> NewAcc when
+      Handle :: CollectorPid | table_handle(),
+      CollectorPid :: pid(),
+      Prev :: first | last | term(),
+      Limit :: Done | Forward | Backward,
+      Done :: 0,
+      Forward :: pos_integer() | 'infinity',
+      Backward :: neg_integer() | '-infinity',
+      Fun :: fun((event(), Acc) -> NewAcc) | undefined,
+      Acc :: term(),
+      NewAcc :: term().
 iterate(_, _, Limit, _, Acc) when Limit =:= 0 ->
     Acc;
 iterate(CollectorPid, Prev, Limit, Fun, Acc) when is_pid(CollectorPid) ->
@@ -858,7 +958,9 @@ incr(Val, Incr) ->
 %% collector_pid() = pid()
 %% table_handle() = record(table_handle)
 %%----------------------------------------------------------------------
-
+-spec clear_table(Handle) -> ok when
+      Handle :: CollectorPid | table_handle(),
+      CollectorPid :: pid().
 clear_table(CollectorPid) when is_pid(CollectorPid) ->
     call(CollectorPid, clear_table);
 clear_table(TH) when is_record(TH, table_handle) ->
diff --git a/lib/et/src/et_selector.erl b/lib/et/src/et_selector.erl
index 18a7e66b1d..e83088d823 100644
--- a/lib/et/src/et_selector.erl
+++ b/lib/et/src/et_selector.erl
@@ -31,6 +31,10 @@
 
 -include("../include/et.hrl").
 
+-type event() :: #event{}.
+
+-type level() :: 0..100.
+
 %%----------------------------------------------------------------------
 %% make_pattern(RawPattern) -> TracePattern
 %%
@@ -46,7 +50,9 @@
 %%   max       - maximum level of tracing  (all calls to trace_me/4,5)
 %%   integer() - explicit detail level of tracing
 %%----------------------------------------------------------------------
-
+-spec make_pattern({Mod::module(), RawPattern}) -> {Mod::module(), TracePattern} when
+      RawPattern :: level(),
+      TracePattern :: [{[term()] | '_' | atom(), [term()], [term()]}].
 make_pattern(undefined) ->
     {undefined, undefined};
 make_pattern({Mod, Pattern}) when is_atom(Mod) ->
@@ -93,7 +99,11 @@ make_pattern({Mod, Pattern}) when is_atom(Mod) ->
 %% Other match specs activates tracing of calls to trace_me/4,5
 %% accordingly with erlang:trace_pattern/2.
 %%----------------------------------------------------------------------
-
+-spec change_pattern({Mod::module(), Pattern}) -> ok when
+      Pattern :: DetailLevel | TracePattern | EmptyTracePattern,
+      DetailLevel :: level(),
+      TracePattern :: [{[term()] | '_' | atom(), [term()], [term()]}],
+      EmptyTracePattern :: [].
 change_pattern({Mod, Pattern}) when is_atom(Mod) ->
     MFA = {Mod, trace_me, 5},
     case Pattern of
@@ -176,7 +186,17 @@ error_to_exit({ok, _Res}) ->
 %%   false         - means that the trace data is uninteresting and
 %%                   should be dropped
 %%----------------------------------------------------------------------
-
+-spec parse_event(Mod, ValidTraceData) -> boolean | {true, event()} when
+      Mod :: module(),
+      ValidTraceData :: ErlangTraceData | event(),
+      ErlangTraceData ::
+        {trace, pid(), atom(), term()} |
+        {trace, pid(), atom(), term(), term()} |
+        {trace_ts, pid(), atom(), term(), TS::{integer(), integer(), integer()}} |
+        {trace_ts, pid(), atom(), term(), term(), TS::{integer(), integer(), integer()}} |
+        {seq_trace, atom(), term()} |
+        {seq_trace, atom(), term(), TS::{integer(), integer(), integer()}} |
+        {drop, integer()}.
 parse_event(_Mod, E) when is_record(E, event) ->
     true;
 parse_event(Mod, Trace) ->
diff --git a/lib/et/src/et_viewer.erl b/lib/et/src/et_viewer.erl
index 3928764c7f..d3e2c2f409 100644
--- a/lib/et/src/et_viewer.erl
+++ b/lib/et/src/et_viewer.erl
@@ -40,6 +40,24 @@
 
 -define(unknown, "UNKNOWN").
 
+-type actors() :: [term()].
+-type first_key() :: term().
+-type option() ::
+        {title, string()} |
+        {detail_level, 0..100} |
+        {is_suspended, boolean()} |
+        {scale, integer()} |
+        {width, integer()} |
+        {height, integer()}|
+        {collector_pid, pid() | undefined} |
+        {active_filter, atom()} |
+        {max_events, integer() | undefined} |
+        {max_actors, integer() | undefined} |
+        {actors, actors()} |
+        {first_event, first_key()} |
+        {hide_unknown, boolean()} |
+        {hide_actions, boolean()} |
+        {display_mode, all | {search_actors, forward | reverse, first_key(), actors()}}.
 
 %%%----------------------------------------------------------------------
 %%% Client side
@@ -55,7 +73,7 @@
 %% ViewerPid = pid()
 %% Reason = term()
 %%----------------------------------------------------------------------
-
+-spec file(FileName::file:filename()) -> {ok, pid()} | {error, term()}.
 file(FileName) ->
     start_link([{trace_client, {file, FileName}}], default).
 
@@ -70,18 +88,25 @@ file(FileName) ->
 %% processes are unlinked from the calling process.
 %%----------------------------------------------------------------------
 
+-spec start() -> {ok, pid()} | {error, term()}.
 start() ->
     start([{trace_global, true}], default).
 
 %%----------------------------------------------------------------------
 %% start(Options) -> {ok, ViewerPid} | {error, Reason}
 %%----------------------------------------------------------------------
-
+-spec start(GUIorOptions) -> {ok, Viewer::pid()} | {error, term()} when
+      GUIorOptions :: wx | default | Options,
+      Options :: [option() | et_collector:option()].
 start(GUI) when GUI =:= wx; GUI =:= default ->
     start_link([{trace_global, true}], GUI);
 start(Options) ->
     start_link([{parent_pid, undefined} | Options], default).
 
+-spec start(Options, GUI) -> {ok, Viewer::pid()} | {error, term()} when
+      GUI :: wx | default,
+      Options :: [option() | et_collector:option()].
+
 start(Options, GUI) ->
     start_link([{parent_pid, undefined} | Options], GUI).
 
@@ -139,12 +164,17 @@ start(Options, GUI) ->
 %% A filter_fun() takes an event record as sole argument
 %% and returns false | true | {true, NewEvent}.
 %%----------------------------------------------------------------------
-
+-spec start_link(GUIorOptions) -> {ok, Viewer::pid()} | {error, term()} when
+      GUIorOptions :: wx | default | Options,
+      Options :: [option() | et_collector:option()].
 start_link(GUI) when GUI =:= wx; GUI =:= default ->
     start_link([{trace_global, true}], GUI);
 start_link(Options) ->
     start_link(Options, default).
 
+-spec start_link(Options, GUI) -> {ok, Viewer::pid()} | {error, term()} when
+      GUI :: wx | default,
+      Options :: [option() | et_collector:option()].
 start_link(Options, GUI) -> 
     case GUI of
 	wx ->
@@ -155,6 +185,7 @@ start_link(Options, GUI) ->
 
 which_gui() -> wx.
 
+-spec get_collector_pid(ViewerPid::pid()) -> pid().
 get_collector_pid(ViewerPid) ->
     call(ViewerPid, get_collector_pid).
 
@@ -165,7 +196,7 @@ get_collector_pid(ViewerPid) ->
 %% 
 %% ViewerPid = pid()
 %%----------------------------------------------------------------------
-
+-spec stop(ViewerPid::pid()) -> ok.
 stop(ViewerPid) ->
     call(ViewerPid, stop).
 
-- 
2.35.3

Places

File 0964-Add-missing-specs-for-et.patch of Package erlang (Revision 0c95bdcb413813ad538c04f6e313b575)

Places