~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/rust/kernel/sync/arc.rs

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /rust/kernel/sync/arc.rs (Version linux-6.12-rc7) and /rust/kernel/sync/arc.rs (Version linux-6.2.16)


  1 // SPDX-License-Identifier: GPL-2.0               
  2                                                   
  3 //! A reference-counted pointer.                  
  4 //!                                               
  5 //! This module implements a way for users to     
  6 //! them. Such a pointer automatically increme    
  7 //! underlying object when it reaches zero. It    
  8 //! threads.                                      
  9 //!                                               
 10 //! It is different from the standard library'    
 11 //! 1. It is backed by the kernel's `refcount_    
 12 //! 2. It does not support weak references, wh    
 13 //! 3. It saturates the reference count instea    
 14 //! 4. It does not provide a `get_mut` method,    
 15 //! 5. The object in [`Arc`] is pinned implici    
 16 //!                                               
 17 //! [`Arc`]: https://doc.rust-lang.org/std/syn    
 18                                                   
 19 use crate::{                                      
 20     alloc::{box_ext::BoxExt, AllocError, Flags    
 21     bindings,                                     
 22     init::{self, InPlaceInit, Init, PinInit},     
 23     try_init,                                     
 24     types::{ForeignOwnable, Opaque},              
 25 };                                                
 26 use alloc::boxed::Box;                            
 27 use core::{                                       
 28     alloc::Layout,                                
 29     fmt,                                          
 30     marker::{PhantomData, Unsize},                
 31     mem::{ManuallyDrop, MaybeUninit},             
 32     ops::{Deref, DerefMut},                       
 33     pin::Pin,                                     
 34     ptr::NonNull,                                 
 35 };                                                
 36 use macros::pin_data;                             
 37                                                   
 38 mod std_vendor;                                   
 39                                                   
 40 /// A reference-counted pointer to an instance    
 41 ///                                               
 42 /// The reference count is incremented when ne    
 43 /// when they are dropped. When the count reac    
 44 ///                                               
 45 /// # Invariants                                  
 46 ///                                               
 47 /// The reference count on an instance of [`Ar    
 48 /// The object pointed to by [`Arc`] is always    
 49 ///                                               
 50 /// # Examples                                    
 51 ///                                               
 52 /// ```                                           
 53 /// use kernel::sync::Arc;                        
 54 ///                                               
 55 /// struct Example {                              
 56 ///     a: u32,                                   
 57 ///     b: u32,                                   
 58 /// }                                             
 59 ///                                               
 60 /// // Create a refcounted instance of `Exampl    
 61 /// let obj = Arc::new(Example { a: 10, b: 20     
 62 ///                                               
 63 /// // Get a new pointer to `obj` and incremen    
 64 /// let cloned = obj.clone();                     
 65 ///                                               
 66 /// // Assert that both `obj` and `cloned` poi    
 67 /// assert!(core::ptr::eq(&*obj, &*cloned));      
 68 ///                                               
 69 /// // Destroy `obj` and decrement its refcoun    
 70 /// drop(obj);                                    
 71 ///                                               
 72 /// // Check that the values are still accessi    
 73 /// assert_eq!(cloned.a, 10);                     
 74 /// assert_eq!(cloned.b, 20);                     
 75 ///                                               
 76 /// // The refcount drops to zero when `cloned    
 77 /// # Ok::<(), Error>(())                         
 78 /// ```                                           
 79 ///                                               
 80 /// Using `Arc<T>` as the type of `self`:         
 81 ///                                               
 82 /// ```                                           
 83 /// use kernel::sync::Arc;                        
 84 ///                                               
 85 /// struct Example {                              
 86 ///     a: u32,                                   
 87 ///     b: u32,                                   
 88 /// }                                             
 89 ///                                               
 90 /// impl Example {                                
 91 ///     fn take_over(self: Arc<Self>) {           
 92 ///         // ...                                
 93 ///     }                                         
 94 ///                                               
 95 ///     fn use_reference(self: &Arc<Self>) {      
 96 ///         // ...                                
 97 ///     }                                         
 98 /// }                                             
 99 ///                                               
100 /// let obj = Arc::new(Example { a: 10, b: 20     
101 /// obj.use_reference();                          
102 /// obj.take_over();                              
103 /// # Ok::<(), Error>(())                         
104 /// ```                                           
105 ///                                               
106 /// Coercion from `Arc<Example>` to `Arc<dyn M    
107 ///                                               
108 /// ```                                           
109 /// use kernel::sync::{Arc, ArcBorrow};           
110 ///                                               
111 /// trait MyTrait {                               
112 ///     // Trait has a function whose `self` t    
113 ///     fn example1(self: Arc<Self>) {}           
114 ///                                               
115 ///     // Trait has a function whose `self` t    
116 ///     fn example2(self: ArcBorrow<'_, Self>)    
117 /// }                                             
118 ///                                               
119 /// struct Example;                               
120 /// impl MyTrait for Example {}                   
121 ///                                               
122 /// // `obj` has type `Arc<Example>`.             
123 /// let obj: Arc<Example> = Arc::new(Example,     
124 ///                                               
125 /// // `coerced` has type `Arc<dyn MyTrait>`.     
126 /// let coerced: Arc<dyn MyTrait> = obj;          
127 /// # Ok::<(), Error>(())                         
128 /// ```                                           
129 pub struct Arc<T: ?Sized> {                       
130     ptr: NonNull<ArcInner<T>>,                    
131     _p: PhantomData<ArcInner<T>>,                 
132 }                                                 
133                                                   
134 #[pin_data]                                       
135 #[repr(C)]                                        
136 struct ArcInner<T: ?Sized> {                      
137     refcount: Opaque<bindings::refcount_t>,       
138     data: T,                                      
139 }                                                 
140                                                   
141 impl<T: ?Sized> ArcInner<T> {                     
142     /// Converts a pointer to the contents of     
143     ///                                           
144     /// # Safety                                  
145     ///                                           
146     /// `ptr` must have been returned by a pre    
147     /// not yet have been destroyed.              
148     unsafe fn container_of(ptr: *const T) -> N    
149         let refcount_layout = Layout::new::<bi    
150         // SAFETY: The caller guarantees that     
151         let val_layout = Layout::for_value(uns    
152         // SAFETY: We're computing the layout     
153         // binary, so its layout is not so lar    
154         let val_offset = unsafe { refcount_lay    
155                                                   
156         // Pointer casts leave the metadata un    
157         // `ArcInner<T>` is the same since `Ar    
158         //                                        
159         // This is documented at:                 
160         // <https://doc.rust-lang.org/std/ptr/    
161         let ptr = ptr as *const ArcInner<T>;      
162                                                   
163         // SAFETY: The pointer is in-bounds of    
164         // pointer, since it originates from a    
165         // still valid.                           
166         let ptr = unsafe { ptr.byte_sub(val_of    
167                                                   
168         // SAFETY: The pointer can't be null s    
169         // address.                               
170         unsafe { NonNull::new_unchecked(ptr.ca    
171     }                                             
172 }                                                 
173                                                   
174 // This is to allow [`Arc`] (and variants) to     
175 impl<T: ?Sized> core::ops::Receiver for Arc<T>    
176                                                   
177 // This is to allow coercion from `Arc<T>` to     
178 // dynamically-sized type (DST) `U`.              
179 impl<T: ?Sized + Unsize<U>, U: ?Sized> core::o    
180                                                   
181 // This is to allow `Arc<U>` to be dispatched     
182 impl<T: ?Sized + Unsize<U>, U: ?Sized> core::o    
183                                                   
184 // SAFETY: It is safe to send `Arc<T>` to anot    
185 // it effectively means sharing `&T` (which is    
186 // `T` to be `Send` because any thread that ha    
187 // mutable reference when the reference count     
188 unsafe impl<T: ?Sized + Sync + Send> Send for     
189                                                   
190 // SAFETY: It is safe to send `&Arc<T>` to ano    
191 // because it effectively means sharing `&T` (    
192 // it needs `T` to be `Send` because any threa    
193 // `Arc<T>` on that thread, so the thread may     
194 // the reference count reaches zero and `T` is    
195 unsafe impl<T: ?Sized + Sync + Send> Sync for     
196                                                   
197 impl<T> Arc<T> {                                  
198     /// Constructs a new reference counted ins    
199     pub fn new(contents: T, flags: Flags) -> R    
200         // INVARIANT: The refcount is initiali    
201         let value = ArcInner {                    
202             // SAFETY: There are no safety req    
203             refcount: Opaque::new(unsafe { bin    
204             data: contents,                       
205         };                                        
206                                                   
207         let inner = <Box<_> as BoxExt<_>>::new    
208                                                   
209         // SAFETY: We just created `inner` wit    
210         // `Arc` object.                          
211         Ok(unsafe { Self::from_inner(Box::leak    
212     }                                             
213 }                                                 
214                                                   
215 impl<T: ?Sized> Arc<T> {                          
216     /// Constructs a new [`Arc`] from an exist    
217     ///                                           
218     /// # Safety                                  
219     ///                                           
220     /// The caller must ensure that `inner` po    
221     /// count, one of which will be owned by t    
222     unsafe fn from_inner(inner: NonNull<ArcInn    
223         // INVARIANT: By the safety requiremen    
224         Arc {                                     
225             ptr: inner,                           
226             _p: PhantomData,                      
227         }                                         
228     }                                             
229                                                   
230     /// Convert the [`Arc`] into a raw pointer    
231     ///                                           
232     /// The raw pointer has ownership of the r    
233     pub fn into_raw(self) -> *const T {           
234         let ptr = self.ptr.as_ptr();              
235         core::mem::forget(self);                  
236         // SAFETY: The pointer is valid.          
237         unsafe { core::ptr::addr_of!((*ptr).da    
238     }                                             
239                                                   
240     /// Recreates an [`Arc`] instance previous    
241     ///                                           
242     /// # Safety                                  
243     ///                                           
244     /// `ptr` must have been returned by a pre    
245     /// must not be called more than once for     
246     pub unsafe fn from_raw(ptr: *const T) -> S    
247         // SAFETY: The caller promises that th    
248         // `Arc` that is still valid.             
249         let ptr = unsafe { ArcInner::container    
250                                                   
251         // SAFETY: By the safety requirements     
252         // reference count held then will be o    
253         unsafe { Self::from_inner(ptr) }          
254     }                                             
255                                                   
256     /// Returns an [`ArcBorrow`] from the give    
257     ///                                           
258     /// This is useful when the argument of a     
259     /// receiver), but we have an [`Arc`] inst    
260     #[inline]                                     
261     pub fn as_arc_borrow(&self) -> ArcBorrow<'    
262         // SAFETY: The constraint that the lif    
263         // the returned `ArcBorrow` ensures th    
264         // reference can be created.              
265         unsafe { ArcBorrow::new(self.ptr) }       
266     }                                             
267                                                   
268     /// Compare whether two [`Arc`] pointers r    
269     pub fn ptr_eq(this: &Self, other: &Self) -    
270         core::ptr::eq(this.ptr.as_ptr(), other    
271     }                                             
272                                                   
273     /// Converts this [`Arc`] into a [`UniqueA    
274     ///                                           
275     /// When this destroys the `Arc`, it does     
276     /// this method will never call the destru    
277     ///                                           
278     /// # Examples                                
279     ///                                           
280     /// ```                                       
281     /// use kernel::sync::{Arc, UniqueArc};       
282     ///                                           
283     /// let arc = Arc::new(42, GFP_KERNEL)?;      
284     /// let unique_arc = arc.into_unique_or_dr    
285     ///                                           
286     /// // The above conversion should succeed    
287     /// assert!(unique_arc.is_some());            
288     ///                                           
289     /// assert_eq!(*(unique_arc.unwrap()), 42)    
290     ///                                           
291     /// # Ok::<(), Error>(())                     
292     /// ```                                       
293     ///                                           
294     /// ```                                       
295     /// use kernel::sync::{Arc, UniqueArc};       
296     ///                                           
297     /// let arc = Arc::new(42, GFP_KERNEL)?;      
298     /// let another = arc.clone();                
299     ///                                           
300     /// let unique_arc = arc.into_unique_or_dr    
301     ///                                           
302     /// // The above conversion should fail si    
303     /// assert!(unique_arc.is_none());            
304     ///                                           
305     /// # Ok::<(), Error>(())                     
306     /// ```                                       
307     pub fn into_unique_or_drop(self) -> Option    
308         // We will manually manage the refcoun    
309         let me = ManuallyDrop::new(self);         
310         // SAFETY: We own a refcount, so the p    
311         let refcount = unsafe { me.ptr.as_ref(    
312                                                   
313         // If the refcount reaches a non-zero     
314         // return without further touching the    
315         // no other arcs, and we can create a     
316         //                                        
317         // SAFETY: We own a refcount, so the p    
318         let is_zero = unsafe { bindings::refco    
319         if is_zero {                              
320             // SAFETY: We have exclusive acces    
321             // accesses to the refcount.          
322             unsafe { core::ptr::write(refcount    
323                                                   
324             // INVARIANT: We own the only refc    
325             // must pin the `UniqueArc` becaus    
326             // their values.                      
327             Some(Pin::from(UniqueArc {            
328                 inner: ManuallyDrop::into_inne    
329             }))                                   
330         } else {                                  
331             None                                  
332         }                                         
333     }                                             
334 }                                                 
335                                                   
336 impl<T: 'static> ForeignOwnable for Arc<T> {      
337     type Borrowed<'a> = ArcBorrow<'a, T>;         
338                                                   
339     fn into_foreign(self) -> *const core::ffi:    
340         ManuallyDrop::new(self).ptr.as_ptr() a    
341     }                                             
342                                                   
343     unsafe fn borrow<'a>(ptr: *const core::ffi    
344         // SAFETY: By the safety requirement o    
345         // a previous call to `Arc::into_forei    
346         let inner = NonNull::new(ptr as *mut A    
347                                                   
348         // SAFETY: The safety requirements of     
349         // for the lifetime of the returned va    
350         unsafe { ArcBorrow::new(inner) }          
351     }                                             
352                                                   
353     unsafe fn from_foreign(ptr: *const core::f    
354         // SAFETY: By the safety requirement o    
355         // a previous call to `Arc::into_forei    
356         // holds a reference count increment t    
357         unsafe { Self::from_inner(NonNull::new    
358     }                                             
359 }                                                 
360                                                   
361 impl<T: ?Sized> Deref for Arc<T> {                
362     type Target = T;                              
363                                                   
364     fn deref(&self) -> &Self::Target {            
365         // SAFETY: By the type invariant, ther    
366         // safe to dereference it.                
367         unsafe { &self.ptr.as_ref().data }        
368     }                                             
369 }                                                 
370                                                   
371 impl<T: ?Sized> AsRef<T> for Arc<T> {             
372     fn as_ref(&self) -> &T {                      
373         self.deref()                              
374     }                                             
375 }                                                 
376                                                   
377 impl<T: ?Sized> Clone for Arc<T> {                
378     fn clone(&self) -> Self {                     
379         // INVARIANT: C `refcount_inc` saturat    
380         // SAFETY: By the type invariant, ther    
381         // safe to increment the refcount.        
382         unsafe { bindings::refcount_inc(self.p    
383                                                   
384         // SAFETY: We just incremented the ref    
385         unsafe { Self::from_inner(self.ptr) }     
386     }                                             
387 }                                                 
388                                                   
389 impl<T: ?Sized> Drop for Arc<T> {                 
390     fn drop(&mut self) {                          
391         // SAFETY: By the type invariant, ther    
392         // touch `refcount` after it's decreme    
393         // may concurrently decrement it to ze    
394         // freed/invalid memory as long as it     
395         let refcount = unsafe { self.ptr.as_re    
396                                                   
397         // INVARIANT: If the refcount reaches     
398         // this instance is being dropped, so     
399         // SAFETY: Also by the type invariant,    
400         let is_zero = unsafe { bindings::refco    
401         if is_zero {                              
402             // The count reached zero, we must    
403             //                                    
404             // SAFETY: The pointer was initial    
405             unsafe { drop(Box::from_raw(self.p    
406         }                                         
407     }                                             
408 }                                                 
409                                                   
410 impl<T: ?Sized> From<UniqueArc<T>> for Arc<T>     
411     fn from(item: UniqueArc<T>) -> Self {         
412         item.inner                                
413     }                                             
414 }                                                 
415                                                   
416 impl<T: ?Sized> From<Pin<UniqueArc<T>>> for Ar    
417     fn from(item: Pin<UniqueArc<T>>) -> Self {    
418         // SAFETY: The type invariants of `Arc    
419         unsafe { Pin::into_inner_unchecked(ite    
420     }                                             
421 }                                                 
422                                                   
423 /// A borrowed reference to an [`Arc`] instanc    
424 ///                                               
425 /// For cases when one doesn't ever need to in    
426 /// to use just `&T`, which we can trivially g    
427 ///                                               
428 /// However, when one may need to increment th    
429 /// over `&Arc<T>` because the latter results     
430 /// to a pointer ([`Arc<T>`]) to the object (`    
431 /// indirection while still allowing one to in    
432 /// needed.                                       
433 ///                                               
434 /// # Invariants                                  
435 ///                                               
436 /// There are no mutable references to the und    
437 /// lifetime of the [`ArcBorrow`] instance.       
438 ///                                               
439 /// # Example                                     
440 ///                                               
441 /// ```                                           
442 /// use kernel::sync::{Arc, ArcBorrow};           
443 ///                                               
444 /// struct Example;                               
445 ///                                               
446 /// fn do_something(e: ArcBorrow<'_, Example>)    
447 ///     e.into()                                  
448 /// }                                             
449 ///                                               
450 /// let obj = Arc::new(Example, GFP_KERNEL)?;     
451 /// let cloned = do_something(obj.as_arc_borro    
452 ///                                               
453 /// // Assert that both `obj` and `cloned` poi    
454 /// assert!(core::ptr::eq(&*obj, &*cloned));      
455 /// # Ok::<(), Error>(())                         
456 /// ```                                           
457 ///                                               
458 /// Using `ArcBorrow<T>` as the type of `self`    
459 ///                                               
460 /// ```                                           
461 /// use kernel::sync::{Arc, ArcBorrow};           
462 ///                                               
463 /// struct Example {                              
464 ///     a: u32,                                   
465 ///     b: u32,                                   
466 /// }                                             
467 ///                                               
468 /// impl Example {                                
469 ///     fn use_reference(self: ArcBorrow<'_, S    
470 ///         // ...                                
471 ///     }                                         
472 /// }                                             
473 ///                                               
474 /// let obj = Arc::new(Example { a: 10, b: 20     
475 /// obj.as_arc_borrow().use_reference();          
476 /// # Ok::<(), Error>(())                         
477 /// ```                                           
478 pub struct ArcBorrow<'a, T: ?Sized + 'a> {        
479     inner: NonNull<ArcInner<T>>,                  
480     _p: PhantomData<&'a ()>,                      
481 }                                                 
482                                                   
483 // This is to allow [`ArcBorrow`] (and variant    
484 impl<T: ?Sized> core::ops::Receiver for ArcBor    
485                                                   
486 // This is to allow `ArcBorrow<U>` to be dispa    
487 // `ArcBorrow<U>`.                                
488 impl<T: ?Sized + Unsize<U>, U: ?Sized> core::o    
489     for ArcBorrow<'_, T>                          
490 {                                                 
491 }                                                 
492                                                   
493 impl<T: ?Sized> Clone for ArcBorrow<'_, T> {      
494     fn clone(&self) -> Self {                     
495         *self                                     
496     }                                             
497 }                                                 
498                                                   
499 impl<T: ?Sized> Copy for ArcBorrow<'_, T> {}      
500                                                   
501 impl<T: ?Sized> ArcBorrow<'_, T> {                
502     /// Creates a new [`ArcBorrow`] instance.     
503     ///                                           
504     /// # Safety                                  
505     ///                                           
506     /// Callers must ensure the following for     
507     /// 1. That `inner` remains valid;            
508     /// 2. That no mutable references to `inne    
509     unsafe fn new(inner: NonNull<ArcInner<T>>)    
510         // INVARIANT: The safety requirements     
511         Self {                                    
512             inner,                                
513             _p: PhantomData,                      
514         }                                         
515     }                                             
516                                                   
517     /// Creates an [`ArcBorrow`] to an [`Arc`]    
518     /// [`Arc::into_raw`].                        
519     ///                                           
520     /// # Safety                                  
521     ///                                           
522     /// * The provided pointer must originate     
523     /// * For the duration of the lifetime ann    
524     ///   not hit zero.                           
525     /// * For the duration of the lifetime ann    
526     ///   [`UniqueArc`] reference to this valu    
527     pub unsafe fn from_raw(ptr: *const T) -> S    
528         // SAFETY: The caller promises that th    
529         // `Arc` that is still valid.             
530         let ptr = unsafe { ArcInner::container    
531                                                   
532         // SAFETY: The caller promises that th    
533         // not hit zero, and no mutable refere    
534         // `UniqueArc`.                           
535         unsafe { Self::new(ptr) }                 
536     }                                             
537 }                                                 
538                                                   
539 impl<T: ?Sized> From<ArcBorrow<'_, T>> for Arc    
540     fn from(b: ArcBorrow<'_, T>) -> Self {        
541         // SAFETY: The existence of `b` guaran    
542         // guarantees that `drop` isn't called    
543         // increment.                             
544         ManuallyDrop::new(unsafe { Arc::from_i    
545             .deref()                              
546             .clone()                              
547     }                                             
548 }                                                 
549                                                   
550 impl<T: ?Sized> Deref for ArcBorrow<'_, T> {      
551     type Target = T;                              
552                                                   
553     fn deref(&self) -> &Self::Target {            
554         // SAFETY: By the type invariant, the     
555         // references to it, so it is safe to     
556         unsafe { &self.inner.as_ref().data }      
557     }                                             
558 }                                                 
559                                                   
560 /// A refcounted object that is known to have     
561 ///                                               
562 /// It is mutable and can be converted to an [    
563 ///                                               
564 /// # Invariants                                  
565 ///                                               
566 /// `inner` always has a reference count of 1.    
567 ///                                               
568 /// # Examples                                    
569 ///                                               
570 /// In the following example, we make changes     
571 /// `Arc<Test>` object (after which point, it     
572 /// cannot fail.                                  
573 ///                                               
574 /// ```                                           
575 /// use kernel::sync::{Arc, UniqueArc};           
576 ///                                               
577 /// struct Example {                              
578 ///     a: u32,                                   
579 ///     b: u32,                                   
580 /// }                                             
581 ///                                               
582 /// fn test() -> Result<Arc<Example>> {           
583 ///     let mut x = UniqueArc::new(Example { a    
584 ///     x.a += 1;                                 
585 ///     x.b += 1;                                 
586 ///     Ok(x.into())                              
587 /// }                                             
588 ///                                               
589 /// # test().unwrap();                            
590 /// ```                                           
591 ///                                               
592 /// In the following example we first allocate    
593 /// initialise it on allocation. We do initial    
594 /// followed by a conversion to `Arc<Example>`    
595 /// in one context (e.g., sleepable) and initi    
596 ///                                               
597 /// ```                                           
598 /// use kernel::sync::{Arc, UniqueArc};           
599 ///                                               
600 /// struct Example {                              
601 ///     a: u32,                                   
602 ///     b: u32,                                   
603 /// }                                             
604 ///                                               
605 /// fn test() -> Result<Arc<Example>> {           
606 ///     let x = UniqueArc::new_uninit(GFP_KERN    
607 ///     Ok(x.write(Example { a: 10, b: 20 }).i    
608 /// }                                             
609 ///                                               
610 /// # test().unwrap();                            
611 /// ```                                           
612 ///                                               
613 /// In the last example below, the caller gets    
614 /// `Arc<Example>`; this is useful in scenario    
615 /// initialisation, for example, when initiali    
616 ///                                               
617 /// ```                                           
618 /// use kernel::sync::{Arc, UniqueArc};           
619 ///                                               
620 /// struct Example {                              
621 ///     a: u32,                                   
622 ///     b: u32,                                   
623 /// }                                             
624 ///                                               
625 /// fn test() -> Result<Arc<Example>> {           
626 ///     let mut pinned = Pin::from(UniqueArc::    
627 ///     // We can modify `pinned` because it i    
628 ///     pinned.as_mut().a += 1;                   
629 ///     Ok(pinned.into())                         
630 /// }                                             
631 ///                                               
632 /// # test().unwrap();                            
633 /// ```                                           
634 pub struct UniqueArc<T: ?Sized> {                 
635     inner: Arc<T>,                                
636 }                                                 
637                                                   
638 impl<T> UniqueArc<T> {                            
639     /// Tries to allocate a new [`UniqueArc`]     
640     pub fn new(value: T, flags: Flags) -> Resu    
641         Ok(Self {                                 
642             // INVARIANT: The newly-created ob    
643             inner: Arc::new(value, flags)?,       
644         })                                        
645     }                                             
646                                                   
647     /// Tries to allocate a new [`UniqueArc`]     
648     pub fn new_uninit(flags: Flags) -> Result<    
649         // INVARIANT: The refcount is initiali    
650         let inner = Box::try_init::<AllocError    
651             try_init!(ArcInner {                  
652                 // SAFETY: There are no safety    
653                 refcount: Opaque::new(unsafe {    
654                 data <- init::uninit::<T, Allo    
655             }? AllocError),                       
656             flags,                                
657         )?;                                       
658         Ok(UniqueArc {                            
659             // INVARIANT: The newly-created ob    
660             // SAFETY: The pointer from the `B    
661             inner: unsafe { Arc::from_inner(Bo    
662         })                                        
663     }                                             
664 }                                                 
665                                                   
666 impl<T> UniqueArc<MaybeUninit<T>> {               
667     /// Converts a `UniqueArc<MaybeUninit<T>>`    
668     pub fn write(mut self, value: T) -> Unique    
669         self.deref_mut().write(value);            
670         // SAFETY: We just wrote the value to     
671         unsafe { self.assume_init() }             
672     }                                             
673                                                   
674     /// Unsafely assume that `self` is initial    
675     ///                                           
676     /// # Safety                                  
677     ///                                           
678     /// The caller guarantees that the value b    
679     /// *immediate* UB to call this when the v    
680     pub unsafe fn assume_init(self) -> UniqueA    
681         let inner = ManuallyDrop::new(self).in    
682         UniqueArc {                               
683             // SAFETY: The new `Arc` is taking    
684             // dropped). The types are compati    
685             inner: unsafe { Arc::from_inner(in    
686         }                                         
687     }                                             
688                                                   
689     /// Initialize `self` using the given init    
690     pub fn init_with<E>(mut self, init: impl I    
691         // SAFETY: The supplied pointer is val    
692         match unsafe { init.__init(self.as_mut    
693             // SAFETY: Initialization complete    
694             Ok(()) => Ok(unsafe { self.assume_    
695             Err(err) => Err(err),                 
696         }                                         
697     }                                             
698                                                   
699     /// Pin-initialize `self` using the given     
700     pub fn pin_init_with<E>(                      
701         mut self,                                 
702         init: impl PinInit<T, E>,                 
703     ) -> core::result::Result<Pin<UniqueArc<T>    
704         // SAFETY: The supplied pointer is val    
705         // to ensure it does not move.            
706         match unsafe { init.__pinned_init(self    
707             // SAFETY: Initialization complete    
708             Ok(()) => Ok(unsafe { self.assume_    
709             Err(err) => Err(err),                 
710         }                                         
711     }                                             
712 }                                                 
713                                                   
714 impl<T: ?Sized> From<UniqueArc<T>> for Pin<Uni    
715     fn from(obj: UniqueArc<T>) -> Self {          
716         // SAFETY: It is not possible to move/    
717         // is `Unpin`), so it is ok to convert    
718         unsafe { Pin::new_unchecked(obj) }        
719     }                                             
720 }                                                 
721                                                   
722 impl<T: ?Sized> Deref for UniqueArc<T> {          
723     type Target = T;                              
724                                                   
725     fn deref(&self) -> &Self::Target {            
726         self.inner.deref()                        
727     }                                             
728 }                                                 
729                                                   
730 impl<T: ?Sized> DerefMut for UniqueArc<T> {       
731     fn deref_mut(&mut self) -> &mut Self::Targ    
732         // SAFETY: By the `Arc` type invariant    
733         // it is safe to dereference it. Addit    
734         // it's inside a `UniqueArc`, so it is    
735         unsafe { &mut self.inner.ptr.as_mut().    
736     }                                             
737 }                                                 
738                                                   
739 impl<T: fmt::Display + ?Sized> fmt::Display fo    
740     fn fmt(&self, f: &mut fmt::Formatter<'_>)     
741         fmt::Display::fmt(self.deref(), f)        
742     }                                             
743 }                                                 
744                                                   
745 impl<T: fmt::Display + ?Sized> fmt::Display fo    
746     fn fmt(&self, f: &mut fmt::Formatter<'_>)     
747         fmt::Display::fmt(self.deref(), f)        
748     }                                             
749 }                                                 
750                                                   
751 impl<T: fmt::Debug + ?Sized> fmt::Debug for Un    
752     fn fmt(&self, f: &mut fmt::Formatter<'_>)     
753         fmt::Debug::fmt(self.deref(), f)          
754     }                                             
755 }                                                 
756                                                   
757 impl<T: fmt::Debug + ?Sized> fmt::Debug for Ar    
758     fn fmt(&self, f: &mut fmt::Formatter<'_>)     
759         fmt::Debug::fmt(self.deref(), f)          
760     }                                             
761 }                                                 
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php