[RFC] explicit Context parameter

[japaric]

Summary

Have all handlers take a Context argument as first parameter.

Motivation

Be less magical. Currently values like resources, spawn and schedule are
directly injected into the value namespace of each handler. This RFC proposes
packing those values in a Context struct which appears in the signature of
each handler. See below:

// today
#[task(resources = [..], spawn = [..], schedule = [..])]
fn foo() {
    let foo = resources.FOO;
    spawn.bar().ok();
    schedule.baz().ok();
}

// with this RFC
#[task(resources = [..], spawn = [..], schedule = [..])]
fn foo(c: foo::Context) {
    let foo = c.resources.FOO;
    c.spawn.bar().ok();
    c.schedule.baz().ok();

    // spawn.bar().ok(); //~ ERROR value `spawn` is not in scope
}

This also makes writing trampolines much easier:

#[task(resources = [..], spawn = [..], schedule = [..])]
fn foo(c: foo::Context) {
    some::module::function(c)
}

Of course, the layout of Context is still auto-generated so which fields are
available in this particular Context remains more or less a mystery -- this
RFC doesn't help with that.

Design

All handlers now require that their first parameter is $handler_name::Context.
Tasks that take inputs will have their inputs appear as second, third, etc.
parameters.

#[app]
const APP: () = {
    // ..

    #[init(resources = [..], spawn = [..], scheduled = [..])]
    fn init(c: init::Context) -> init::LateResources {
        // ..
    }

    #[idle(resources = [..], spawn = [..], scheduled = [..])]
    fn idle(c: idle::Context) -> ! {
        // ..
    }

    // task with no input
    #[task(resources = [..], spawn = [..], schedule = [..])]
    fn foo(c: foo::Context) {
        // ..
    }

    // task with one input
    #[task(resources = [..], spawn = [..], schedule = [..])]
    fn bar(c: bar::Context, input: i32) {
        // ..
    }

    // task with two inputs
    #[task(resources = [..], spawn = [..], schedule = [..])]
    fn baz(c: baz::Context, first: i32, second: i64) {
        // ..
    }

    // task with empty context
    #[task]
    fn quux(c: quux::Context) {
         // ^ parameter is still required in this case
    }
};

Alternatives

In addition to this change we can also flatten resources into
$handler::Context , effectively removing the need for the resources. prefix.

// the main proposal
#[task(resources = [..])]
fn foo(c: foo::Context) {
    c.resources.FOO.lock(|foo| /* .. */);
}

// with this extension
#[task(resources = [..])]
fn foo(c: foo::Context) {
    c.FOO.lock(|foo| /* .. */);
}

Note that this extension does not run into the drawbacks that plague RFC #146.

Drawbacks

Application authors would have to write more code: the signature of handlers are
longer and accessing resources and spawning / scheduling tasks requires a
$context. prefix per access / invocation (though all those can be replaced
with some de-structuring at the beginning of the handler).

[perlindgren]

Hi Good job. I think this is preferable to the current implementation. Best Per

…

________________________________ Från: Jorge Aparicio <notifications@github.com> Skickat: den 19 februari 2019 17:55:09 Till: japaric/cortex-m-rtfm Kopia: Subscribed Ämne: [japaric/cortex-m-rtfm] [RFC] explicit `Context` parameter (#155) Summary Have all handlers take a Context argument as first parameter. Motivation Be less magical. Currently values like resources, spawn and schedule are directly injected into the value namespace of each handler. This RFC proposes packing those values in a Context struct which appears in the signature of each handler. See below: // today #[task(resources = [..], spawn = [..], schedule = [..])] fn foo() { let foo = resources.FOO; spawn.bar().ok(); schedule.baz().ok(); } // with this RFC #[task(resources = [..], spawn = [..], schedule = [..])] fn foo(c: foo::Context) { let foo = c.resources.FOO; c.spawn.bar().ok(); c.schedule.baz().ok(); // spawn.bar().ok(); //~ ERROR value `spawn` is not in scope } This also makes writing trampolines much easier: #[task(resources = [..], spawn = [..], schedule = [..])] fn foo(c: foo::Context) { some::module::function(c) } Of course, the layout of Context is still auto-generated so which fields are available in this particular Context remains more or less a mystery -- this RFC doesn't help with that. Design All handlers now require that their first parameter is $handler_name::Context. Tasks that take inputs will have their inputs appear as second, third, etc. parameters. #[app] const APP: () = { // .. #[init(resources = [..], spawn = [..], scheduled = [..])] fn init(c: init::Context) -> init::LateResources { // .. } #[idle(resources = [..], spawn = [..], scheduled = [..])] fn idle(c: idle::Context) -> ! { // .. } // task with no input #[task(resources = [..], spawn = [..], schedule = [..])] fn foo(c: foo::Context) { // .. } // task with one input #[task(resources = [..], spawn = [..], schedule = [..])] fn bar(c: bar::Context, input: i32) { // .. } // task with two inputs #[task(resources = [..], spawn = [..], schedule = [..])] fn baz(c: baz::Context, first: i32, second: i64) { // .. } // task with empty context #[task] fn quux(c: quux::Context) { // ^ parameter is still required in this case } }; Alternatives In addition to this change we can also flatten resources into $handler::Context , effectively removing the need for the resources. prefix. // the main proposal #[task(resources = [..])] fn foo(c: foo::Context) { c.resources.FOO.lock(|foo| /* .. */); } // with this extension #[task(resources = [..])] fn foo(c: foo::Context) { c.FOO.lock(|foo| /* .. */); } Note that this extension does not run into the drawbacks that plague RFC #146<https://github.com/japaric/cortex-m-rtfm/issues/146>. Drawbacks Application authors would have to write more code: the signature of handlers are longer and accessing resources and spawning / scheduling tasks requires a $context. prefix per access / invocation (though all those can be replaced with some de-structuring at the beginning of the handler). — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub<https://github.com/japaric/cortex-m-rtfm/issues/155>, or mute the thread<https://github.com/notifications/unsubscribe-auth/AD5naJGe_8X5Td8T4uwARERzAKjnPdmZks5vPCxtgaJpZM4bDav->. {"api_version":"1.0","publisher":{"api_key":"05dde50f1d1a384dd78767c55493e4bb","name":"GitHub"},"entity":{"external_key":"github/japaric/cortex-m-rtfm","title":"japaric/cortex-m-rtfm","subtitle":"GitHub repository","main_image_url":"https://github.githubassets.com/images/email/message_cards/header.png","avatar_image_url":"https://github.githubassets.com/images/email/message_cards/avatar.png","action":{"name":"Open in GitHub","url":"https://github.com/japaric/cortex-m-rtfm"}},"updates":{"snippets":[{"icon":"DESCRIPTION","message":"[RFC] explicit `Context` parameter (#155)"}],"action":{"name":"View Issue","url":"https://github.com/japaric/cortex-m-rtfm/issues/155"}}} [ { "@context": "http://schema.org", "@type": "EmailMessage", "potentialAction": { "@type": "ViewAction", "target": "https://github.com/japaric/cortex-m-rtfm/issues/155", "url": "https://github.com/japaric/cortex-m-rtfm/issues/155", "name": "View Issue" }, "description": "View this Issue on GitHub", "publisher": { "@type": "Organization", "name": "GitHub", "url": "https://github.com" } } ]

[TeXitoi]

Another alternative would be to have 1 parameter per "context" attribute, i.e.:

#[app]
const APP: () = {
    // ..

    #[init(resources = [..], spawn = [..], scheduled = [..])]
    fn init(r: init::Resources, s: init::Spawn, sch: init::Scheduled) -> init::LateResources {
        // ..
    }

    #[idle(resources = [..], spawn = [..])]
    fn idle(r: idle::Resources, s: idle::Spawn) -> ! {
        // ..
    }

    // task with no input
    #[task(resources = [..])]
    fn foo(r: foo::Resources) {
        // ..
    }

    // task with one input
    #[task(resources = [..], spawn = [..], schedule = [..])]
    fn bar(c: bar::Resources, s: bar::Spawn, sch: bar::Schedule, input: i32) {
        // ..
    }

    // task with two inputs
    #[task(resources = [..])]
    fn baz(r: baz::Resources, first: i32, second: i64) {
        // ..
    }

    // task with empty context
    #[task]
    fn quux() {
    }
};

[TeXitoi]

I'm in favor of this. Not a very strong preference.

My preferences would be: RFC > as now > my alternative > RFC alternative

[MabezDev]

I like this. As much I like the ease of the magicness, I find it quite hard to explain to other people new to Rust where these values come from without having to go down a rabit hole about proc_macro's.

[korken89]

I'd say the presented interface is good, the one shown by @TeXitoi is also good, but this would need changes in the interface every time one changes the task definition.
IMO the first one presented is preferred.

[davidlenfesty]

As someone very new to rust and rust-embedded, this looks very nice to me.

1. it clears up the mystery (slightly, coming from a C embedded background it still kind of seems like magic, given that interrupt vectors don't actually pass context) about where the peripherals structures come from.
2. It (hopefully) gives a useful compile time error when you pass context and it's not explicitly included.

I don't think more code is necessarily always a problem, given that this is an embedded context more specificity is generally nice.

As well, I would say the first interface is better, since adding more code for each piece of context passed seems to be a little redundant. It could be argued that adding the context bit in the first place is redundant but I feel it would be worth it for the compile time error.

[japaric]

It seems everyone who has commented is in favor of the main proposal so I'm going to call for a vote to accept the main proposal of:

#[task(resources = [..])]
fn foo(c: foo::Context) {
    c.resources.FOO.lock(|foo| /* .. */);
}

where resources are grouped in a resources field.

Votes:

• @japaric
• @korken89
• @TeXitoi

[japaric]

This has enough approvals and no concerns have been raised over the course of several weeks so this RFC is now officially accepted. 🎉

[placrosse]

I know this comment is "late in the game", but, since 0.5.0 is not yet released, here goes.

Try to convert a relatively small RTFM app, such as
https://github.com/jonas-schievink/rubble/tree/master/rubble-demo

Take a look at the "before and after" and answer honestly if, in practice, this made an improvement? If you enjoy the verbosity of (original) Java, with its duplicate type information specified everywhere, perhaps. The new Context really, in most cases, seems to be repetitive information from the required annotations.

More noise, without more expressiveness. It made RTFM "less beautiful", IMHO

[perlindgren]

Hi placrosse

The main reason is to make the task signature follow the Rust lang/syntax. If you want to modularise the code, e.g., use the task merely as a trampoline while doing the work somewhere else (like a lib), then its easier to get the signature of the library function right, rather than to guess what the signature should be.

We have experimented back and forth with the API/syntax of the DSL and I/we believe the extra "noise" is well worth it. Rust is extremely noisy in comparison to e.g., OCaml, but the advantage with Rust that is that the explicit signatures makes it clear under which context a function evaluates, and we just pick up on that. (In an older version of RTFM we had the explicit signatures, we removed them in v4 (I even argued for further simplifications, but that would have implied potential name clashes) , and now they are back in v5 as we found the extra clarity is overall beneficial... you just write code once, but read it many times).

Maybe some smart "templating" in an IDE could fill out the signatures, given the task specification?

/Per

[placrosse]

Thank you for your response, Per. I understand what you are saying, and truly appreciate the dialog!

I compared RTFM 0.3 and 0.4, along with 0.5. The difference is the addition of the annotations immediately above the function signature. This was not present in 0.3, with the information about resources, spawns, etc., away from the function, further up in the app macro. In 0.4, this specification moved to be immediately by the function. While reading, the annotated function signature (at least to me) indicates exactly the information required. My "rant" above was from the experience of converting the Rubble demo app to RTFM 0.5. It felt very "boilerplate". In the case of convenience for trampoline use, though, I agree fully that the experience is the exact opposite, with everything automatically packaged together for you. As I make further use of RTFM, I'm certain I'll appreciate this.

Thank you for your work on this framework; it's exciting to see Rust start to mature in the embedded space.