Skip to main content

Engine

Struct Engine 

Source
pub struct Engine { /* private fields */ }
Expand description

Unique owner of one lifecycle, resource, and bulk-cancellation domain.

Engine is Send, deliberately non-cloneable, and deliberately not Sync in the initial contract. Engine::client and Engine::tcp_connector issue cheap cloneable capability tickets; the default-on resolver feature also provides Engine::resolver. Tickets neither own nor extend Engine lifetime. Explicit shutdown consumes the Engine owner.

ⓘ
use nbreq::Engine;
fn require_sync<T: Sync>() {}
require_sync::<Engine>();

Implementations§

Source§

impl Engine

Source

pub fn new(config: EngineConfig) -> Result<Self, Error>

Creates one independent Engine from backend-neutral configuration.

The default build uses NBReq’s native HTTP implementation in spawned or manual mode. A build without the native feature returns ErrorKind::Unsupported.

Source

pub fn builder() -> EngineBuilder

Starts a configuration builder in the convenient spawned mode.

Source

pub fn run_mode(&self) -> RunMode

Returns whether this Engine is spawned or driven manually.

Source

pub fn client(&self) -> Client

Issues a cheap cloneable command handle for this Engine.

Source

pub fn get(&self, url: impl Into<String>) -> EngineRequestBuilder

Starts a simple Engine-bound GET request.

The returned builder uses this Engine’s existing Client, backend, connection pool, limits, and lifecycle. It does not create or retain another Engine.

use nbreq::{Engine, EngineConfig};

let engine = Engine::new(EngineConfig::spawned())?;
let response = engine
    .get("https://example.com/")
    .header("Accept", "text/plain")
    .call()?;
assert!(response.status() >= 100);
engine.shutdown()?;
Source

pub fn post(&self, url: impl Into<String>) -> EngineRequestBuilder

Starts a simple Engine-bound POST request.

The buffered body may be supplied with EngineRequestBuilder::send, or an empty POST may be executed with EngineRequestBuilder::call or EngineRequestBuilder::send_empty.

use nbreq::{Engine, EngineConfig};

let engine = Engine::new(EngineConfig::spawned())?;
let response = engine
    .post("https://example.com/items")
    .header("Content-Type", "application/json")
    .send(br#"{"name":"thing"}"#)?;
assert!(response.status() >= 100);
engine.shutdown()?;
Source

pub fn resolver(&self) -> Resolver

Issues a cheap cloneable hostname-resolution handle for this Engine.

The ticket is always issued. Native Engines that own the private DNS service accept public resolutions. Engines without that service reject new work with ErrorKind::Unsupported before identity allocation, admission, callback reservation, or command queuing.

use nbreq::{Engine, EngineConfig, ResolveRequest};

let engine = Engine::new(EngineConfig::spawned())?;
let resolver = engine.resolver();
let request = ResolveRequest::hostname("example.com")
    .max_results(8)
    .build()?;
let _pending = resolver.submit(request);
engine.shutdown()?;
Source

pub fn tcp_connector(&self) -> TcpConnector

Issues a cheap cloneable cleartext TCP handle for this Engine.

The ticket is always issued. Native Engines accept literal-address connects on their existing reactor owner. Hostname connects and Engines without that owner currently fail ErrorKind::Unsupported before identity allocation or admission.

use nbreq::{Engine, EngineConfig, TcpConnectRequest};

let engine = Engine::new(EngineConfig::spawned())?;
let tcp = engine.tcp_connector();
let request = TcpConnectRequest::hostname("example.com", 1234)
    .connect_timeout(std::time::Duration::from_secs(5))
    .build()?;
let _pending = tcp.submit(request);
engine.shutdown()?;
Source

pub fn metrics(&self) -> EngineMetrics

Returns a nonblocking, payload-free snapshot of this Engine’s lifetime activity.

Fields are loaded independently and may be cross-field inconsistent while work is moving.

Source

pub fn cancel_all(&self)

Cancels HTTP requests, public resolutions when compiled, pending connects, and live standalone TCP accepted before the cancellation barrier while keeping the Engine alive.

Source

pub fn drive(&mut self, deadline: Instant) -> Result<DriveStatus, Error>

Performs one host-driven Engine pass up to deadline.

Source

pub fn drive_until<T: WaiterTarget>( &mut self, pending: T, ) -> Result<T::Output, Error>

Drives a manual Engine until pending reaches its canonical terminal outcome.

The existing HTTP call shape is unchanged: passing a PendingRequest still returns Completion. Public resolve and connect waiters return their own terminal types through the same method.

Source

pub fn shutdown(self) -> Result<(), ShutdownError>

Irreversibly stops network work and waits for callback dispatch to drain.

Source

pub fn shutdown_for( self, duration: Duration, ) -> Result<ShutdownOutcome, ShutdownError>

Irreversibly stops network work, then waits up to duration for callback dispatch.

Trait Implementations§

Source§

impl Drop for Engine

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

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. Read more

Auto Trait Implementations§

§

impl !RefUnwindSafe for Engine

§

impl !Sync for Engine

§

impl !UnwindSafe for Engine

§

impl Freeze for Engine

§

impl Send for Engine

§

impl Unpin for Engine

§

impl UnsafeUnpin for Engine

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.