Struct remote_trait_object::Context

pub struct Context { /* fields omitted */ }

One end of a remote-trait-object connection.

If you establish a remote-trait-object connection, there must be two ends and each will be provided as a Context to each user on both sides.

A context holds multiple things to function as a remote-trait-object connection end. Since the connection is symmetric, it manages both server and client toward the other end. It also manages a registry that contains all exported services. The server will look up the registry to find a target object for handling an incoming method invocation.

Note that remote-trait-object is a point-to-point connection protocol. Exporting & importing a service are always performed on a specific connection, which is toward the other side, or another instance of Context.

If you created an instance of this, that means you have a connection that has been successfully established once, but is not guaranteed to be alive. If the other end (or the other Context) is closed, most operations performed on Context will just cause an error.

Implementations

impl Context

pub fn new<S: TransportSend + 'static, R: TransportRecv + 'static>(
    config: Config,
    transport_send: S,
    transport_recv: R
) -> Self

Creates a new context without any initial services.

If you decide to use this, you have to exchange raw HandleToExchange at least once using a secondary transportation means. It is really rarely needed, so please consider introducing an initializing service as an initial service, to avoid any raw exchange.

Please see with_initial_service() for a general explanation of creation of Context.

pub fn with_initial_service_export<S: TransportSend + 'static, R: TransportRecv + 'static, A: ?Sized + Service>(
    config: Config,
    transport_send: S,
    transport_recv: R,
    initial_service: ServiceToExport<A>
) -> Self

Creates a new context only exporting a service, but importing nothing.

The other end's context must be initialized with with_initial_service_import(). Please see with_initial_service() for a general explanation of creation of Context.

pub fn with_initial_service_import<S: TransportSend + 'static, R: TransportRecv + 'static, B: ?Sized + Service>(
    config: Config,
    transport_send: S,
    transport_recv: R
) -> (Self, ServiceToImport<B>)

Creates a new context only importing a service, but exporting nothing.

The other end's context must be initialized with with_initial_service_export(). Please see with_initial_service() for a general explanation of creation of Context.

pub fn with_initial_service<S: TransportSend + 'static, R: TransportRecv + 'static, A: ?Sized + Service, B: ?Sized + Service>(
    config: Config,
    transport_send: S,
    transport_recv: R,
    initial_service: ServiceToExport<A>
) -> (Self, ServiceToImport<B>)

Creates a new context exchanging two services, one for export and one for import.

It takes initial_service and registers in it, and passes a HandleToExchange internally. (export). Also it receives a HandleToExchange from the other side, and makes it into a proxy object. (import)

The other end's context must be initialized with with_initial_service() as well, and such processes will be symmetric for both.

pub fn clear_service_registry(&mut self)

Clears all service objects in its registry.

The most usual way of deleting a service object is dropping its proxy object on the client side, and letting it request a delete to the exporter side. However, in some cases (especially while you're trying to shut down the connection) it is useful to clear all exported service objects by the exporter side itself.

Note that it will cause an error if the client side drops a proxy object of an already deleted (by this method) service object. Consider calling disable_garbage_collection() on the other end if there's such an issue.

Note also that this might trigger delete request as a side effect since the service object might own a proxy object.

pub fn disable_garbage_collection(&self)

Disables all delete request from this end to the other end.

If you call this, all drop() of proxy objects imported from this context won't send a delete request anymore. This is useful when you're not sure if the connection is still alive, but you have to close your side's context anyway.

pub fn wait(self, timeout: Option<Duration>) -> Result<(), Self>

Waits until the transport is closed.

Technically, this method will block until TransportRecv returns an error. Use this if you have nothing to do while the connection is working well.

TODO: We should actually consider timeout

Trait Implementations

impl Debug for Context

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Context

pub fn drop(&mut self)

This will delete all service objects after calling disable_garbage_collection() internally.