File 0589-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
