ref_portals/
lib.rs

1//! Safely use (stack) references outside their original scope.
2
3#![doc(html_root_url = "https://docs.rs/ref-portals/1.0.0-beta.2")]
4#![doc(test(no_crate_inject))]
5#![warn(
6    clippy::as_conversions,
7    clippy::cargo,
8    clippy::clone_on_ref_ptr,
9    clippy::fallible_impl_from,
10    clippy::missing_const_for_fn,
11    clippy::missing_docs_in_private_items,
12    clippy::multiple_crate_versions,
13    clippy::needless_borrow,
14    clippy::pedantic,
15    clippy::use_self,
16    clippy::wrong_pub_self_convention
17)]
18#![allow(clippy::wildcard_imports)]
19#![deny(clippy::wildcard_dependencies)]
20// Debug cleanup. Uncomment before committing.
21#![forbid(
22    clippy::dbg_macro,
23    clippy::print_stdout,
24    clippy::todo,
25    clippy::unimplemented
26)]
27
28//! # Example
29//!
30//! ```rust
31//! use ref_portals::rc::Anchor;
32//! 
33//! let x = "Scoped".to_owned();
34//! let anchor = Anchor::new(&x);
35//! let self_owned: Box<dyn Fn() + 'static> = Box::new({
36//!     let portal = anchor.portal();
37//!     move || println!("{}", *portal)
38//! });
39//! 
40//! self_owned(); // Scoped
41//! ```
42//! 
43//! Note that dropping `anchor` before `self_owned` would still cause a panic here.  
44//! You can use weak portals to work around this:
45//!
46//! ```rust
47//! use ref_portals::rc::Anchor;
48//! 
49//! let x = "Scoped".to_owned();
50//! let anchor = Anchor::new(&x);
51//! let eternal: &'static dyn Fn() = Box::leak(Box::new({
52//!     let weak_portal = anchor.weak_portal();
53//!     move || println!(
54//!         "{}",
55//!         *weak_portal.upgrade(), // Panics iff the anchor has been dropped.
56//!     )
57//! }));
58//! 
59//! eternal(); // Scoped
60//! ```
61//!
62//! # Notes
63//! 
64//! Panic assertions in this documentation use [assert_panic](https://crates.io/crates/assert-panic).
65
66pub mod rc;
67pub mod sync;
68
69/// Panicked when upgrading weak portals iff the anchor has been destroyed already.
70const ANCHOR_DROPPED: &str = "Anchor dropped";
71
72/// Panicked when borrowing through a portal or dropping an anchor if the anchor has been poisoned.
73/// Only mutable anchors can be poisoned.
74const ANCHOR_POISONED: &str = "Anchor poisoned";
75
76/// Panicked when dropping an anchor if any (strong) portals still exist.
77const ANCHOR_STILL_IN_USE: &str = "Anchor still in use (at least one portal exists)";
ref_portals/lib.rs

ref_portals/
lib.rs
