fre_rs/
lib.rs

1//!
2//! Safe, ergonomic Rust abstraction over the AIR Native Extension (ANE) C API ([`fre-sys`](https://crates.io/crates/fre-sys)) for native-side development.
3//!
4//! ## Getting Started
5//!
6//! The primary entry points of this crate are the macros [`extension!`] and [`function!`].
7//! Refer to their documentation for details and examples.
8//!
9//! # Flash Runtime Extension Lifecycle
10//!
11//! ```text
12//!                                   Flash-Runtime ━━━━┓
13//!                                                     ┃
14//!          ExtensionContext.loadExtension ━━━━━━━━━━━━┫
15//!                ↓                                    ┃
16//!    ┏━━━━ Extension-Load ━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
17//!    ┃           ↓                                    ┃
18//!    ┃     Initializer → Extension-Data               ┃
19//!    ┃           ↓                                    ┃
20//!    ┃  ┏━━ ExtensionContext.createExtensionContext ━━┫
21//!    ┃  ┃        ↓                                    ┃
22//!    ┃  ┃    Context-Initializer → Context-Data       ┃
23//!    ┃  ┃        ↓            ↓    ↓         ↓        ┃
24//!    ┃  ┃    Function-Data → Function  Extension-Data ┃
25//!    ┃  ┃                     ↑                       ┃
26//!    ┃  ┣━━ ExtensionContext.call ━━━━━━━━━━━━━━━━━━━━┫
27//!    ┃  ┃                                             ┃
28//!    ┃  ┃                        Extension-Data       ┃
29//!    ┃  ┃                              ↑              ┃
30//!    ┃  ┃    Context-Data ≈ `ContextRegistry`         ┃
31//!    ┃  ┃        ↓                     ↑              ┃
32//!    ┃  ┃    Context-Finalizer    Function-Data       ┃
33//!    ┃  ┃        ↑                                    ┃
34//!    ┃  ┗━━ ExtensionContext.dispose ━━━━━━━━━━━━━━━━━┫
35//!    ┃                                                ┃
36//!    ┃            Extension-Data → Finalizer          ┃
37//!    ┃                                 ↑              ┃
38//!    ┗━━━━━━━━━━━━━━━━━━━━━━━━━━ Extension-Unload ━━━━┛
39//! ```
40//!
41
42
43/// Namespace for ActionScript 3 classes and objects.
44/// 
45pub mod as3 {
46    use super::*;
47    pub use crate::types::{
48        display::*,
49        misc::*,
50        object::{Object},
51        primitive::*,
52    };
53
54    /// Although `'static`, using [`null`] outside the Flash runtime main thread,
55    /// or within certain restricted closure call stacks (when an object is acquired
56    /// and the runtime is constrained) is unsupported. Related APIs may return errors in such cases.
57    /// 
58    #[allow(non_upper_case_globals)]
59    // 
60    // ALL APIS THAT MAY BE USED IN UNSUPPORTED CASES MUST HANDLE ERRORS CORRECTLY AND MUST NOT PANIC. (`AsObject`, `Object`)
61    // 
62    pub const null: Object<'static> = unsafe {transmute(std::ptr::null_mut::<FREObject>())};
63}
64
65/// [`fre-sys`](https://crates.io/crates/fre-sys)
66/// 
67pub mod c {pub use fre_sys::*;}
68pub mod prelude {
69    pub use crate::{
70        as3,
71        types::{Type, object::{Object, NonNullObject, AsObject, AsNonNullObject, TryAs}},
72        context::{Context, CurrentContext},
73        data::Data,
74        event::*,
75        function::{FunctionSet, trace},
76        validated::*,
77    };
78    pub use std::any::Any;
79}
80pub mod context;
81pub mod data;
82pub mod error;
83pub mod event;
84pub mod function;
85mod macros;
86pub mod misc;
87pub mod types;
88pub mod validated;
89pub mod utils;
90
91
92use {
93    prelude::*,
94    c::*,
95    data::ExtensionData,
96    error::*,
97    function::*,
98    misc::*,
99    utils::*,
100};
101use std::{
102    borrow::Cow,
103    cell::{RefCell},
104    collections::HashMap,
105    ffi::{CStr, CString, NulError, c_void, c_char},
106    fmt::{self, Debug, Display},
107    marker::PhantomData,
108    mem::{MaybeUninit, transmute},
109    ptr::{NonNull},
110    rc::Rc,
111    str::Utf8Error,
112    sync::{Arc, Mutex},
113};
114
115
116/// Internal implementation details of the crate. Not intended for public use.
117/// 
118#[doc(hidden)]
119pub mod __private {
120    pub unsafe trait Sealed {}
121    pub(crate) const SEALED: () = ();
122    pub mod context {
123        pub use crate::context::stack::{with, with_initializer, with_method};
124    }
125    pub mod function {
126        use crate::*;
127        use crate::function::FunctionImplementation;
128        pub const fn implement (name: UCStr, func: FREFunction) -> FunctionImplementation {FunctionImplementation::new(name, func)}
129    }
130}
131
fre_rs/lib.rs

fre_rs/
lib.rs
