# `Snakepit.GRPCWorker`
[🔗](https://github.com/nshkrdotcom/snakepit/blob/v0.13.0/lib/snakepit/grpc_worker.ex#L1)

  A GenServer that manages gRPC connections to external processes.

  This worker can handle both traditional request/response and streaming operations
  via gRPC instead of stdin/stdout communication.

  ## Features

  - Automatic gRPC connection management
- Health check monitoring
- Streaming support with callback-based API
- Session affinity for stateful operations
- Graceful fallback to traditional workers if gRPC unavailable

## Usage

    # Start a gRPC worker
    {:ok, worker} = Snakepit.GRPCWorker.start_link(adapter: Snakepit.Adapters.GRPCPython)

    # Simple execution
    {:ok, result} = Snakepit.GRPCWorker.execute(worker, "ping", %{})

    # Streaming execution
    Snakepit.GRPCWorker.execute_stream(worker, "batch_inference", %{
      batch_items: ["img1.jpg", "img2.jpg"]
    }, fn chunk ->
      handle_chunk(chunk)
    end)

# `worker_state`

```elixir
@type worker_state() :: %{
  adapter: module(),
  connection: map() | nil,
  port: integer(),
  process_pid: integer() | nil,
  pgid: integer() | nil,
  process_group?: boolean(),
  server_port: port() | nil,
  id: String.t(),
  pool_name: atom() | pid(),
  health_check_ref: reference() | nil,
  heartbeat_monitor: pid() | nil,
  heartbeat_config: map(),
  ready_file: String.t(),
  stats: map(),
  session_id: String.t(),
  worker_config: map(),
  shutting_down: boolean(),
  rpc_request_queue: :queue.queue(map()),
  pending_rpc_calls: map(),
  pending_rpc_monitors: map()
}
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `execute`

Execute a command and return the result.

# `execute`

# `execute_in_session`

Execute a command in a specific session.

# `execute_in_session`

# `execute_stream`

Execute a streaming command with callback.

# `execute_stream`

# `get_channel`

Get the gRPC channel for direct client usage.

# `get_health`

Get worker health and statistics.

# `get_info`

Get worker information and capabilities.

# `get_session_id`

Get the session ID for this worker.

# `start_link`

Start a gRPC worker with the given adapter.

# `supervisor_shutdown_timeout`

Returns the recommended supervisor shutdown timeout.

This is `graceful_shutdown_timeout + margin` to ensure supervisors give workers
enough time to complete their terminate/2 callback (which includes graceful
Python process termination).

Use this value for:
- `shutdown:` in child_spec
- `shutdown:` in Worker.Starter
- Any other supervisor that manages GRPCWorker processes

## Example

    children = [
      %{
        id: MyWorker,
        start: {Snakepit.GRPCWorker, :start_link, [opts]},
        shutdown: Snakepit.GRPCWorker.supervisor_shutdown_timeout()
      }
    ]

---

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