1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

//! Safely use (stack) references outside their original scope.

#![doc(html_root_url = "https://docs.rs/ref-portals/1.0.0-beta.2")]
#![doc(test(no_crate_inject))]
#![warn(
    clippy::as_conversions,
    clippy::cargo,
    clippy::clone_on_ref_ptr,
    clippy::fallible_impl_from,
    clippy::missing_const_for_fn,
    clippy::missing_docs_in_private_items,
    clippy::multiple_crate_versions,
    clippy::needless_borrow,
    clippy::pedantic,
    clippy::use_self,
    clippy::wrong_pub_self_convention
)]
#![allow(clippy::wildcard_imports)]
#![deny(clippy::wildcard_dependencies)]
// Debug cleanup. Uncomment before committing.
#![forbid(
    clippy::dbg_macro,
    clippy::print_stdout,
    clippy::todo,
    clippy::unimplemented
)]

//! # Example
//!
//! ```rust
//! use ref_portals::rc::Anchor;
//! 
//! let x = "Scoped".to_owned();
//! let anchor = Anchor::new(&x);
//! let self_owned: Box<dyn Fn() + 'static> = Box::new({
//!     let portal = anchor.portal();
//!     move || println!("{}", *portal)
//! });
//! 
//! self_owned(); // Scoped
//! ```
//! 
//! Note that dropping `anchor` before `self_owned` would still cause a panic here.  
//! You can use weak portals to work around this:
//!
//! ```rust
//! use ref_portals::rc::Anchor;
//! 
//! let x = "Scoped".to_owned();
//! let anchor = Anchor::new(&x);
//! let eternal: &'static dyn Fn() = Box::leak(Box::new({
//!     let weak_portal = anchor.weak_portal();
//!     move || println!(
//!         "{}",
//!         *weak_portal.upgrade(), // Panics iff the anchor has been dropped.
//!     )
//! }));
//! 
//! eternal(); // Scoped
//! ```
//!
//! # Notes
//! 
//! Panic assertions in this documentation use [assert_panic](https://crates.io/crates/assert-panic).

pub mod rc;
pub mod sync;

/// Panicked when upgrading weak portals iff the anchor has been destroyed already.
const ANCHOR_DROPPED: &str = "Anchor dropped";

/// Panicked when borrowing through a portal or dropping an anchor if the anchor has been poisoned.
/// Only mutable anchors can be poisoned.
const ANCHOR_POISONED: &str = "Anchor poisoned";

/// Panicked when dropping an anchor if any (strong) portals still exist.
const ANCHOR_STILL_IN_USE: &str = "Anchor still in use (at least one portal exists)";