Feature request: implicit init function

[0xDing]

Hi @matsadler ,

Thanks for creating this awesome crate.

When I was writing native extensions for NodeJS with Rust, I had used a crate called nap-rs. Its API design is quite impressive. I thought it might be of some reference value to you. If mangus:init could be implicit or could be defined in separate mods, it could be a big DX boost.

Sorry, this seems like a topic that should be posted in "discussions", but since this repo doesn't have discussions turned on, I had to create an issue.

[matsadler]

Hey! Thanks for the suggestion.

For the implicit init, I looked into napi-rs, and I don't think the solution they are using will translate across directly to Ruby/Magnus. Implementing something like this probably isn't a priority for me at the moment, but I'd welcome contributions.

I'm not sure what you mean by "could be defined in separate mods".

You should be able to do something like:

lib.rs

mod a;
mod b;

// this is the init exposed to Ruby
#[magnus::init]
fn init() -> Result<(), magnus::Error> {
    a::init()?;
    b::init()
}

a.rs

use magnus::{define_module, function, prelude::*, Error};

fn foo() -> String {
    String::from("foo")
}

// this is internal, no need for the #[magnus::init] attribute
pub fn init() -> Result<(), Error> {
    let module = define_module("Foo")?;
    module.define_singleton_method("foo", function!(foo, 0))?;
    Ok()
}

b.rs

use magnus::{define_module, function, prelude::*, Error};

fn bar() -> String {
    String::from("bar")
}

// this is internal, no need for the #[magnus::init] attribute
pub fn init() -> Result<(), Error> {
    let module = define_module("Bar")?;
    module.define_singleton_method("bar", function!(bar, 0))?;
    Ok()
}

---

Here's some notes on what I found looking at napi-rs if you, or anyone else reading this, wants to take a go at implementing something in Magnus.

It looks like napi-rs/napi-rs#696 was where they introduced the feature, and running cargo-expand on one of napi-rs examples is a good way of seeing how it's working.

It looks like for each function something like the following is generated:

// the original function
pub fn example(...) {
    ()
}

extern "C" fn __napi__example(...) -> ... {
    let args = from_napi_value(...);
    let res = example(args);
    to_napi_value_or_raise(res)
}

unsafe fn example_js_function(...) -> ... {
    create_function("example", __napi__example)
}

extern "C" fn __napi_register__example() {
    export("example", example_js_function);
}

// this is generated by the `ctor` crate
#[link_section = "__DATA,__mod_init_func"]
static __napi_register__example___rust_ctor___ctor: unsafe extern "C" fn() = {
    unsafe extern "C" fn __napi_register__example___rust_ctor___ctor() {
        __napi_register__example()
    };
    __napi_register__example___rust_ctor___ctor
};

This just skips an Init function entirely, instead registering a ctor individually for every function.

Ruby can error when defining methods, and I'm not totally sure how you'd handle that in a ctor function. Looking at the source of Ruby's extension loading code, I think it'd be ok to raise in a ctor, but I haven't tried it.

A lot of what napi-rs does in its #[napi] macro Magnus already does, so I think a #[magnus::method] macro would just be a case of emitting something like:

#[ctor]
fn define_example() {
    let class = // get class somehow
    let res = class.define_method(method!(example, 0));
    // handle error somehow
}

However, it is not possible to skip providing an Init function with Ruby.

You could just provide an empty one, although it'd be nice if there was some way to collect up all the functions annotated with something like #[magnus::method], to then use that to generate the init function, but I don't know of anything that would work and that'd I'd be totally happy with.

I guess it'd be possible to write out to a file in proc macro, but I'd much prefer to keep the macros purely as syntax transformations, without side effects.

I don't want to have to wrap everything in an extra mod or a macro_rules macro, I'm also not a fan of having a free floating init!() macro to generate the init function.

An 'inner' attribute (like #![some_name]) that you could apply to the main module seems like a nice idea, but that's currently unstable, so that's out for now.

All the figuring out what kind of method you want to define (public, private, protected, singleton, module_function) on what (existing module, new module, existing class, new class, class nested in module, class nested in class, module nested in module, class inheriting from other class, etc), also dealing with global variables, constants, etc also seems like a lot of work to do before this would be useable in all but the simplest use cases.

[ms-jpq]

kinda related, for magnus::init another consideration is the naming aspect too.

I think its not possible to force ruby to look up a the init function by anything other than the stem part of filename of the .so/.bundle.

Because I need to ship for multi triples, I ended up doing where the build.rs exports a different RVM_INIT_NAME based on the target

#[export_name = env!("RVM_INIT_NAME")]
pub extern "C" fn init_vm() {
  Init_rb();
}

[matsadler]

@ms-jpq the init macro has a name attribute (that I have failed to document, I'll fix that), that'd get you half way there:

#[magnus::init(name = "example-aarch64-apple-darwin")]
fn init() -> Result<(), Error> {
   ...
}

would give Init_example_aarch64_apple_darwin as the final init function exported for Ruby.

However it doesn't look like it'll accept anything other than a literal as the value for the name. I'm not sure if this is a general limitation of this macro syntax, or down to the way I've written the macro. I can investigate.

The code for the macro is here if you'd like to take a look:

magnus/magnus-macros/src/lib.rs

Lines 90 to 108 in b2f2931

	let crate_name = match InitAttributes::from_list(&attr_args) {
	Ok(v) => v.name,
	Err(e) => return TokenStream::from(e.write_errors()),
	};
	let crate_name = match crate_name.or_else(|| std::env::var("CARGO_PKG_NAME").ok()) {
	Some(v) => v,
	None => {
	return Error::new(
	proc_macro2::TokenStream::from(attrs).span(),
	"missing #[magnus] attribute",
	)
	.into_compile_error()
	.into()
	}
	};
	let extern_init_name = Ident::new(
	&format!("Init_{}", crate_name.replace('-', "_")),
	Span::call_site(),
	);

[ms-jpq]

oh sweet, i love u

[ms-jpq]

wait yeah, thats fine tho.

its a niche usecase

[matsadler]

@ms-jpq I looked into it and as far as I can tell being able to use a function-like macro in an attribute macro (like #[export_name = env!("RVM_INIT_NAME")]) is something that's limited to Rust built in attributes, and isn't available to attribute macros generally. So that's a bummer.

The init macro is actually pretty simple though, it expands out to:

fn init() -> Result<(), Error> {
  // your orignial init function
}
#[allow(non_snake_case)]
#[no_mangle]
pub extern "C" fn Init_example() {
    unsafe { magnus::method::Init::new(init).call_handle_error() }
}

So you could forego the macro and just implement it by hand like that (with export_name rather than no_mangle, and that'll probably let you drop the allow(non_snake_case) too).

[ianks]

@ms-jpq Not sure if this is relevant anymore, but instead of baking in the triple you could leverage Rubygems platform support for gems. If you use the rb_sys gem with rake-compiler-dock this is all handled for you.