Struct TCPClient 

pub struct TCPClient { /* private fields */ }

Available on (crate features clients or servers) and crate feature clients only.

A generic TCP client that can handle connections to multiple TCP Servers.

This client allows for connecting to many servers all at once, or creating a real “TCP Server” that allows people to connect to it (for SDIO). Because of the weirdness of our SDIO client, and the hooks for scientists this client ends up accepting a lot of parameters, see the module documentation for more information.

Implementations

impl TCPClient

pub fn new( service_name: &'static str, guard: impl Into<NagleGuard>, nagle_hooks: (Option<&'static dyn PreNagleFnTy>, Option<&'static dyn PostNagleFnTy>), trace_io_during_debug: bool, ) -> Self

Construct a new TCP Client.

This TCP client will by default not connect to anything/listen to any ports. Instead you will have to call TCPClient::connect, and TCPClient::bind manually to setup connections.

Remember the default TCPClient::send, and TCPClient::receive will only return responses to the “primary” connection (whichever connection has the oldest connection). That is unless you call TCPClient::set_primary_stream.

pub const fn set_cat_dev_slowdown(&mut self, slowdown: Option<Duration>)

Set the slowdown to before sending bytes from this server.

pub const fn should_keep_all_responses(&mut self)

Mark that this client should keep all responses (e.g. those from the non active upstreams).

pub const fn set_keep_all_responses(&mut self, keep: bool)

Set directly whether or not this client should keep all responses.

pub fn set_primary_stream(&mut self, stream_id: u64)

Set the primary stream to receive responses from.

pub const fn chunk_output_at_size(&self) -> Option<usize>

pub const fn set_chunk_output_at_size(&mut self, new_size: Option<usize>)

pub const fn slowloris_timeout(&self) -> Duration

pub const fn set_slowloris_timeout(&mut self, slowloris_timeout: Duration)

pub const fn on_stream_begin( &self, ) -> Option<&UnderlyingOnStreamBeginService<()>>

pub fn set_raw_on_stream_begin( &mut self, on_start: Option<UnderlyingOnStreamBeginService<()>>, ) -> Result<(), CommonNetAPIError>

Set a hook to run when a stream has been created.

This is what happens when a new machine connects. So it may also be refered to as “on connect”. This assumes you’re assigning a service that already exists and is in the raw storage type, you may want to look into Self::set_on_stream_begin, or Self::set_on_stream_begin_service.

Errors

If the stream beginning hook has already been registered. If you’re looking to perform multiple actions at once, look into layer-ing.

pub fn set_on_stream_begin<HandlerTy, HandlerParamsTy>( &mut self, handler: HandlerTy, ) -> Result<(), CommonNetAPIError>

where HandlerParamsTy: Send + 'static, HandlerTy: OnRequestStreamBeginHandler<HandlerParamsTy, ()> + Clone + Send + 'static,

Set a function hook to run when a stream has been created.

This is what happens when a new machine connects. So it may also be refered to as “on connect”. This assumes you’re assigning a function to on stream begin otherwise use Self::set_raw_on_stream_begin, or Self::set_on_stream_begin_service.

Errors

If the stream beginning hook has already been registered. If you’re looking to perform multiple actions at once, look into layer-ing.

pub fn set_on_stream_begin_service<ServiceTy>( &mut self, service_ty: ServiceTy, ) -> Result<(), CommonNetAPIError>

where ServiceTy: Clone + Send + Service<RequestStreamEvent<()>, Response = bool, Error = CatBridgeError> + 'static, ServiceTy::Future: Send + 'static,

Set a function hook to run when a stream has been created.

This is what happens when a new machine connects. So it may also be refered to as “on connect”. This assumes you’re assigning a Service to on stream begin otherwise use Self::set_raw_on_stream_begin, or Self::set_on_stream_begin.

Errors

If the stream beginning hook has already been registered. If you’re looking to perform multiple actions at once, look into layer-ing.

pub fn layer_on_stream_begin<LayerTy, ServiceTy>( &mut self, layer: LayerTy, ) -> Result<(), CommonNetAPIError>

where LayerTy: Layer<UnderlyingOnStreamBeginService<()>, Service = ServiceTy>, ServiceTy: Service<RequestStreamEvent<()>, Response = bool, Error = CatBridgeError> + Clone + Send + 'static, <LayerTy::Service as Service<RequestStreamEvent<()>>>::Future: Send + 'static,

Add a layer to the service to process when a stream begins, or a new connection is created.

Errors

If there is no on stream begin handler that is currently active.

pub const fn on_stream_end(&self) -> Option<&UnderlyingOnStreamEndService<()>>

pub fn set_raw_on_stream_end( &mut self, on_end: Option<UnderlyingOnStreamEndService<()>>, ) -> Result<(), CommonNetAPIError>

Set a hook to run when a stream is being destroyed.

This is what happens when a machine disconnects. So it may also be refered to as “on disconnect”. This assumes you’re assigning a service that already exists and is in the raw storage type, you may want to look into Self::set_on_stream_end, or Self::set_on_stream_end_service.

Errors

If the stream ending hook has already been registered. If you’re looking to perform multiple actions at once, look into layer-ing.

pub fn set_on_stream_end<HandlerTy, HandlerParamsTy>( &mut self, handler: HandlerTy, ) -> Result<(), CommonNetAPIError>

where HandlerParamsTy: Send + 'static, HandlerTy: OnRequestStreamEndHandler<HandlerParamsTy, ()> + Clone + Send + 'static,

Set a function hook to run when a stream is being destroyed.

This is what happens when a machine disconnects. So it may also be refered to as “on disconnect”. This assumes you’re assigning a function to on stream end otherwise use Self::set_raw_on_stream_end, or Self::set_on_stream_end_service.

Errors

If the stream ending hook has already been registered. If you’re looking to perform multiple actions at once, look into layer-ing.

pub fn set_on_stream_end_service<ServiceTy>( &mut self, service_ty: ServiceTy, ) -> Result<(), CommonNetAPIError>

where ServiceTy: Clone + Send + Service<RequestStreamEvent<()>, Response = (), Error = CatBridgeError> + 'static, ServiceTy::Future: Send + 'static,

Set a function hook to run when a stream is being destroyed.

This is what happens when a machine disconnects. So it may also be refered to as “on disconnect”. This assumes you’re assigning a Service to on stream end otherwise use Self::set_raw_on_stream_end, or Self::set_on_stream_end.

Errors

If the stream beginning hook has already been registered. If you’re looking to perform multiple actions at once, look into layer-ing.

pub fn layer_on_stream_end<LayerTy, ServiceTy>( &mut self, layer: LayerTy, ) -> Result<(), CommonNetAPIError>

where LayerTy: Layer<UnderlyingOnStreamEndService<()>, Service = ServiceTy>, ServiceTy: Service<RequestStreamEvent<()>, Response = (), Error = CatBridgeError> + Clone + Send + 'static, <LayerTy::Service as Service<RequestStreamEvent<()>>>::Future: Send + 'static,

Add a layer to the service to process when a stream ends, or a new connection is destroyed.

Errors

If there is no on stream end handler that is currently active.

pub async fn bind<AddrTy: ToSocketAddrs>( &self, address: AddrTy, ) -> Result<(), CatBridgeError>

“Bind” this client to listen on a specific address.

I know this is unusual for a “TCP Client”, binding is for servers? I mean who exactly would be binding to an address as a client? However, certain protocols used for PCFS & the like are “reverse”. E.g. the pc the server connects to the “client” the MION listening on a server.

TCP Servers also have a “connect” method for this very reason.

Errors

If we cannot spin up a server to listen on this host. This doesn’t mean someone is connected, just that we’re listening. You may want to use: TCPClient::wait_for_connection.

pub async fn wait_for_connection(&self)

This will be an async function that will not return until at least one server has connected to our client.

pub async fn connect<AddrTy: ToSocketAddrs>( &self, address: AddrTy, ) -> Result<u64, CatBridgeError>

Connect to a new server as a raw TCP client.

This method will return the stream id to use for later requests to specific streams.

Errors

If we can’t connect to the remote TCP Server completing the three way handshake, or if we the stream begin handler returns an error/failure of some kind.

pub async fn send<ErrorTy: Debug, BodyTy: TryInto<Bytes, Error = ErrorTy>>( &self, body: BodyTy, wait_for_response_timeout: Option<Duration>, ) -> Result<(u64, RequestID, Option<Response>), NetworkError>

Send a series of bytes over the wire potentially receiving responses back.

This will always only take the response from the ‘primary server’. Even if other servers respond first or at all. It will always be the primary response.

If you want to truly access all the client streams at once use Self::broadcast_send to send to all, and receive all their responses back.

This will return the stream that was used as the ‘primary’, the request-id to wait for a response later or otherwise, and the optional response if we waited for one.

Errors

This function will error if we run into any issues writing or reading the bytes from the stream in a timely manner.

pub async fn send_with_read_amount<ErrorTy: Debug, BodyTy: TryInto<Bytes, Error = ErrorTy>>( &self, body: BodyTy, wait_for_response_timeout: Option<Duration>, explicit_read_amount: usize, ) -> Result<(u64, RequestID, Option<Response>), NetworkError>

Send a series of bytes over the wire potentially receiving responses back.

This will always only take the response from the ‘primary server’. Even if other servers respond first or at all. It will always be the primary response.

If you want to truly access all the client streams at once use Self::broadcast_send to send to all, and receive all their responses back.

This will return the stream that was used as the ‘primary’, the request-id to wait for a response later or otherwise, and the optional response if we waited for one.

Errors

This function will error if we run into any issues writing or reading the bytes from the stream in a timely manner.

pub async fn broadcast_send<ErrorTy: Debug, BodyTy: TryInto<Bytes, Error = ErrorTy>>( &self, body: BodyTy, wait_for_response_timeout: Duration, ) -> Result<FnvHashMap<u64, Option<Response>>, CatBridgeError>

The equivalent of [send], but get all the responses back out of this client.

Errors

If we timeout, or run into any sort of error sending or receiving content from a stream.

pub async fn receive( &self, wait_until: Duration, ) -> Result<Option<Response>, NetworkError>

Receive a packet from the primary stream.

Used for out-of-band receiving of packets that don’t have an associated Self::send call.

Errors

If we timeout, or have another series of failures reading bytes from our stream.

pub async fn take_all_response_for_request_id( &self, request_id: &RequestID, wait_for: Duration, ) -> FnvHashMap<u64, Option<Response>>

Get all the responses for a particular request id.

In order to keep memory from ballooning up, and the fact that TCP is ordered. This API also expects to be called in an ‘ordered’ way. Previous requests that do not match the request id will be dropped.

Trait Implementations

impl Debug for TCPClient

fn fmt(&self, fmt: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl Structable for TCPClient

fn definition(&self) -> StructDef<'_>

Returns the struct’s definition.

impl Valuable for TCPClient

fn as_value(&self) -> Value<'_>

Converts self into a Value instance.

fn visit(&self, visitor: &mut dyn Visit)

Calls the relevant method on Visit to extract data from self.

fn visit_slice(slice: &[Self], visit: &mut dyn Visit)

where Self: Sized,

Calls Visit::visit_primitive_slice() with self.