Struct EggressHandle 

pub struct EggressHandle { /* private fields */ }

Handle to a running eggress service.

Provides access to bound addresses, status, metrics, reload, and shutdown. Dropping the handle cancels the shutdown token, initiating graceful shutdown.

Thread ownership

The handle owns exactly one of two mutually exclusive thread models:

Async path (start()):

• A Tokio blocking-pool thread runs the startup sequence and then blocks on run_result.join() for the lifetime of the service.
• A dedicated OS thread ("eggress-embed-rt") owns ServiceSupervisor::run().
• _runtime_task wraps the blocking task’s JoinHandle as a Tokio task.

Blocking path (start_blocking()):

• An outer OS thread ("eggress-embed-rt") handles startup, sends results through a channel, and terminates.
• An inner OS thread ("eggress-embed-run") owns ServiceSupervisor::run().
• _run_handle holds the inner thread’s JoinHandle directly.

Drop behavior

Dropping the handle cancels the shutdown token and performs a best-effort join: the blocking path joins the run thread directly; the async path creates a throwaway Tokio runtime and awaits the task with a 5-second timeout. Explicit shutdown() or shutdown_blocking() is preferred to guarantee orderly teardown.

Implementations

impl EggressHandle

pub fn bound_addresses(&self) -> BoundAddresses

Get the addresses the service is listening on.

pub fn status(&self) -> ServiceStatus

Get the current service status.

pub fn metrics_text(&self) -> Result<String, EggressError>

Render Prometheus metrics text.

pub fn reload_toml_str( &self, input: &str, ) -> Result<ReloadOutcome, EggressError>

Reload configuration from a TOML string.

Returns the outcome of the reload attempt. On success, the generation is incremented. On rejection, the old configuration remains active.

pub fn reload_toml_file( &self, path: impl AsRef<Path>, ) -> Result<ReloadOutcome, EggressError>

Reload configuration from a file.

pub fn cancel(&self)

Cancel the runtime’s shutdown token without joining the supervisor.

Best-effort teardown for finalizers that must not synchronously join the service thread: listeners and background tasks stop in the background while the handle itself may be abandoned.

pub fn cancel_and_cleanup(&mut self)

Cancel the runtime and remove the temporary config without joining it.

This is intended for finalizers that must abandon the handle after cancellation without retaining credentials in a temporary file.

pub async fn shutdown(self) -> Result<(), EggressError>

Initiate graceful shutdown.

pub fn shutdown_blocking(self) -> Result<(), EggressError>

Initiate graceful shutdown (blocking).

Trait Implementations

impl Drop for EggressHandle

fn drop(&mut self)

Cancel the shutdown token and best-effort join the supervisor.

This is a fallback for callers who do not call shutdown() explicitly. The async path creates a throwaway Tokio runtime to await the task with a 5-second timeout; if the timeout expires, the task is abandoned. Prefer explicit shutdown() or shutdown_blocking() for guaranteed orderly teardown.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.