Migrate to the Velo handle in 0.21
Velo is now a cheap handle. VeloBuilder::build() returns Velo. It used to return Arc<Velo>.
Velo is Clone. A clone adds one reference count and does not copy any state. Every clone is the same instance.
How to migrate
- Replace
Arc<Velo>withVeloin your types and signatures. - Replace
Weak<Velo>withWeakVeloin your types and signatures. - Remove
velo.as_ref()and&*velo. Pass&veloinstead. Replacevelo.as_ref().clone()withvelo.clone(). - Keep
.clone()as it is. It now clones the handle. - Change
Arc::clone(&velo)tovelo.clone(). - Change
Arc::downgrade(&velo)tovelo.downgrade(). It returns aWeakVelo, andWeakVelo::upgrade()returnsOption<Velo>. A handler that reaches its own instance must hold aWeakVelo. AVeloclone in the handler keeps the instance alive, so its final drop never runs. - Change
Weak::new()toWeakVelo::default(). It points at no instance, andupgrade()returnsNone. - Change
Arc::ptr_eq(&a, &b)toa.instance_id() == b.instance_id(). Clones of one instance share anInstanceId, and separate instances never do.Velodoes not expose reference counts. - The other
ArcandWeakmethods have no counterpart:try_unwrap,into_inner,get_mut,make_mut,strong_count,weak_count, andWeak::ptr_eq. For identity, compareinstance_id(). To share, clone. - Remove
Arc::new(velo)if you wrapped a builtVelo. Passveloorvelo.clone()instead.
// 0.20: `velo` is an `Arc<Velo>`
let velo = Velo::builder().add_transport(transport).build().await?;
let worker = Arc::clone(&velo);
// 0.21: `velo` is a Velo
let velo = Velo::builder().add_transport(transport).build().await?;
let worker = velo.clone();
Arc<Messenger> and the other Arc values that Velo hands out do not change.
What does not change
- Clones share one instance and one set of handlers, streams, and rendezvous state.
- The final drop of the last clone cancels the streaming services. Dropping any other clone does not.
graceful_shutdownruns its teardown once, even when you call it through different clones. A later call waits for the first and then returns, unless the first teardown failed. Then a later call panics at once.shutdowncallsgraceful_shutdown, then closes the streaming services. It does the streaming step again on each call.- Wire formats and
velo-exttraits do not change.