ringbuf/wrap/
frozen.rs

1//! Deprecated compatibility wrappers for caching endpoints.
2//!
3//! All writes and removals are now published immediately. Use [`CachingProd`](super::CachingProd)
4//! and [`CachingCons`](super::CachingCons) directly instead. These wrappers remain available;
5//! their removal is reserved for a future breaking release.
6//!
7//! Deferred publication could cause double drops if an endpoint was forgotten with [`core::mem::forget`].
8//! Publication no longer depends on running its destructor. Code relying on delayed visibility or
9//! rollback must be updated even though the compatibility API remains available.
10//!
11//! # Migration
12//!
13//! Remove calls to `freeze`, `commit`, `fetch`, and `sync`. Endpoints publish their own changes
14//! immediately and fetch the opposite endpoint's progress as needed. `discard` is now a no-op:
15//! published items cannot be retracted. Stage items outside the ring buffer if rollback is needed,
16//! and use bulk operations such as `push_slice` and `pop_slice` to batch index updates.
17
18#![allow(deprecated)]
19
20use super::{caching::Caching, direct::Obs, traits::Wrap};
21#[cfg(feature = "std")]
22use crate::traits::Consumer;
23use crate::{
24    rb::RbRef,
25    traits::{
26        Based,
27        consumer::{DelegateConsumer, impl_consumer_traits},
28        observer::DelegateObserver,
29        producer::{DelegateProducer, Producer, impl_producer_traits},
30    },
31};
32
33/// Compatibility wrapper with the same immediate publication behavior as [`Caching`].
34///
35/// Unlike earlier versions, this wrapper never defers publication until `commit` or drop.
36#[deprecated(note = "use Caching directly; frozen endpoints now publish changes immediately and will be removed in the next breaking release")]
37pub struct Frozen<R: RbRef, const P: bool, const C: bool> {
38    inner: Caching<R, P, C>,
39}
40
41/// Deprecated producer wrapper. All inserted items are published immediately.
42#[deprecated(note = "use CachingProd; writes are now published immediately")]
43pub type FrozenProd<R> = Frozen<R, true, false>;
44
45/// Deprecated consumer wrapper. All removals are published immediately.
46#[deprecated(note = "use CachingCons; removals are now published immediately")]
47pub type FrozenCons<R> = Frozen<R, false, true>;
48
49impl<R: RbRef, const P: bool, const C: bool> Frozen<R, P, C> {
50    /// Create a compatibility wrapper with immediate publication.
51    ///
52    /// Panics if an endpoint with matching rights already exists.
53    pub fn new(rb: R) -> Self {
54        Self::from_caching(Caching::new(rb))
55    }
56
57    pub(crate) fn from_caching(inner: Caching<R, P, C>) -> Self {
58        Self { inner }
59    }
60
61    /// Get ring buffer observer.
62    pub fn observe(&self) -> Obs<R> {
63        self.inner.observe()
64    }
65
66    /// Does nothing: all changes have already been published.
67    #[deprecated(note = "changes are published immediately; remove this call")]
68    pub fn commit(&self) {}
69
70    /// Refresh the cached opposite index. Operations also refresh it as needed.
71    #[deprecated(note = "the caching endpoint fetches progress automatically; remove this call")]
72    pub fn fetch(&self) {
73        self.inner.fetch();
74    }
75
76    /// Refresh the cached opposite index. All local changes are already published.
77    #[deprecated(note = "changes are published immediately and progress is fetched automatically; remove this call")]
78    pub fn sync(&self) {
79        self.inner.fetch();
80    }
81}
82
83impl<R: RbRef> FrozenProd<R> {
84    /// Does nothing: inserted items are already published and cannot be retracted.
85    ///
86    /// Stage items outside the ring buffer if they may need to be discarded.
87    #[deprecated(
88        note = "discard is now a no-op because writes are immediately published; stage items outside the ring buffer to support rollback"
89    )]
90    pub fn discard(&mut self) {}
91}
92
93impl<R: RbRef, const P: bool, const C: bool> Based for Frozen<R, P, C> {
94    type Base = Caching<R, P, C>;
95
96    fn base(&self) -> &Self::Base {
97        &self.inner
98    }
99    fn base_mut(&mut self) -> &mut Self::Base {
100        &mut self.inner
101    }
102}
103
104impl<R: RbRef, const P: bool, const C: bool> Wrap for Frozen<R, P, C> {
105    type RbRef = R;
106
107    fn rb_ref(&self) -> &R {
108        self.inner.rb_ref()
109    }
110    fn into_rb_ref(self) -> R {
111        self.inner.into_rb_ref()
112    }
113}
114
115impl<R: RbRef, const P: bool, const C: bool> AsRef<Self> for Frozen<R, P, C> {
116    fn as_ref(&self) -> &Self {
117        self
118    }
119}
120impl<R: RbRef, const P: bool, const C: bool> AsMut<Self> for Frozen<R, P, C> {
121    fn as_mut(&mut self) -> &mut Self {
122        self
123    }
124}
125
126impl<R: RbRef, const P: bool, const C: bool> DelegateObserver for Frozen<R, P, C> {}
127impl<R: RbRef> DelegateProducer for FrozenProd<R> {}
128impl<R: RbRef> DelegateConsumer for FrozenCons<R> {}
129
130impl_producer_traits!(FrozenProd<R: RbRef>);
131impl_consumer_traits!(FrozenCons<R: RbRef>);
ringbuf/wrap/frozen.rs

ringbuf/wrap/
frozen.rs
