Crate magnus

Source
Expand description

Magnus is a library for writing Ruby extentions in Rust, or running Ruby code from Rust.

§Overview

All Ruby objects are represented by Value. To make it easier to work with values that are instances of specific classes a number of wrapper types are available. These wrappers and Value all implement the ReprValue trait, so share many methods.

Ruby ClassMagnus Type
StringRString
IntegerInteger
FloatFloat
ArrayRArray
HashRHash
SymbolSymbol
ClassRClass
ModuleRModule

When writing Rust code to be called from Ruby the init attribute can be used to mark your init function that Ruby will call when your library is required.

When embedding Ruby in a Rust program, see embed::init for initialising the Ruby VM.

The method macro can be used to wrap a Rust function with automatic type conversion and error handing so it can be exposed to Ruby. The TryConvert trait handles conversions from Ruby to Rust, and anything implementing IntoValue can be returned to Ruby. See the Module and Object traits for defining methods.

Value::funcall can be used to call Ruby methods from Rust.

See the wrap attribute macro for wrapping Rust types as Ruby objects.

§Safety

When using Magnus, in Rust code, Ruby objects must be kept on the stack. If objects are moved to the heap the Ruby GC can not reach them, and they may be garbage collected. This could lead to memory safety issues.

It is not possible to enforce this rule in Rust’s type system or via the borrow checker, users of Magnus must maintain this rule manually.

An example of something that breaks this rule would be storing a Ruby object in a Rust heap allocated data structure, such as Vec, HashMap, or Box. This must be avoided at all costs.

While it would be possible to mark any functions that could expose this unsafty as unsafe, that would mean that almost every interaction with Ruby would be unsafe. This would leave no way to differentiate the really unsafe functions that need much more care to use.

§Examples

use magnus::{function, method, prelude::*, Error, Ruby};

#[magnus::wrap(class = "Euclid::Point", free_immediately, size)]
struct Point {
    x: isize,
    y: isize,
}

impl Point {
    fn new(x: isize, y: isize) -> Self {
        Self { x, y }
    }

    fn x(&self) -> isize {
        self.x
    }

    fn y(&self) -> isize {
        self.y
    }
}

fn distance(a: &Point, b: &Point) -> f64 {
    (((b.x - a.x).pow(2) + (b.y - a.y).pow(2)) as f64).sqrt()
}

#[magnus::init]
fn init(ruby: &Ruby) -> Result<(), Error> {
    let module = ruby.define_module("Euclid")?;
    let class = module.define_class("Point", ruby.class_object())?;
    class.define_singleton_method("new", function!(Point::new, 2))?;
    class.define_method("x", method!(Point::x, 0))?;
    class.define_method("y", method!(Point::y, 0))?;
    module.define_module_function("distance", function!(distance, 2))?;
    Ok(())
}

§Crates that work with Magnus

§C Function Index

This lists all the Ruby C API functions currently implemented, and how they map to Rust functions and methods in Magnus.

Click to show

§A-N

§RARRAY

§RB

§rb_a-rb_arx

§rb_ary

§rb_as-rb_az

§rb_b

§rb_c

§rb_d

§rb_e-rb_enb

§rb_enc

§rb_en-rb_ez

§rb_f

§rb_g

§rb_h

§rb_i-rb_in

§rb_io

§rb_is-rb_iz

§rb_j-rb_k

  • rb_jump_tag: Return Error.

§rb_l

§rb_m

§rb_n

§rb_o

§rb_p

§rb_r

§rb_s-rb_strl

§rb_struct

§rb_str

§rb_st_

§rb_sy-rb_sz

§rb_t

§rb_u

§rb_v-rb_z

§rc-rt

§ruby_

§S-Z

Re-exports§

pub use crate::fiber::Fiber;ruby_gte_3_1
pub use crate::value::Flonum;
pub use crate::class::Class;
pub use crate::class::RClass;
pub use crate::error::Error;
pub use crate::exception::Exception;
pub use crate::exception::ExceptionClass;
pub use crate::module::Attr;
pub use crate::module::Module;
pub use crate::module::RModule;
pub use crate::numeric::Numeric;
pub use crate::r_array::RArray;
pub use crate::r_hash::RHash;
pub use crate::r_regexp::RRegexp;
pub use crate::r_string::RString;
pub use crate::r_struct::RStruct;
pub use crate::symbol::Symbol;
pub use crate::try_convert::TryConvert;
pub use crate::typed_data::DataType;
pub use crate::typed_data::DataTypeFunctions;
pub use crate::typed_data::TypedData;
pub use crate::value::Fixnum;
pub use crate::value::StaticSymbol;
pub use crate::value::Value;

Modules§

block
Types and functions for working with Ruby blocks and Procs.
class
Types and functions for working with Ruby classes.
embedembed
Helpers for use when embedding Ruby in a Rust project.
encoding
Types and functions for working with encodings.
error
Rust types for working with Ruby Exceptions and other interrupts.
exception
Types and functions for working with Ruby exceptions.
fiberruby_gte_3_1
Types and functions for working with Ruby’s Fiber class.
gc
Functions for working with Ruby’s Garbage Collector.
method
Traits for exposing Rust functions as Ruby methods.
module
Types and functions for working with Ruby modules.
numeric
Types and Traits for working with Ruby’s Numeric class.
prelude
Traits that commonly should be in scope.
process
Types for working with processes.
r_array
Types and functions for working with Ruby’s Array class.
r_hash
Types and functions for working with Ruby’s Hash class.
r_regexp
Types for working with Ruby’s Regexp class.
r_string
Types for working with Ruby’s String class.
r_struct
Types and functions for working with Ruby’s Struct class.
rb_sysrb-sys
Functions for interoperability with rb-sys.
scan_args
Types and functions for complex method arguments.
symbol
Types and traits for working with Ruby symbols.
try_convert
Traits for converting from Ruby Values to Rust types.
typed_data
Types and Traits for wrapping Rust types as Ruby objects.
value
Types for working with Ruby’s VALUE type, representing all objects, and ‘immediate’ values such as Fixnum.

Macros§

data_type_builder
Create a new DataTypeBuilder.
eval
Evaluate a literal string of Ruby code with the given local variables.
function
Wrap a Rust function item with Ruby type conversion and error handling, ignoring Ruby’s self argument.
kwargs
Create a KwArgs from Rust key-value mappings. Keys must be string literals, while values can be anything that implements IntoValue.
method
Wrap a Rust function item with Ruby type conversion and error handling.
r_string
Create a RString from a Rust str literal.
rb_assert
Asserts a Ruby expression evaluates to a truthy value.

Structs§

Enumerator
Wrapper type for a Value known to be an instance of Ruby’s Enumerator class.
Float
A type wrapping either a Flonum or an RFloat value.
Integer
A type wrapping either a Fixnum or a RBignum.
KwArgs
Wrapper for RHash intended for use in the tuple implementations of ArgList to indicate that the last argument in the tuple is to be passed as keyword arguments.
Mutex
Wrapper type for a Value known to be an instance of Ruby’s Mutex class.
RBignum
A Value pointer to a RBignum struct, Ruby’s internal representation of large integers.
RComplex
A Value pointer to a RComplex struct, Ruby’s internal representation of complex numbers.
RFile
A Value pointer to a RFile struct, Ruby’s internal representation of IO.
RFloat
A Value pointer to an RFloat struct, Ruby’s internal representation of high precision floating point numbers.
RMatch
A Value pointer to a RMatch struct, Ruby’s internal representation of the MatchData returned from a regex match.
RObject
A Value pointer to a RObject struct, Ruby’s internal representation of generic objects, not covered by the other R* types.
RRational
A Value pointer to a RRational struct, Ruby’s internal representation of rational numbers.
RTypedData
A Value pointer to a RTypedData struct, Ruby’s internal representation of objects that wrap foreign types.
Range
Wrapper type for a Value known to be an instance of Ruby’s Range class.
Ruby
A handle to access Ruby’s API.
Thread
Wrapper type for a Value known to be an instance of Ruby’s Thread class.
Time
Wrapper type for a Value known to be an instance of Ruby’s Time class.

Traits§

ArgList
Trait for types that can be used as an arguments list when calling Ruby methods.
IntoValue
Conversions from Rust types into Value.
IntoValueFromNative
Conversions from Rust types that do not contain Value into Value.
Object
Functions available all non-immediate values.
RArrayArgList
Trait for types that can be used as an arguments list when calling Ruby Procs.

Functions§

backref_getold-api
Returns the result of the most recent regexp match.
call_superold-api
Call the super method of the current method context.
current_receiverold-api
Return the Ruby self of the current method context.
define_classold-api
Define a class in the root scope.
define_errorold-api
Define an exception class in the root scope.
define_global_constold-api
Define a global constant.
define_global_functionold-api
Define a method in the root scope.
define_moduleold-api
Define a module in the root scope.
define_variableold-api
Define a global variable.
eval
Evaluate a string of Ruby code, converting the result to a T.
requireold-api
Finds and loads the given feature if not already loaded.

Attribute Macros§

init
Mark a function as the ‘init’ function to be run for a library when it is required by Ruby code.
wrap
Allow a Rust type to be passed to Ruby, automatically wrapped as a Ruby object.

Derive Macros§

DataTypeFunctions
Derives DataTypeFunctions with default implementations, for simple uses of TypedData.
TypedData
Derives TypedData, allowing the type to be passed to Ruby automatically wrapped as a Ruby object.