11//! # FFI opaque pointers.
2- //!
2+ //!
33//! FFI to use Rust objects from C as opaque pointer.
44
55#![ allow( unsafe_code) ]
88#![ deny( clippy:: complexity) ]
99#![ deny( clippy:: cognitive_complexity) ]
1010#![ allow( clippy:: needless_return) ] // To avoid surprise in devs more familiar where return is always explicit
11-
1211#![ doc( html_no_source) ]
13-
1412#![ no_std]
1513
1614#[ cfg( all( feature = "alloc" , not( feature = "std" ) ) ) ]
@@ -36,18 +34,15 @@ fn panic_if_null<T>(pointer: *const T) {
3634}
3735
3836/// Get a heap-allocated raw pointer without ownership.
39- ///
37+ ///
4038/// To back to manage the memory with ownership use [`own_back<T>()`].
4139#[ cfg( any( feature = "alloc" , feature = "std" ) ) ]
4240#[ inline]
4341pub fn raw < T > ( data : T ) -> * mut T {
4442 return Box :: into_raw ( Box :: new ( data) ) ;
4543}
4644
47- #[ deprecated(
48- since = "0.7.2" ,
49- note = "Use `own_back<T>()` instead"
50- ) ]
45+ #[ deprecated( since = "0.7.2" , note = "Use `own_back<T>()` instead" ) ]
5146#[ allow( missing_docs) ]
5247#[ cfg( any( feature = "alloc" , feature = "std" ) ) ]
5348#[ inline]
@@ -56,11 +51,11 @@ pub unsafe fn free<T>(pointer: *mut T) {
5651}
5752
5853/// Opposite of [`raw<T>()`], to use Rust's ownership as usually.
59- ///
54+ ///
6055/// # Safety
61- ///
56+ ///
6257/// The pointer must be a valid reference and never call it twice or behavior is undefined.
63- ///
58+ ///
6459/// That could produce a HEAP error that produce a crash.
6560#[ doc( alias = "free" ) ]
6661#[ cfg( any( feature = "alloc" , feature = "std" ) ) ]
@@ -74,12 +69,12 @@ pub unsafe fn own_back<T>(pointer: *mut T) -> T {
7469}
7570
7671/// Reference to a object but without back to own it.
77- ///
72+ ///
7873/// That's the difference with [`own_back<T>()`], you must
7974/// use [`own_back<T>()`] to own it again and it will be dropped.
80- ///
75+ ///
8176/// # Safety
82- ///
77+ ///
8378/// Invalid pointer or call it twice could cause an undefined behavior or heap error and a crash.
8479#[ inline]
8580pub unsafe fn object < ' a , T > ( pointer : * const T ) -> & ' a T {
@@ -90,12 +85,12 @@ pub unsafe fn object<'a, T>(pointer: *const T) -> &'a T {
9085}
9186
9287/// Mutable reference to a object but without back to own it.
93- ///
88+ ///
9489/// That's the difference with [`own_back<T>()`], you must
9590/// use [`own_back<T>()`] to own it again and it will be dropped.
96- ///
91+ ///
9792/// # Safety
98- ///
93+ ///
9994/// Invalid pointer or call it twice could cause an undefined behavior or heap error and a crash.
10095#[ inline]
10196pub unsafe fn mut_object < ' a , T > ( pointer : * mut T ) -> & ' a mut T {
0 commit comments