%% Copyright 2026 Benoit Chesneau

%%

%% Licensed under the Apache License, Version 2.0 (the "License");

%% you may not use this file except in compliance with the License.

%% You may obtain a copy of the License at

%%

%% http://www.apache.org/licenses/LICENSE-2.0

%%

%% Unless required by applicable law or agreed to in writing, software

%% distributed under the License is distributed on an "AS IS" BASIS,

%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

%% See the License for the specific language governing permissions and

%% limitations under the License.

%%% @doc Supervisor for py_context processes.

%%%

%%% This is a simple_one_for_one supervisor that manages py_context

%%% processes. New contexts are started via start_context/2.

%%%

%%% @end

-module(py_context_sup).

-behaviour(supervisor).

-export([

start_link/0,

start_context/2,

stop_context/1,

which_contexts/0

]).

%% Supervisor callbacks

-export([init/1]).

%% ============================================================================

%% API

%% ============================================================================

%% @doc Start the supervisor.

-spec start_link() -> {ok, pid()} | {error, term()}.

start_link() ->

supervisor:start_link({local, ?MODULE}, ?MODULE, []).

%% @doc Start a new py_context under this supervisor.

%%

%% @param Id Unique identifier for the context (integer or {Pool, N} tuple)

%% @param Mode Context mode (worker | subinterp | owngil)

%% @returns {ok, Pid} | {error, Reason}

-spec start_context(term(), py_context:context_mode()) ->

{ok, pid()} | {error, term()}.

start_context(Id, Mode) ->

supervisor:start_child(?MODULE, [Id, Mode]).

%% @doc Stop a context by its PID.

-spec stop_context(pid()) -> ok | {error, term()}.

stop_context(Pid) when is_pid(Pid) ->

case supervisor:terminate_child(?MODULE, Pid) of

ok -> ok;

{error, not_found} -> ok;

Error -> Error

end.

%% @doc List all running context PIDs.

-spec which_contexts() -> [pid()].

which_contexts() ->

[Pid || {_, Pid, _, _} <- supervisor:which_children(?MODULE),

is_pid(Pid)].

%% ============================================================================

%% Supervisor callbacks

%% ============================================================================

%% @private

init([]) ->

SupFlags = #{

strategy => simple_one_for_one,

intensity => 5,

period => 10

},

ChildSpec = #{

id => py_context,

start => {py_context, start_link, []},

restart => temporary,

shutdown => 5000,

type => worker,

modules => [py_context]

},

{ok, {SupFlags, [ChildSpec]}}.