# `SnakeBridge.SessionContext`
[🔗](https://github.com/nshkrdotcom/snakebridge/blob/v0.14.0/lib/snakebridge/session_context.ex#L1)

Provides scoped session context for Python calls.

Sessions control the lifecycle of Python object references (refs). Each session
is isolated, meaning refs from one session cannot be used in another.

## Automatic vs Explicit Sessions

By default, SnakeBridge creates an auto-session for each Elixir process. This is
convenient for most use cases where Python objects don't need to be shared.

Use explicit sessions when you need:
- Multiple processes to access the same Python objects
- Long-lived refs that outlive a single request/task
- Fine-grained control over cleanup timing

## Usage

    # Explicit session with custom ID
    SnakeBridge.SessionContext.with_session([session_id: "my-session"], fn ->
      {:ok, model} = SnakeBridge.call("sklearn.linear_model", "LinearRegression", [])
      # model ref is accessible by other processes using "my-session"
      model
    end)

    # Simple scoped session (auto-generated ID)
    SnakeBridge.SessionContext.with_session(fn ->
      # All Python calls here use the same session
      {:ok, df} = SnakeBridge.call("pandas", "DataFrame", [[1, 2, 3]])
      {:ok, mean} = SnakeBridge.method(df, "mean", [])
      mean
    end)

## Session Cleanup

Sessions are automatically cleaned up when:
- All owning processes die (auto-sessions)
- `SnakeBridge.Runtime.release_session/1` is called explicitly
- Refs exceed TTL (SessionContext default: 1 hour) or max count (default 10,000)

## Sharing Refs Across Processes

To share Python objects across processes, use the same explicit session_id:

    # Process A
    session_id = "shared--576460752303420525"
    SessionContext.with_session([session_id: session_id], fn ->
      {:ok, ref} = SnakeBridge.call("heavy_model", "load", [])
      send(process_b, {:model, session_id, ref})
    end)

    # Process B - can use the ref if it adopts the same session
    receive do
      {:model, session_id, ref} ->
        SessionContext.with_session([session_id: session_id], fn ->
          {:ok, result} = SnakeBridge.method(ref, "predict", [data])
          result
        end)
    end

## Options

- `:session_id` - Custom session ID (default: auto-generated)
- `:max_refs` - Maximum refs per session (default: 10,000)
- `:ttl_seconds` - Session time-to-live in seconds (default: 3600, i.e., 1 hour)
- `:tags` - Custom metadata for debugging

# `t`
[🔗](https://github.com/nshkrdotcom/snakebridge/blob/v0.14.0/lib/snakebridge/session_context.ex#L83)

```elixir
@type t() :: %SnakeBridge.SessionContext{
  created_at: integer(),
  max_refs: pos_integer(),
  owner_pid: pid(),
  session_id: String.t(),
  tags: map(),
  ttl_seconds: pos_integer()
}
```

# `clear_current`
[🔗](https://github.com/nshkrdotcom/snakebridge/blob/v0.14.0/lib/snakebridge/session_context.ex#L130)

```elixir
@spec clear_current() :: t() | nil
```

Clears the current session context.

# `create`
[🔗](https://github.com/nshkrdotcom/snakebridge/blob/v0.14.0/lib/snakebridge/session_context.ex#L96)

```elixir
@spec create(keyword()) :: t()
```

Creates a new session context.

# `current`
[🔗](https://github.com/nshkrdotcom/snakebridge/blob/v0.14.0/lib/snakebridge/session_context.ex#L114)

```elixir
@spec current() :: t() | nil
```

Gets the current session context from the process dictionary.

# `put_current`
[🔗](https://github.com/nshkrdotcom/snakebridge/blob/v0.14.0/lib/snakebridge/session_context.ex#L122)

```elixir
@spec put_current(t()) :: t() | nil
```

Sets the current session context in the process dictionary.

# `with_session`
[🔗](https://github.com/nshkrdotcom/snakebridge/blob/v0.14.0/lib/snakebridge/session_context.ex#L141)

```elixir
@spec with_session((-> result)) :: result when result: term()
```

Executes a function within a session context.

The session is automatically registered and will be released
when the last owner process dies.

# `with_session`
[🔗](https://github.com/nshkrdotcom/snakebridge/blob/v0.14.0/lib/snakebridge/session_context.ex#L146)

```elixir
@spec with_session(
  keyword(),
  (-> result)
) :: result
when result: term()
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*