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 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256
//! Functions for interoperability with rb-sys.
//!
//! These functions are provided to interface with the lower-level Ruby
//! bindings provided by [rb-sys](rb_sys). You may want to use rb-sys when:
//!
//! 1. Magnus does not provide access to a Ruby API because the API can not be
//! made safe & ergonomic.
//! 2. Magnus exposed the API in a way that does not work for your use case.
//! 3. The API just hasn't been implemented yet.
//!
//! Even if you are not in a position to contribute code to Magnus, please
//! [open an issue](https://github.com/matsadler/magnus/issues) outlining your
//! use case and the APIs you need whenever you find yourself reaching for this
//! module.
//!
//! # Stability
//!
//! Functions in this module are considered unstable. While there is no plan
//! to alter or remove them, non-backwards compatible changes in this module
//! will not necessarily be considered as SemVer major changes.
//!
//! # Safety
//!
//! The unsafe functions in this module are capable of producing values that
//! break the saftey guarantees of almost every other function in Magnus. Use
//! them with care.
use std::panic::UnwindSafe;
use rb_sys::{ID, VALUE};
use crate::{
error::{self, raise, Error},
value::{Id, Value},
};
/// Converts from a [`Value`] to a raw [`VALUE`].
pub trait AsRawValue {
/// Convert [`magnus::Value`](Value) to [`rb_sys::VALUE`](VALUE).
///
/// ```
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// use magnus::{RString, rb_sys::AsRawValue};
///
/// let foo = RString::new("foo");
/// let bar = RString::new("bar");
///
/// unsafe { rb_sys::rb_str_buf_append(foo.as_raw(), bar.as_raw()) };
///
/// assert_eq!(foo.to_string().unwrap(), "foobar");
/// ```
fn as_raw(self) -> VALUE;
}
/// Converts from a raw [`VALUE`] to a [`Value`].
pub trait FromRawValue {
/// Convert [`rb_sys::VALUE`](VALUE) to [`magnus::Value`](Value).
/// # Safety
///
/// You must only supply a valid [`VALUE`] obtained from [rb-sys](rb_sys) to
/// this function. Using a invalid [`Value`] produced from this function will
/// void all saftey guarantees provided by Magnus.
///
/// ```
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// use magnus::{RString, Value, rb_sys::FromRawValue};
///
/// let raw_value = unsafe { rb_sys::rb_str_new("foo".as_ptr() as *mut _, 3) };
///
/// assert_eq!(unsafe { Value::from_raw(raw_value) }.to_string(), "foo");
/// ```
unsafe fn from_raw(value: VALUE) -> Self;
}
impl AsRawValue for Value {
fn as_raw(self) -> VALUE {
self.as_rb_value()
}
}
impl FromRawValue for Value {
unsafe fn from_raw(val: VALUE) -> Value {
Value::new(val.into())
}
}
/// Trait to convert a [`Id`] to a raw [`ID`].
pub trait AsRawId {
/// Convert [`magnus::value::Id`](Id) to [`rb_sys::ID`](ID).
///
/// ```
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// use magnus::{Symbol, value::Id, rb_sys::{AsRawId, FromRawId}};
///
/// let foo: Id = Symbol::new("foo").into();
/// let raw = foo.as_raw();
/// let from_raw_val: Symbol = unsafe { Id::from_raw(raw) }.into();
///
/// assert_eq!(from_raw_val.inspect(), ":foo");
/// ```
fn as_raw(self) -> ID;
}
/// Trait to convert from a raw [`ID`] to an [`Id`].
pub trait FromRawId {
/// Convert [`rb_sys::ID`](ID) to [`magnus::value::Id`](ID).
///
/// # Safety
///
/// You must only supply a valid, non-zero [`ID`] obtained from [rb-sys](rb_sys) to this
/// function. Using a invalid [`Id`] produced from this function will void all
/// saftey guarantees provided by Magnus.
///
/// ```
/// # let _cleanup = unsafe { magnus::embed::init() };
///
/// use magnus::{Symbol, value::Id, rb_sys::{FromRawId, AsRawId}};
/// use std::convert::TryInto;
///
/// let foo: Id = Symbol::new("foo").into();
/// let from_raw_val: Symbol = unsafe { Id::from_raw(foo.as_raw()) }.into();
///
/// assert_eq!(from_raw_val.inspect(), ":foo");
/// ```
unsafe fn from_raw(id: ID) -> Self;
}
impl AsRawId for Id {
fn as_raw(self) -> ID {
self.as_rb_id()
}
}
impl FromRawId for Id {
unsafe fn from_raw(id: ID) -> Id {
Id::new(id.into())
}
}
/// Calls the given closure, catching all cases of unwinding from Ruby
/// returning them as an [`Error`].
///
/// The most common will be exceptions, but this will also catch `throw`,
/// `break`, `next`, `return` from a block, etc.
///
/// All functions exposed by Magnus that call Ruby in a way that may unwind
/// already use this internally, this should only be required to wrap functions
/// from [rb-sys](rb_sys).
pub fn protect<F>(func: F) -> Result<VALUE, Error>
where
F: FnOnce() -> VALUE,
{
error::protect(|| Value::new(func())).map(|v| v.as_rb_value())
}
/// Attempts to catch cases of Rust unwinding, converting to a fatal [`Error`].
///
/// This should not be used to catch and discard panics.
///
/// This function can be used to ensure Rust panics do not cross over to Ruby.
/// This will convert a panic to a Ruby fatal [`Error`] that can then be used
/// to safely terminate Ruby.
///
/// All functions exposed by Magnus that allow Ruby to call Rust code already
/// use this internally, this should only be required to wrap
/// functions/closures given directly to [rb-sys](rb_sys).
pub fn catch_unwind<F, T>(func: F) -> Result<T, Error>
where
F: FnOnce() -> T + UnwindSafe,
{
std::panic::catch_unwind(func).map_err(Error::from_panic)
}
/// Resumes an [`Error`] previously caught by [`protect`].
///
/// All functions exposed by Magnus where it is safe to resume an error use
/// this internally to automatically convert returned errors to raised
/// exceptions. This should only be required to in functions/closures given
/// directly to [rb-sys](rb_sys).
///
/// # Safety
///
/// Beware this function does not return and breaks the normal assumption that
/// Rust code does not unwind during normal behaviour. This can break
/// invariants in code that assumes unwinding only happens during terminating
/// panics.
///
/// If possible, only call this at the very end of a function/closure that is
/// directly called by Ruby, not other Rust code, and ensure all other values
/// in scope have been dropped before calling this function.
pub unsafe fn resume_error(e: Error) -> ! {
raise(e)
}
/// Convert [`magnus::Value`](Value) to [`rb_sys::VALUE`].
#[deprecated(since = "0.4.0", note = "please use `Value::as_raw` instead")]
pub fn raw_value(val: Value) -> VALUE {
val.as_raw()
}
/// Convert [`rb_sys::VALUE`] to [`magnus::Value`](Value).
///
/// # Safety
///
/// You must only supply a valid [`VALUE`] obtained from [rb-sys](rb_sys) to
/// this function. Using a invalid [`Value`] produced from this function will
/// void all saftey guarantees provided by Magnus.
#[deprecated(since = "0.4.0", note = "please use `Value::from_raw` instead")]
pub unsafe fn value_from_raw(val: VALUE) -> Value {
Value::from_raw(val)
}
/// Convert [`magnus::value::Id`](Id) to [`rb_sys::ID`].
#[deprecated(since = "0.4.0", note = "please use `Id::as_raw` instead")]
pub fn raw_id(id: Id) -> ID {
id.as_raw()
}
/// Convert [`rb_sys::ID`] to [`magnus::value::Id`](Id).
///
/// # Safety
///
/// You must only supply a valid [`ID`] obtained from [rb-sys](rb_sys) to this
/// function. Using a invalid [`Id`] produced from this function will void all
/// saftey guarantees provided by Magnus.
#[deprecated(since = "0.4.0", note = "please use `Id::from_raw` instead")]
pub unsafe fn id_from_raw(id: ID) -> Id {
Id::from_raw(id)
}
#[cfg(test)]
mod tests {
use crate::{
class,
rb_sys::{AsRawId, FromRawId},
value::Id,
Module, RArray, RClass, Symbol,
};
#[test]
fn roundtrip_all_symbols() {
let _cleanup = unsafe { magnus::embed::init() };
let sym_class: RClass = class::object().const_get("Symbol").unwrap();
let symbols: RArray = sym_class.funcall("all_symbols", ()).unwrap();
for sym in symbols.each() {
let sym: Symbol = sym.unwrap().try_convert().unwrap();
let id: Id = sym.into();
assert_eq!(id, unsafe { Id::from_raw(id.as_raw()) });
}
}
}