Magnus 0.6.0 makes some breaking API changes to improve thread safety. A handful of fixes and new features are also included.
Magnus is a Rust library providing a high-level easy-to-use interface to the C API of the Ruby programming language. Magnus lets you write Ruby extension libraries (or 'gems') in Rust, or embed Ruby in your Rust program.
Thread Safety
Previous versions of Magnus have ignored thread safety in aid of getting something working, but support for threads and running Rust code outside of the Global VM Lock via rb_thread_call_without_gvl have been common feature requests. This release prepares for the introduction of those features with some breaking API changes.
To this end all APIs that create Ruby objects have been moved to a new Ruby handle which can only be obtained on a Ruby thread. For example RArray::new() becomes Ruby::ary_new(&self) (currently RArray::new() still exists as a wrapper around Ruby::get().unwrap().ary_new()). Default implementations have been removed. Additionally Ruby types are no longer Send & Sync. An Opaque wrapper type can be used to pass Ruby types between threads where they can only be unwrapped on a Ruby thread.
To make getting ahold of the Ruby handle simple, functions bound as Ruby methods with method!() and function!(), along with the function marked with #[magnus::init] optionally take &Ruby as a first argument.
Other API Changes
The minimum supported Rust version is now 1.61.
The bytes-crate and rb-sys-interop features have been renamed to bytes and rb-sys respectively.
Previously all Ruby types, such as RString, RArray, etc Deref'd to Value, allowing Value methods to be called on all Ruby types. This is no longer the case. All Value methods have been moved to the ReprValue trait, which is implemented by Value and all other Ruby types.
This allows typed_data::Obj<T> to Deref to T, turning typed_data::Obj into a 'smart pointer' type that makes advanced use of wrapped data much more pleasant.
The kwargs!() macro and KwArgs type can be used to pass keyword arguments to ReprValue::funcall, et al.
Documentation examples for almost every function
Upgrading
If you encounter a lot of deprecation warnings when upgrading it may be easier to ignore warnings to concentrate on fixing errors, assuming your project is setup with a Rake and a 'compile' task this can be done with:
Ruby 2.6 support requires enabling rb-sys' stable-api-compiled-fallback
feature in your Cargo.toml like so:
rb-sys = { version = "*", default-features = false, features = ["stable-api-compiled-fallback"] }
[0.6.0] - 2023-07-28
Added
value::Opaque can be used to wrap a Ruby type to make it Send + Sync.
value::Lazy lazily initialises a Ruby value so it can be assigned to a
static.
value::OpaqueId is a Send + Sync version of value::Id.
value::LazyId is an Id with a const constructor so can be assigned to a
static and derefs to OpaqueId.
error::OpaqueError is a Send + Sync version of Error.
The #[magnus(opaque_attr_reader)] attribute can be set on Opaque wrapped
fields of a struct when deriving TypedData to generate a method to return
the inner value.
Ruby::init function to initialise Ruby when embedding Ruby in Rust that
runs a function with Ruby initialised, passing &Ruby.
rb_assert!() macro to assert a Ruby expression evaluates to a truthy value.
Class::undef_default_alloc_func to remove a class' allocator function only
if it is Ruby's default allocator function.
Class::obj_alloc and Class::define_alloc_func for allocating an object
without calling initialize, and for defining an allocator function.
RTypedData::wrap_as & typed_data::Obj<T>::wrap_as can be used to
dynamically set the class when wrapping Rust data in a Ruby object. This can
be used to allow wrapped data to be subclassed in Ruby.
Exception::exception_class returns the class of an exception as an
ExceptionClass.
The kwargs!() macro and KwArgs type can be used to pass keyword arguments
to ReprValue::funcall, et al.
Changed
Minimum supported Rust version in now 1.61.
The bytes-crate feature has been renamed to bytes.
The rb-sys-interop feature has been renamed to rb-sys.
Ruby types are no longer Send or Sync. These types can be made Send &
Sync with the deprecated-send-sync-value feature. This feature is meant
to ease upgrading and will be removed with the next release.
Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.
Dependabot commands and options
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
- `@dependabot show ignore conditions` will show all of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
Bumps magnus from 0.5.4 to 0.6.2.
Release notes
Sourced from magnus's releases.
... (truncated)
Changelog
Sourced from magnus's changelog.
... (truncated)
Commits
f33d38afix compile error in bytes featurea6f9c4abump version to 0.6.14014edeupdate changelog3b22ea1Backport #79, Implement rb-sys stable api for RArray and RStringef66b6badd 0.6.0 release date to changelogd8f862fbump version to 0.6.0 before releaseb89ef33remove links to serde-magnuseda98c3don't deprecate eval when disabling friendly-api feature5cc7e6fMerge pull request #81 from adampetro/doc-typod749927Fix typo inArgList::contains_kw_argsdocsDependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting
@dependabot rebase.Dependabot commands and options
You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot show