Remove auto mode, use worker as default

- Remove auto context mode, worker is now the default
- subinterp and owngil must be explicitly requested
- This avoids C extension crashes (_decimal) on Python 3.12/3.13
- subinterp requires Python 3.12+, owngil requires Python 3.14+

Author: benoitc

src/erlang_python_sup.erl

@@ -34,7 +34,7 @@ start_link() ->
 init([]) ->
     NumContexts = application:get_env(erlang_python, num_contexts,
                                        erlang:system_info(schedulers)),
-    ContextMode = application:get_env(erlang_python, context_mode, auto),
+    ContextMode = application:get_env(erlang_python, context_mode, worker),
     NumAsyncWorkers = application:get_env(erlang_python, num_async_workers, 2),
 
     %% Default executors: 4 (benchmarked sweet spot for most workloads)

src/py.erl

@@ -1319,8 +1319,7 @@ clear_traces() ->
 
 %% @doc Start the process-per-context system with default settings.
 %%
-%% Creates one context per scheduler, using auto mode (subinterp on
-%% Python 3.12+, worker otherwise).
+%% Creates one context per scheduler using worker mode.
 %%
 %% @returns {ok, [Context]} | {error, Reason}
 -spec start_contexts() -> {ok, [pid()]} | {error, term()}.
@@ -1331,7 +1330,7 @@ start_contexts() ->
 %%
 %% Options:
 %% - `contexts' - Number of contexts to create (default: number of schedulers)
-%% - `mode' - Context mode: `auto', `subinterp', or `worker' (default: `auto')
+%% - `mode' - Context mode: `worker', `subinterp', or `owngil' (default: `worker')
 %%
 %% @param Opts Start options
 %% @returns {ok, [Context]} | {error, Reason}

src/py_context.erl

@@ -62,7 +62,7 @@
 %% Exported for py_reactor_context
 -export([extend_erlang_module_in_context/1]).
 
--type context_mode() :: auto | subinterp | worker | owngil.
+-type context_mode() :: worker | subinterp | owngil.
 -type context() :: pid().
 
 -export_type([context_mode/0, context/0]).
@@ -82,14 +82,12 @@
 %% @doc Start a new py_context process.
 %%
 %% The process creates a Python context based on the mode:
-%% - `auto' - Detect best mode (subinterp on Python 3.12+, worker otherwise)
-%% - `subinterp' - Create a sub-interpreter with shared GIL (uses pool)
 %% - `worker' - Create a thread-state worker (main interpreter namespace)
-%% - `owngil' - Create a sub-interpreter with its own GIL (true parallelism)
+%% - `subinterp' - Create a sub-interpreter with shared GIL (Python 3.12+)
+%% - `owngil' - Create a sub-interpreter with its own GIL (Python 3.14+)
 %%
 %% The `owngil' mode creates a dedicated pthread for each context, allowing
-%% true parallel Python execution. This is useful for CPU-bound workloads.
-%% Requires Python 3.12+.
+%% true parallel Python execution. Requires Python 3.14+.
 %%
 %% @param Id Unique identifier for this context
 %% @param Mode Context mode
@@ -128,13 +126,13 @@ stop(Ctx) when is_pid(Ctx) ->
 %% @doc Create a new context with options map.
 %%
 %% Options:
-%% - `mode' - Context mode (auto | subinterp | worker | owngil), default: auto
+%% - `mode' - Context mode (worker | subinterp | owngil), default: worker
 %%
 %% @param Opts Options map
 %% @returns {ok, Pid} | {error, Reason}
 -spec new(map()) -> {ok, context()} | {error, term()}.
 new(Opts) when is_map(Opts) ->
-    Mode = maps:get(mode, Opts, auto),
+    Mode = maps:get(mode, Opts, worker),
     Id = erlang:unique_integer([positive]),
     start_link(Id, Mode).
 
@@ -521,19 +519,10 @@ apply_registered_paths(Ref) ->
     end.
 
 %% @private
-%% Auto mode uses subinterpreters only on Python 3.14+ where C extension
-%% global state bugs (e.g., _decimal) are fixed. On Python 3.12/3.13,
-%% use worker mode to avoid crashes from C extensions like _decimal.
-%% Users can still explicitly use subinterp mode if needed.
-create_context(auto) ->
-    case py_nif:owngil_supported() of
-        true -> create_context(subinterp);
-        false -> create_context(worker)
-    end;
-create_context(subinterp) ->
-    py_nif:context_create(subinterp);
 create_context(worker) ->
     py_nif:context_create(worker);
+create_context(subinterp) ->
+    py_nif:context_create(subinterp);
 create_context(owngil) ->
     %% OWN_GIL mode requires Python 3.14+ due to C extension bugs in earlier versions
     case py_nif:owngil_supported() of

src/py_context_init.erl

@@ -29,7 +29,7 @@
 %%% {erlang_python, [
 %%%     {default_pool_size, 4},        % Number of contexts (default: schedulers)
 %%%     {io_pool_size, 10},            % I/O pool size (default: 10)
-%%%     {io_pool_mode, worker}         % Mode for io pool (default: auto)
+%%%     {io_pool_mode, worker}         % Mode for io pool (default: worker)
 %%% ]}.
 %%% '''
 %%% @private
@@ -49,13 +49,13 @@
 start_link(Opts) ->
     %% Start default pool
     DefaultSize = maps:get(contexts, Opts, erlang:system_info(schedulers)),
-    DefaultMode = maps:get(mode, Opts, auto),
+    DefaultMode = maps:get(mode, Opts, worker),
 
     case py_context_router:start_pool(default, DefaultSize, DefaultMode) of
         {ok, _DefaultContexts} ->
             %% Start I/O pool if configured
             IoSize = application:get_env(erlang_python, io_pool_size, 10),
-            IoMode = application:get_env(erlang_python, io_pool_mode, auto),
+            IoMode = application:get_env(erlang_python, io_pool_mode, worker),
             case py_context_router:start_pool(io, IoSize, IoMode) of
                 {ok, _IoContexts} ->
                     %% The contexts are supervised by py_context_sup

src/py_context_router.erl

@@ -124,8 +124,7 @@
 
 %% @doc Start the context router with default settings.
 %%
-%% Creates one context per scheduler, using auto mode (subinterp on
-%% Python 3.12+, worker otherwise).
+%% Creates one context per scheduler using worker mode.
 %%
 %% @returns {ok, [Context]} | {error, Reason}
 -spec start() -> {ok, [pid()]} | {error, term()}.
@@ -136,14 +135,14 @@ start() ->
 %%
 %% Options:
 %% - `contexts' - Number of contexts to create (default: number of schedulers)
-%% - `mode' - Context mode: `auto', `subinterp', or `worker' (default: `auto')
+%% - `mode' - Context mode: `worker', `subinterp', or `owngil' (default: `worker')
 %%
 %% @param Opts Start options
 %% @returns {ok, [Context]} | {error, Reason}
 -spec start(start_opts()) -> {ok, [pid()]} | {error, term()}.
 start(Opts) ->
     NumContexts = maps:get(contexts, Opts, erlang:system_info(schedulers)),
-    Mode = maps:get(mode, Opts, auto),
+    Mode = maps:get(mode, Opts, worker),
     %% Delegate to start_pool for the default pool
     start_pool(?DEFAULT_POOL, NumContexts, Mode).
 
@@ -274,13 +273,13 @@ contexts(Pool) when is_atom(Pool) ->
 %% @returns {ok, [Context]} | {error, Reason}
 -spec start_pool(pool_name(), pos_integer()) -> {ok, [pid()]} | {error, term()}.
 start_pool(Pool, Size) ->
-    start_pool(Pool, Size, auto).
+    start_pool(Pool, Size, worker).
 
 %% @doc Start a named pool with given size and mode.
 %%
 %% @param Pool Pool name (default, io, or custom)
 %% @param Size Number of contexts in the pool
-%% @param Mode Context mode (auto, subinterp, worker)
+%% @param Mode Context mode (worker, subinterp, owngil)
 %% @returns {ok, [Context]} | {error, Reason}
 -spec start_pool(pool_name(), pos_integer(), py_context:context_mode()) ->
     {ok, [pid()]} | {error, term()}.

src/py_context_sup.erl

@@ -44,7 +44,7 @@ start_link() ->
 %% @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 (auto | subinterp | worker)
+%% @param Mode Context mode (worker | subinterp | owngil)
 %% @returns {ok, Pid} | {error, Reason}
 -spec start_context(term(), py_context:context_mode()) ->
     {ok, pid()} | {error, term()}.

src/py_reactor_context.erl

@@ -79,7 +79,7 @@
 %% @doc Start a new py_reactor_context process.
 %%
 %% @param Id Unique identifier for this context
-%% @param Mode Context mode (auto, subinterp, worker)
+%% @param Mode Context mode (worker, subinterp, owngil)
 %% @returns {ok, Pid} | {error, Reason}
 -spec start_link(pos_integer(), atom()) -> {ok, pid()} | {error, term()}.
 start_link(Id, Mode) ->
@@ -95,7 +95,7 @@ start_link(Id, Mode) ->
 %%               (useful for setting up protocol factory)
 %%
 %% @param Id Unique identifier for this context
-%% @param Mode Context mode (auto, subinterp, worker)
+%% @param Mode Context mode (worker, subinterp, owngil)
 %% @param Opts Options map
 %% @returns {ok, Pid} | {error, Reason}
 -spec start_link(pos_integer(), atom(), map()) -> {ok, pid()} | {error, term()}.
@@ -180,18 +180,8 @@ handoff(Ctx, Fd, ClientInfo) when is_pid(Ctx), is_integer(Fd), is_map(ClientInfo
 init(Parent, Id, Mode, Opts) ->
     process_flag(trap_exit, true),
 
-    %% Determine mode
-    ActualMode = case Mode of
-        auto ->
-            case py_nif:subinterp_supported() of
-                true -> subinterp;
-                false -> worker
-            end;
-        _ -> Mode
-    end,
-
     %% Create Python context
-    case py_nif:context_create(ActualMode) of
+    case py_nif:context_create(Mode) of
         {ok, Ref, _InterpId} ->
             %% Set up callback handler
             py_nif:context_set_callback_handler(Ref, self()),

test/py_import_SUITE.erl

@@ -398,7 +398,7 @@ import_applied_to_new_context_test(_Config) ->
     ok = py_import:ensure_imported(json),
 
     %% Create a new context
-    {ok, Ctx} = py_context:new(#{mode => auto}),
+    {ok, Ctx} = py_context:new(#{mode => worker}),
 
     %% The json module should already be cached in the new context
     %% We can verify by calling a function from it
@@ -689,7 +689,7 @@ context_import_in_sys_modules_test(_Config) ->
     ok = py_import:clear_imports(),
 
     %% Create a context
-    {ok, Ctx} = py_context:new(#{mode => auto}),
+    {ok, Ctx} = py_context:new(#{mode => worker}),
 
     %% Call a function from a module (this imports it)
     {ok, _} = py_context:call(Ctx, textwrap, fill, [<<"Hello world this is a test">>, 10], #{}),
@@ -751,7 +751,7 @@ add_path_test(Config) ->
     ?assertEqual(1, length(Paths)),
 
     %% Create a new context to apply paths
-    {ok, Ctx} = py_context:new(#{mode => auto}),
+    {ok, Ctx} = py_context:new(#{mode => worker}),
 
     %% Import and call the sample module
     {ok, Greeting} = py_context:call(Ctx, sample_module, greet, [<<"World">>], #{}),