Struct netidx::publisher::Publisher

pub struct Publisher(_);

Publish values and centrally flush queued updates. Publisher is internally wrapped in an Arc, so cloning it is virtually free. When all references to to the publisher have been dropped the publisher will shutdown the listener, and remove all published paths from the resolver server.

Implementations

impl Publisher

pub async fn new(
    resolver: Config,
    desired_auth: Auth,
    bind_cfg: BindCfg
) -> Result<Publisher>

Create a new publisher using the specified resolver, desired auth, and bind config.

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

Perform a clean shutdown of the publisher, remove all published paths from the resolver server, shutdown the listener, and close the connection to all clients. Dropping all references to the publisher also calls this function, however because async Drop is not yet implemented it is not guaranteed that a clean shutdown will be achieved before the Runtime itself is Dropped, as such it is necessary to call this function directly in the case you are tearing down the whole program. In the case where you have multiple publishers in your process, or you are for some reason tearing down the publisher but will continue to run async jobs on the same Runtime, then there is no need to call this function, you can just Drop all references to the Publisher.

This function will return an error if other references to the publisher exist.

pub fn addr(&self) -> SocketAddr

get the SocketAddr that publisher is bound to

pub fn publish_with_flags(
    &self,
    flags: PublishFlags,
    path: Path,
    init: Value
) -> Result<Val>

Publish Path with initial value init and flags flags. It is an error for the same publisher to publish the same path twice, however different publishers may publish a given path as many times as they like. Subscribers will then pick randomly among the advertised publishers when subscribing. See subscriber

pub fn publish(&self, path: Path, init: Value) -> Result<Val>

Publish Path with initial value init and no flags. It is an error for the same publisher to publish the same path twice, however different publishers may publish a given path as many times as they like. Subscribers will then pick randomly among the advertised publishers when subscribing. See subscriber

pub fn publish_default_with_flags(
    &self,
    flags: PublishFlags,
    base: Path
) -> Result<DefaultHandle>

Install a default publisher rooted at base with flags flags. Once installed, any subscription request for a child of base, regardless if it doesn’t exist in the resolver, will be routed to this publisher or one of it’s peers in the case of multiple default publishers.

You must listen for requests on the returned channel handle, and if they are valid, you should publish the requested value, and signal the subscriber by sending () to the oneshot channel that comes with the request. In the case the request is not valid, just send to the oneshot channel and the subscriber will be told the value doesn’t exist.

This functionality is useful if, for example, you have a huge namespace and you know your subscribers will only want small parts of it, but you can’t predict ahead of time which parts. It can also be used to implement e.g. a database query by appending the escaped query to the base path, with the added bonus that the result will be automatically cached and distributed to anyone making the same query again.

pub fn publish_default(&self, base: Path) -> Result<DefaultHandle>

Install a default publisher rooted at base with no flags. Once installed, any subscription request for a child of base, regardless if it doesn’t exist in the resolver, will be routed to this publisher or one of it’s peers in the case of multiple default publishers.

You must listen for requests on the returned channel handle, and if they are valid, you should publish the requested value, and signal the subscriber by sending () to the oneshot channel that comes with the request. In the case the request is not valid, just send to the oneshot channel and the subscriber will be told the value doesn’t exist.

This functionality is useful if, for example, you have a huge namespace and you know your subscribers will only want small parts of it, but you can’t predict ahead of time which parts. It can also be used to implement e.g. a database query by appending the escaped query to the base path, with the added bonus that the result will be automatically cached and distributed to anyone making the same query again.

pub async fn flush(&self, timeout: Option<Duration>)

Flush initiates sending queued updates out to subscribers, and also sends all queued publish/unpublish operations to the resolver. The semantics of flush are such that any update queued before flush is called will go out when it is called, and any update queued after flush is called will only go out on the next flush.

If you don’t want to wait for the future you can just throw it away, flush triggers sending the data whether you await the future or not, unlike most futures. However if you never wait for any of the futures returned by flush there won’t be any pushback, so a slow client could cause the publisher to consume arbitrary amounts of memory unless you set an aggressive timeout.

If timeout is specified then any client that can’t accept the update within the timeout duration will be disconnected. Otherwise flush will wait as long as necessary to flush the update to every client.

pub fn clients(&self) -> usize

Returns the number of subscribers subscribing to at least one value.

pub async fn wait_any_client(&self)

Wait for at least one client to subscribe to at least one value. Returns immediately if there is already a client.

pub async fn wait_any_new_client(&self)

Wait for any new client to connect. This will always wait for a new client, even if there are clients connected.

pub async fn wait_client(&self, id: Id)

Wait for at least one client to subscribe to the specified published value. Returns immediatly if there is a client, or if the published value is dead.

Trait Implementations

impl Clone for Publisher

fn clone(&self) -> Publisher

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.