-module(aws@internal@actor_lifecycle).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch, inline]).
-define(FILEPATH, "src/aws/internal/actor_lifecycle.gleam").
-export([shutdown_via_stop/2, shutdown_via_stop_sync/3]).

-if(?OTP_RELEASE >= 27).
-define(MODULEDOC(Str), -moduledoc(Str)).
-define(DOC(Str), -doc(Str)).
-else.
-define(MODULEDOC(Str), -compile([])).
-define(DOC(Str), -compile([])).
-endif.

?MODULEDOC(
    " Generic teardown helpers for actors that follow the SDK's\n"
    " \"polite stop message\" convention. Used by `credentials_cache` and\n"
    " `retry/rate_limiter` — both opaque types wrap a `Subject` whose\n"
    " message variant set includes a `Stop` constructor that triggers\n"
    " `actor.stop()` next dispatch.\n"
    "\n"
    " Lives in a separate module so the same fire-and-forget + monitor-\n"
    " based synchronous teardown lands in exactly one place. Adding a\n"
    " third long-lived actor later (a request-rate limiter, an event-\n"
    " stream demuxer) reuses these directly.\n"
).

-file("src/aws/internal/actor_lifecycle.gleam", 18).
?DOC(
    " Fire-and-forget teardown: send the supplied `Stop` message and\n"
    " return immediately. The actor exits on its next dispatch. Safe to\n"
    " call against a dead actor — Erlang silently drops sends to a\n"
    " terminated Pid.\n"
).
-spec shutdown_via_stop(gleam@erlang@process:subject(KUM), KUM) -> nil.
shutdown_via_stop(Subject, Stop_message) ->
    gleam@erlang@process:send(Subject, Stop_message).

-file("src/aws/internal/actor_lifecycle.gleam", 29).
?DOC(
    " Synchronous teardown: monitor the owning Pid, send `Stop`, then\n"
    " wait for the `DOWN` signal up to `timeout_ms`. Returns `Ok(Nil)`\n"
    " on clean exit (already-dead actor short-circuits here too — the\n"
    " `subject_owner` lookup fails fast). Returns `Error(Nil)` only on\n"
    " real timeout — i.e. the actor is alive but didn't exit within the\n"
    " window. The monitor is demonitored on the timeout path so the\n"
    " caller's mailbox doesn't accumulate stray `DOWN` messages.\n"
).
-spec shutdown_via_stop_sync(gleam@erlang@process:subject(KUO), KUO, integer()) -> {ok,
        nil} |
    {error, nil}.
shutdown_via_stop_sync(Subject, Stop_message, Timeout_ms) ->
    case gleam@erlang@process:subject_owner(Subject) of
        {error, _} ->
            {ok, nil};

        {ok, Pid} ->
            Monitor = gleam@erlang@process:monitor(Pid),
            gleam@erlang@process:send(Subject, Stop_message),
            Selector = begin
                _pipe = gleam_erlang_ffi:new_selector(),
                gleam@erlang@process:select_specific_monitor(
                    _pipe,
                    Monitor,
                    fun(_) -> nil end
                )
            end,
            case gleam_erlang_ffi:select(Selector, Timeout_ms) of
                {ok, nil} ->
                    {ok, nil};

                {error, nil} ->
                    gleam@erlang@process:demonitor_process(Monitor),
                    {error, nil}
            end
    end.