apps/libtmux_erlang/src/tmux_scope.erl

Source at 4d73c9795adca3e49eea74d1d2cbbbbdcbea0b6c

SHA-256: 02c1624a9618fb24022b13263e6de0ca14ca60e5ff7b773e1ecfdd742b2ea03b

-module(tmux_scope).
-moduledoc """
Run synchronous work and cleanup while preserving both outcomes.

Use `run/2` around a resource whose handle remains in the caller's scope.
Use `run_or_error/2` for nested scopes or fail-fast programs that need the
callback's value directly and raise when cleanup fails.
`tmux_server:with_server/2` and `tmux_server:with_owned/2` also acquire their
resources and add recovery handles when cleanup fails. This module owns no
process, timeout or retry policy; the supplied functions own those contracts.
""".
-export([run/2, run_or_error/2]).
-export_type([exception/0, failure/0]).

-doc "The original exception class, reason and stack, retained as evidence.".
-type exception() :: {exception, error | exit | throw, term(), erlang:stacktrace()}.
-doc """
Both outcomes when cleanup failed. primary contains the callback's ordinary
return or exception; cleanup contains its separate error or exception.
Resource-specific wrappers may add recovery handles to this map.
""".
-type failure() :: #{code := scope_cleanup_failed,
    primary := {ok, term()} | exception(),
    cleanup := {error, term()} | exception(), atom() => term()}.

-doc """
Run a callback, then attempt cleanup once, synchronously in the calling process.
This function performs only the I/O supplied by those functions. The callback
has no library duration timer. Abrupt uncatchable caller death remains subject
to each resource's existing ownership policy.

Only ok proves cleanup success. Normalize resource-specific successful replies
inside the cleanup function. With successful cleanup, return {ok, Value} or
re-raise the original callback exception with its reason and stack. A callback
returning an error tuple is an ordinary value. Cleanup failure instead returns
{error, Failure} with `t:failure/0`, preserving both outcomes. An unexpected
cleanup return is recorded as invalid_cleanup_result.

Handle an inner scope's error explicitly when nesting scopes. Otherwise it is
an ordinary outer callback value. Keep resource handles for recovery; this
function does not infer ownership or retry cleanup.

```erlang
1> tmux_scope:run(fun() -> done end, fun() -> ok end).
{ok,done}
2> tmux_scope:run(fun() -> done end, fun() -> {error, enoent} end).
{error,#{code => scope_cleanup_failed,
         primary => {ok,done},cleanup => {error,enoent}}}
3> Work = fun() -> error(build_failed) end, ok.
ok
4> {error, F} = tmux_scope:run(Work, fun() -> {error, busy} end), ok.
ok
5> {exception, error, build_failed, [_ | _]} = maps:get(primary, F), ok.
ok
6> maps:get(cleanup, F).
{error,busy}
```
""".
-spec run(fun(() -> Value), fun(() -> ok | {error, term()})) ->
    {ok, Value} | {error, failure()}.
run(Function, Cleanup) when is_function(Function, 0), is_function(Cleanup, 0) ->
    Primary = outcome(Function),
    Retired = case outcome(Cleanup) of
        {ok, ok} -> ok;
        {ok, {error, _} = Error} -> Error;
        {ok, Other} -> {error, #{code => invalid_cleanup_result, value => Other}};
        {exception, _, _, _} = Exception -> Exception
    end,
    case {Primary, Retired} of
        {{ok, Value}, ok} -> {ok, Value};
        {{exception, Class, Reason, Stack}, ok} -> erlang:raise(Class, Reason, Stack);
        _ -> {error, #{code => scope_cleanup_failed,
                       primary => Primary, cleanup => Retired}}
    end.

-doc """
Run work and cleanup with `run/2`, returning the callback value directly.
Raises {scope_cleanup_failed, Failure} if cleanup fails, retaining both
outcomes in `t:failure/0`. With successful cleanup, callback exceptions retain
their original reason and stack. Nested raising scopes propagate an inner
failure through the outer scope while still attempting outer cleanup.
""".
-spec run_or_error(fun(() -> Value), fun(() -> ok | {error, term()})) -> Value.
run_or_error(Function, Cleanup) ->
    case run(Function, Cleanup) of
        {ok, Value} -> Value;
        {error, Failure} -> erlang:error({scope_cleanup_failed, Failure}, none,
            [{error_info, #{module => tmux_error}}])
    end.

outcome(Function) ->
    try {ok, Function()}
    catch Class:Reason:Stack -> {exception, Class, Reason, Stack}
    end.