Skip to content

Commit

Permalink
Merge branch 'dgud/add-specs'
Browse files Browse the repository at this point in the history 
* dgud/add-specs:
  Add missing specs for et
  Add missing specs for observer
  Add missing specs for wx functions
  Add specs for missing mnesia functions
  • Loading branch information
@dgud
dgud committed Jan 19, 2024
2 parents 74a4933 + 8a16f3b commit 43d2f9b
Show file tree
Hide file tree
Showing 10 changed files with 442 additions and 44 deletions.
37 changes: 37 additions & 0 deletions lib/et/src/et.erl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
%%
Expand Down Expand Up @@ -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
Expand Down
136 changes: 119 additions & 17 deletions lib/et/src/et_collector.erl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
%%%----------------------------------------------------------------------
Expand Down Expand Up @@ -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} ->
Expand Down Expand Up @@ -266,7 +305,7 @@ start_clients(CollectorPid, []) ->
%%
%% CollectorPid = pid()
%%----------------------------------------------------------------------

-spec stop(CollectorPid::pid()) -> ok.
stop(CollectorPid) ->
call(CollectorPid, stop).

Expand Down Expand Up @@ -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}).

Expand All @@ -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}],
Expand Down Expand Up @@ -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) ->
Expand Down Expand Up @@ -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,
Expand All @@ -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) ->
Expand Down Expand Up @@ -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) ->
Expand All @@ -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}).
Expand Down Expand Up @@ -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) ->
Expand All @@ -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.
%%
Expand All @@ -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}).

Expand All @@ -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}).

Expand All @@ -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}) ->
Expand All @@ -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 ->
Expand Down Expand Up @@ -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).

Expand All @@ -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) ->
Expand Down Expand Up @@ -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) ->
Expand Down
Loading

0 comments on commit 43d2f9b

Please sign in to comment.