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
impl Engine
Sourcepub fn new(config: EngineConfig) -> Result<Self, Error>
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.
Sourcepub fn builder() -> EngineBuilder
pub fn builder() -> EngineBuilder
Starts a configuration builder in the convenient spawned mode.
Sourcepub fn get(&self, url: impl Into<String>) -> EngineRequestBuilder
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()?;Sourcepub fn post(&self, url: impl Into<String>) -> EngineRequestBuilder
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()?;Sourcepub fn resolver(&self) -> Resolver
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()?;Sourcepub fn tcp_connector(&self) -> TcpConnector
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()?;Sourcepub fn metrics(&self) -> EngineMetrics
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.
Sourcepub fn cancel_all(&self)
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.
Sourcepub fn drive(&mut self, deadline: Instant) -> Result<DriveStatus, Error>
pub fn drive(&mut self, deadline: Instant) -> Result<DriveStatus, Error>
Performs one host-driven Engine pass up to deadline.
Sourcepub fn drive_until<T: WaiterTarget>(
&mut self,
pending: T,
) -> Result<T::Output, Error>
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.
Sourcepub fn shutdown(self) -> Result<(), ShutdownError>
pub fn shutdown(self) -> Result<(), ShutdownError>
Irreversibly stops network work and waits for callback dispatch to drain.
Sourcepub fn shutdown_for(
self,
duration: Duration,
) -> Result<ShutdownOutcome, ShutdownError>
pub fn shutdown_for( self, duration: Duration, ) -> Result<ShutdownOutcome, ShutdownError>
Irreversibly stops network work, then waits up to duration for callback dispatch.