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:
RUSTFLAGS=-Awarnings rake compile
It is also possible to ignore errors due to Value no longer being Send + Sync by activating the deprecated-send-sync-value feature:
magnus = { version = "0.6", features = ["deprecated-send-sync-value"] }
This feature is intended purely as a convenience when upgrading and will be removed with the next release.
Functions on Value have moved to the ReprValue trait, It is recommended to import this with use magnus::prelude::*. Magnus' prelude module only imports traits, and does so anonymously, so there is minimal chance of it causing problems.
There are no longer From<T>/Into implementations for Value. In a lot of cases this can be replaced with .as_value(). For 'wrapped' structs you will need to wrap them with Ruby::obj_wrap first. Internally Magnus uses the IntoValue trait, which is available publicly with use magnus::IntoValue.
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.
Value's methods moved to the ReprValue trait.
typed_data::Obj<T> derefs to T so now T's methods can be called
directly on typed_data::Obj<T>.
ReprValue and TryConvert added to magnus::prelude.
typed_data::Cmp, typed_data::Dup and typed_data::Inspect traits to help
with implementing #<=>, #dup & #clone, and #inspect methods for
wrapped structs.
Wrapped data must be Sync to enable frozen_shareable flag.
TypedData::class and TypedData::class_for now take a &Ruby argument.
DataTypeFunctions::mark and DataTypeFunctions::compact now take
&gc::Marker and &gc::Compactor arguments respectively.
Init function marked with #[magnus::init] optionally takes a &Ruby
argument.
Functions bound as Ruby methods with method!() and function!() optionally
take &Ruby as a first argument.
The value returned from embed::init derefs to Ruby.
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 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)
dependabot[bot]
commented
1 year ago
Bumps magnus from 0.5.4 to 0.6.0.
Release notes
Sourced from magnus's releases.
... (truncated)
Changelog
Sourced from magnus's changelog.
... (truncated)
Commits
ef66b6badd 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_argsdocsfd39f11enable keyword args for Proc::calla0dd125update changelog571fa45Merge pull request #80 from adampetro/funcall-kw7ceba7fSupport kwargs with existing methodsDependabot 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 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)