File 0235-sasl-Add-specs-to-all-public-functions.patch of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 0235-sasl-Add-specs-to-all-public-functions.patch of Package erlang

From 196e7cd6a9827eae2b3fa1ada2024733a9736e1c Mon Sep 17 00:00:00 2001
From: Lukas Larsson <lukas@erlang.org>
Date: Thu, 4 Jan 2024 15:49:41 +0100
Subject: [PATCH 5/6] sasl: Add specs to all public functions

---
 lib/sasl/src/alarm_handler.erl   |   7 ++
 lib/sasl/src/rb.erl              |  45 ++++++++++-
 lib/sasl/src/release_handler.erl | 126 +++++++++++++++++++++++++++++++
 lib/sasl/src/systools.erl        |  49 +++++++++++-
 4 files changed, 224 insertions(+), 3 deletions(-)

diff --git a/lib/sasl/src/alarm_handler.erl b/lib/sasl/src/alarm_handler.erl
index 77863f0f8f..d197b4e54d 100644
--- a/lib/sasl/src/alarm_handler.erl
+++ b/lib/sasl/src/alarm_handler.erl
@@ -32,6 +32,9 @@
 	 handle_event/2, handle_call/2, handle_info/2,
 	 terminate/2]).
 
+-type alarm_id() :: term().
+-type alarm() :: {alarm_id(), AlarmDescription :: term()}.
+
 start_link() ->
     case gen_event:start_link({local, alarm_handler}) of
 	{ok, Pid} ->
@@ -45,6 +48,8 @@ start_link() ->
 %% Args: Alarm ::= {AlarmId, term()}
 %%       where AlarmId ::= term()
 %%-----------------------------------------------------------------
+-spec set_alarm(alarm()) -> term().
+
 set_alarm(Alarm) ->
     gen_event:notify(alarm_handler, {set_alarm, Alarm}).
 
@@ -52,6 +57,7 @@ set_alarm(Alarm) ->
 %% Func: clear_alarm/1
 %% Args: AlarmId ::= term()
 %%-----------------------------------------------------------------
+-spec clear_alarm(alarm_id()) -> term().
 clear_alarm(AlarmId) ->
     gen_event:notify(alarm_handler, {clear_alarm, AlarmId}).
 
@@ -59,6 +65,7 @@ clear_alarm(AlarmId) ->
 %% Func: get_alarms/0
 %% Returns: [{AlarmId, AlarmDesc}]
 %%-----------------------------------------------------------------
+-spec get_alarms() -> [alarm()].
 get_alarms() ->
     gen_event:call(alarm_handler, alarm_handler, get_alarms).
 
diff --git a/lib/sasl/src/rb.erl b/lib/sasl/src/rb.erl
index c8fb4b16a3..bed041d660 100644
--- a/lib/sasl/src/rb.erl
+++ b/lib/sasl/src/rb.erl
@@ -33,6 +33,15 @@
 -export([init/1, terminate/2, handle_call/3,
 	 handle_cast/2, handle_info/2, code_change/3]).
 
+-type type() :: error | error_report | info_msg | info_report |
+                warning_msg | warning_report | crash_report |
+                supervisor_report | progress | all.
+-type option() :: {start_log, FileName :: string() | atom() | pid()} |
+                  {max, MaxNoOfReports :: integer() | all} |
+                  {report_dir, DirString :: string()} |
+                  {type, ReportType :: type() | [type()] | all } |
+                  {abort_on_error, boolean()}.
+
 %%%-----------------------------------------------------------------
 %%% Report Browser Tool.
 %%% Formats Error reports written by log_mf_h
@@ -44,7 +53,10 @@
 %% Interface functions.
 %% For available options; see print_options().
 %%-----------------------------------------------------------------
+-spec start() -> term().
 start() -> start([]).
+-spec start(Options) -> term() when
+      Options :: [option()].
 start(Options) ->
     supervisor:start_child(sasl_sup, 
 			   {rb_server, {rb, start_link, [Options]},
@@ -53,40 +65,69 @@ start(Options) ->
 start_link(Options) ->
     gen_server:start_link({local, rb_server}, rb, Options, []).
 
+-spec stop() -> term().
 stop() -> 
     supervisor:terminate_child(sasl_sup, rb_server).
 
+-spec rescan() -> term().
 rescan() -> rescan([]).
+-spec rescan(Options) -> term() when Options :: [option()].
 rescan(Options) ->
     call({rescan, Options}).
 
+-spec list() -> term().
 list() -> list(all).
+-spec list(Type :: type()) -> term().
 list(Type) -> call({list, Type}).
 
+-spec log_list() -> term().
 log_list() -> log_list(all).
+-spec log_list(Type :: type()) -> term().
 log_list(Type) -> call({log_list, Type}).
 
-show() -> 
+-spec show() -> term().
+show() ->
     call(show).
 
-show(Number) when is_integer(Number) -> 
+-spec show(Report) -> term() when Report :: integer() | type().
+show(Number) when is_integer(Number) ->
     call({show_number, Number});
 show(Type) when is_atom(Type) ->
     call({show_type, Type}).
 
+-type regexp() :: string() | {string(), Options :: [re:options()]} |
+                  re:mp() | {re:mp(), Options :: [re:compile_options()]}.
+
+-spec grep(RegExp :: regexp()) -> term().
 grep(RegExp) -> call({grep, RegExp}).
 
+-type filter() :: {Key :: term(), Value :: term()} |
+                  {Key :: term(), Value :: term(), no} |
+                  {Key :: term(), RegExp :: regexp(), re} |
+                  {Key :: term(), RegExp :: regexp(), re, no}.
+
+-spec filter(Filters) -> term() when
+      Filters :: [filter()].
 filter(Filters) when is_list(Filters) ->
     call({filter, Filters}).
 
+-spec filter(Filters, Dates) -> term() when
+      Filters :: [filter()],
+      Dates :: {DateFrom, DateTo} | {DateFrom, from} | {DateTo, to},
+      DateFrom :: calendar:datetime(),
+      DateTo :: calendar:datetime().
 filter(Filters, FDates) when is_list(Filters) andalso is_tuple(FDates) ->
     call({filter, {Filters, FDates}}).
 
+-spec start_log(FileName) -> term() when FileName :: string() | atom() | pid().
 start_log(FileName) -> call({start_log, FileName}).
 
+-spec stop_log() -> term().
 stop_log() -> call(stop_log).
 
+-spec h() -> term().
 h() -> help().
+-spec help() -> term().
 help() ->
     io:format("~nReport Browser Tool - usage~n"),
     io:format("===========================~n"),
diff --git a/lib/sasl/src/release_handler.erl b/lib/sasl/src/release_handler.erl
index 7635b1ef78..91e07fec35 100644
--- a/lib/sasl/src/release_handler.erl
+++ b/lib/sasl/src/release_handler.erl
@@ -161,6 +161,9 @@ start_link() ->
 %%                   {file_missing, FileName} |  (in the tar package)
 %%                   exit_reason()
 %%-----------------------------------------------------------------
+-spec unpack_release(Name) -> {ok, Vsn} | {error, Reason} when Name :: string(),
+   Vsn :: string(),
+   Reason :: client_node | term().
 unpack_release(ReleaseName) ->
     call({unpack_release, ReleaseName}).
     
@@ -179,9 +182,19 @@ unpack_release(ReleaseName) ->
 %%                   {no_such_from_vsn, Vsn} |
 %%                   exit_reason()
 %%-----------------------------------------------------------------
+-spec check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason} when Vsn :: string(),
+   OtherVsn :: string(),
+   Descr :: term(),
+   Reason :: term().
 check_install_release(Vsn) ->
     check_install_release(Vsn, []).
 
+-spec check_install_release(Vsn,Opts) -> {ok, OtherVsn, Descr} | {error, Reason} when Vsn :: string(),
+   OtherVsn :: string(),
+   Opts :: [Opt],
+   Opt :: purge,
+   Descr :: term(),
+   Reason :: term().
 check_install_release(Vsn, Opts) ->
     case check_check_install_options(Opts, false) of
 	{ok,Purge} ->
@@ -213,10 +226,35 @@ check_check_install_options([],Purge) ->
 %%                   {illegal_option, Opt}} |
 %%                   exit_reason()
 %%-----------------------------------------------------------------
+-spec install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason} when
+      Vsn :: string(),
+      OtherVsn :: string(),
+      Descr :: term(),
+      Reason :: {already_installed, Vsn} |
+                {change_appl_data, term()} |
+                {missing_base_app, OtherVsn, App} |
+                {could_not_create_hybrid_boot, term()} |
+                term(),
+      App :: atom().
 install_release(Vsn) ->
     call({install_release, Vsn, restart, []}).
 
 
+-spec install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {continue_after_restart, OtherVsn, Descr} | {error, Reason} when
+      Vsn :: string(),
+      OtherVsn :: string(),
+      Opt :: {error_action, Action} | {code_change_timeout, Timeout} | {suspend_timeout, Timeout} | {update_paths, Bool},
+      Action :: restart | reboot,
+      Timeout :: default | infinity | pos_integer(),
+      Bool :: boolean(),
+      Descr :: term(),
+      Reason :: {illegal_option, Opt} |
+                {already_installed, Vsn} |
+                {change_appl_data, term()} |
+                {missing_base_app, OtherVsn, App} |
+                {could_not_create_hybrid_boot, term()} |
+                term(),
+      App :: atom().
 install_release(Vsn, Opt) ->
     case check_install_options(Opt, restart, []) of
 	{ok, ErrorAction, InstallOpt} ->
@@ -275,12 +313,23 @@ new_emulator_upgrade(Vsn, Opts) ->
 %%                   {no_such_release, Vsn} |
 %%                   exit_reason()
 %%-----------------------------------------------------------------
+-spec make_permanent(Vsn) -> ok | {error, Reason}
+                        when
+                            Vsn :: string(),
+                            Reason ::
+                                {bad_status, Status :: term()} | term().
 make_permanent(Vsn) ->
     call({make_permanent, Vsn}).
 
 %%-----------------------------------------------------------------
 %% Purpose: Reboots the system from an old release.
 %%-----------------------------------------------------------------
+-spec reboot_old_release(Vsn) -> ok | {error, Reason}
+                            when
+                                Vsn :: string(),
+                                Reason ::
+                                    {bad_status, Status :: term()} |
+                                    term().
 reboot_old_release(Vsn) ->
     call({reboot_old_release, Vsn}).
 
@@ -291,6 +340,8 @@ reboot_old_release(Vsn) ->
 %% Returns: ok | {error, Reason}
 %%          Reason = {permanent, Vsn} |
 %%-----------------------------------------------------------------
+-spec remove_release(Vsn) -> ok | {error, Reason} when Vsn :: string(),
+   Reason :: {permanent, Vsn} | client_node | term().
 remove_release(Vsn) ->
     call({remove_release, Vsn}).
 
@@ -310,6 +361,12 @@ remove_release(Vsn) ->
 %%          them).
 %% Returns: ok | {error, Reason}
 %%-----------------------------------------------------------------
+-spec set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason} when RelFile :: string(),
+   AppDirs :: [{App, Vsn, Dir}],
+    App :: atom(),
+    Vsn :: string(),
+   Dir :: string(),
+   Reason :: term().
 set_unpacked(RelFile, LibDirs) ->
     call({set_unpacked, RelFile, LibDirs}).
 
@@ -320,6 +377,8 @@ set_unpacked(RelFile, LibDirs) ->
 %%          This function won't delete any files at all.
 %% Returns: ok | {error, Reason}
 %%-----------------------------------------------------------------
+-spec set_removed(Vsn) -> ok | {error, Reason} when Vsn :: string(),
+   Reason :: {permanent, Vsn} | term().
 set_removed(Vsn) ->
     call({set_removed, Vsn}).
 
@@ -331,6 +390,9 @@ set_removed(Vsn) ->
 %%          is called.
 %% Returns: ok | {error, {no_such_release, Vsn}}
 %%-----------------------------------------------------------------
+-spec install_file(Vsn, File) -> ok | {error, Reason} when Vsn :: string(),
+   File :: string(),
+   Reason :: term().
 install_file(Vsn, File) when is_list(File) ->
     call({install_file, File, Vsn}).
 
@@ -338,6 +400,10 @@ install_file(Vsn, File) when is_list(File) ->
 %% Returns: [{Name, Vsn, [LibName], Status}]
 %%          Status = unpacked | current | permanent | old
 %%-----------------------------------------------------------------
+-spec which_releases() -> [{Name, Vsn, Apps, Status}] when Name :: string(),
+   Vsn :: string(),
+   Apps :: [AppVsn :: string()],
+   Status :: unpacked | current | permanent | old.
 which_releases() ->
     call(which_releases).
 
@@ -345,6 +411,10 @@ which_releases() ->
 %% Returns: [{Name, Vsn, [LibName], Status}]
 %%          Status = unpacked | current | permanent | old
 %%-----------------------------------------------------------------
+-spec which_releases(Status) -> [{Name, Vsn, Apps, Status}] when Name :: string(),
+   Vsn :: string(),
+   Apps :: [AppVsn :: string()],
+   Status :: unpacked | current | permanent | old.
 which_releases(Status) ->
     Releases = which_releases(),
     get_releases_with_status(Releases, Status, []).
@@ -384,8 +454,24 @@ create_RELEASES([Root, RelFile | LibDirs]) ->
 create_RELEASES(Root, RelFile) ->
     create_RELEASES(Root, filename:join(Root, "releases"), RelFile, []).
 
+-spec create_RELEASES(RelDir, RelFile, AppDirs) -> ok | {error, Reason} when
+      RelDir :: string(),
+      RelFile :: string(),
+      AppDirs :: [{App, Vsn, Dir}],
+      App :: atom(),
+      Vsn :: string(),
+      Dir :: string(),
+      Reason :: term().
 create_RELEASES(RelDir, RelFile, LibDirs) ->
     create_RELEASES("", RelDir, RelFile, LibDirs).
+-spec create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason} when Root :: string(),
+   RelDir :: string(),
+   RelFile :: string(),
+   AppDirs :: [{App, Vsn, Dir}],
+    App :: atom(),
+    Vsn :: string(),
+   Dir :: string(),
+   Reason :: term().
 create_RELEASES(Root, RelDir, RelFile, LibDirs) ->
     case catch check_rel(Root, RelFile, LibDirs, false) of
 	{error, Reason } ->
@@ -405,6 +491,11 @@ create_RELEASES(Root, RelDir, RelFile, LibDirs) ->
 %%         located under Dir/ebin
 %% Purpose: Upgrade to the version in Dir according to an appup file
 %%-----------------------------------------------------------------
+-spec upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason} when App :: atom(),
+   Dir :: string(),
+   Unpurged :: [Module],
+    Module :: atom(),
+   Reason :: term().
 upgrade_app(App, NewDir1) ->
     NewDir = root_dir_relative_path(NewDir1),
     try upgrade_script(App, NewDir) of
@@ -428,6 +519,12 @@ upgrade_app(App, NewDir1) ->
 %% Purpose: Downgrade from the version in Dir according to an appup file
 %%          located in the ebin dir of the _current_ version
 %%-----------------------------------------------------------------
+-spec downgrade_app(App, Dir) ->  {ok, Unpurged} | restart_emulator | {error, Reason} when
+      App :: atom(),
+      Dir :: string(),
+      Unpurged :: [Module],
+      Module :: atom(),
+      Reason :: term().
 downgrade_app(App, OldDir) ->
     case string:lexemes(filename:basename(OldDir), "-") of
 	[_AppS, OldVsn] ->
@@ -435,6 +532,12 @@ downgrade_app(App, OldDir) ->
 	_ ->
 	    {error, {unknown_version, App}}
     end.
+-spec downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason} when App :: atom(),
+   Dir :: string(),
+   OldVsn :: string(),
+   Unpurged :: [Module],
+    Module :: atom(),
+   Reason :: term().
 downgrade_app(App, OldVsn, OldDir) ->
     try downgrade_script(App, OldVsn, OldDir) of
 	{ok, Script} ->
@@ -444,6 +547,12 @@ downgrade_app(App, OldVsn, OldDir) ->
 	    {error, Reason}
     end.
 
+-spec upgrade_script(App, Dir) -> {ok, NewVsn, Script}
+                        when
+                            App :: atom(),
+                            Dir :: string(),
+                            NewVsn :: string(),
+                            Script :: Instructions :: term().
 upgrade_script(App, NewDir1) ->
     NewDir = root_dir_relative_path(NewDir1),
     OldVsn = ensure_running(App),
@@ -459,6 +568,12 @@ upgrade_script(App, NewDir1) ->
 	    throw(Reason)
     end.
 
+-spec downgrade_script(App, OldVsn, Dir) -> {ok, Script}
+                          when
+                              App :: atom(),
+                              OldVsn :: string(),
+                              Dir :: string(),
+                              Script :: Instructions :: term().
 downgrade_script(App, OldVsn, OldDir) ->
     NewVsn = ensure_running(App),
     NewDir = code:lib_dir(App),
@@ -473,6 +588,17 @@ downgrade_script(App, OldVsn, OldDir) ->
 	    throw(Reason)
     end.
 
+-spec eval_appup_script(App, ToVsn, ToDir, Script :: term()) ->
+                           {ok, Unpurged} |
+                           restart_emulator |
+                           {error, Reason}
+                           when
+                               App :: atom(),
+                               ToVsn :: string(),
+                               ToDir :: string(),
+                               Unpurged :: [Module],
+                               Module :: atom(),
+                               Reason :: term().
 eval_appup_script(App, ToVsn, ToDir, Script) ->
     EnvBefore = application_controller:prep_config_change(),
     AppSpecL = read_appspec(App, ToDir),
diff --git a/lib/sasl/src/systools.erl b/lib/sasl/src/systools.erl
index 889cf924a3..2fe7264832 100644
--- a/lib/sasl/src/systools.erl
+++ b/lib/sasl/src/systools.erl
@@ -47,10 +47,29 @@
 %% local generates a script with references to the directories there
 %% the applications are found.
 %%-----------------------------------------------------------------
+-spec make_script(Name) -> Result when
+      Name :: string(),
+      Result :: ok | error | {ok,Module,Warnings} | {error,Module,Error},
+      Module :: atom(),
+      Warnings :: term(),
+      Error :: term().
 make_script([RelName|Opts]) when is_atom(RelName) ->
-    make_script([RelName], Opts);
+    systools_make:make_script([RelName], Opts);
 make_script(RelName) -> make_script(RelName, []).
 
+-spec make_script(Name, [Opt]) -> Result when
+      Name :: string(),
+      Opt :: src_tests | {path,[Dir]} | local | {variables,[Var]} | exref | {exref,[App]} |
+             silent | {outdir,Dir} | no_dot_erlang | no_warn_sasl | warnings_as_errors | {script_name, Name},
+      Dir :: string(),
+      Var :: {VarName,Prefix},
+      VarName :: string(),
+      Prefix :: string(),
+      App :: atom(),
+      Result :: ok | error | {ok,Module,Warnings} | {error,Module,Error},
+      Module :: atom(),
+      Warnings :: term(),
+      Error :: term().
 make_script(RelName, Opt) ->
     systools_make:make_script(RelName, Opt).
 
@@ -94,6 +113,7 @@ make_tar(RelName, Opt) ->
 %%-----------------------------------------------------------------
 %% Create a binary form of a boot script.
 %%-----------------------------------------------------------------
+-spec script2boot(File) -> ok | error when File :: string().
 script2boot(File) ->
     case systools_lib:file_term2binary(File ++ ".script", File ++ ".boot") of
 	{error,Error} ->
@@ -119,8 +139,35 @@ script2boot(File, Output0, _Opt) ->
 %% search path, silent suppresses error message printing on console,
 %% noexec suppresses writing the output "relup" file
 %%-----------------------------------------------------------------
+-spec make_relup(Name, UpFrom, DownTo) -> Result when Name :: string(),
+   UpFrom :: [Name | {Name,Descr}],
+   DownTo :: [Name | {Name,Descr}],
+    Descr :: term(),
+   Result :: ok | error | {ok,Relup :: term(),Module,Warnings} | {error,Module,Error},
+    Module :: atom(),
+    Warnings :: term(),
+   Error :: term().
 make_relup(ReleaseName, UpNameList, DownNameList) ->
     systools_relup:mk_relup(ReleaseName, UpNameList, DownNameList, []).
+-spec make_relup(Name, UpFrom, DownTo, [Opt]) -> Result
+                    when
+                        Name :: string(),
+                        UpFrom :: [Name | {Name, Descr}],
+                        DownTo :: [Name | {Name, Descr}],
+                        Descr :: term(),
+                        Opt ::
+                            {path, [Dir]} |
+                            restart_emulator | silent | noexec |
+                            {outdir, Dir} |
+                            warnings_as_errors,
+                        Dir :: string(),
+                        Result ::
+                            ok | error |
+                            {ok, Relup :: term(), Module, Warnings} |
+                            {error, Module, Error},
+                        Module :: atom(),
+                        Warnings :: term(),
+                        Error :: term().
 make_relup(ReleaseName, UpNameList, DownNameList, Opts) ->
     systools_relup:mk_relup(ReleaseName, UpNameList, DownNameList, Opts).
 
-- 
2.35.3

Places

File 0235-sasl-Add-specs-to-all-public-functions.patch of Package erlang

Places