tmux_scope (libtmux for Erlang v0.0.1)

View Source

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.

Summary

Types

The original exception class, reason and stack, retained as evidence.

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.

Functions

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.

Run work and cleanup with run/2, returning the callback value directly. Raises {scope_cleanup_failed, Failure} if cleanup fails, retaining both outcomes in 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.

Types

exception()

-type exception() :: {exception, error | exit | throw, term(), erlang:stacktrace()}.

The original exception class, reason and stack, retained as evidence.

failure()

-type failure() ::
          #{code := scope_cleanup_failed,
            primary := {ok, term()} | exception(),
            cleanup := {error, term()} | exception(),
            atom() => term()}.

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.

Functions

run(Function, Cleanup)

-spec run(fun(() -> Value), fun(() -> ok | {error, term()})) -> {ok, Value} | {error, failure()}.

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 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.

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}

run_or_error(Function, Cleanup)

-spec run_or_error(fun(() -> Value), fun(() -> ok | {error, term()})) -> Value.

Run work and cleanup with run/2, returning the callback value directly. Raises {scope_cleanup_failed, Failure} if cleanup fails, retaining both outcomes in 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.