Reduce Event.h and EventQueue.h using C++11

[kjbracey]

Description

Variadic templates can reduce Event.h from 4,100 lines to 300, and EventQueue.h from 3,400 to 1,000, so 6,000 lines saved total.

End result isn't totally variadic, as we still need specialisations for storing 0-5 values in contexts, but that specialisation is now in exactly one place.

Only change other from switching to variadic templates is using delegating constructors instead of the new (this) trick. That trick is still used in the assignment operator.

Minor documentation correction. It's possible that the separate simplified variadic Doxygen version not be needed now, but I've left it.

Pull request type

[ ] Fix
[X] Refactor
[ ] Target update
[ ] Functionality change
[ ] Docs update
[ ] Test update
[ ] Breaking change

Reviewers

@pan-, @bulislaw, @geky, @evedon

[ciarmcom]

@kjbracey-arm, thank you for your changes.
@bulislaw @geky @pan- @evedon @ARMmbed/mbed-os-core @ARMmbed/mbed-os-maintainers please review.

[kjbracey]

Second commit makes a change to template deduction which I think is required to make all variadic cases work, but it will be a subtle behaviour change. Full details in commit message - review especially from @geky appreciated.

[kjbracey]

Hmm, still have a problem with the template deduction - I see now that if you don't let the passed arguments be freely-typed, any need for conversion makes the (F, any...) (0 conversions) match better than (obj, method(types...), types...) (1 or more args converted).

But then if they're freely typed, I don't see how I can use the variadic form for

template <typename T, typename R, typename... BoundArgTs, typename... ArgTs, typename... ContextArgTs>
Event<void(ArgTs...)> EventQueue::event(T *obj, R(T::*method)(BoundArgTs..., ArgTs...), ContextArgTs... context_args)

There's nothing to associate the number of parameters passed to how many bound args we want. It ends up putting nothing in BoundArgTs and everything in ArgTs.

It may be necessary to do these binding calls non-variadically.

[kjbracey]

I believe the variadic form of this would be:

template <typename F, typename... ContextTypes>
struct context {
    F f;
    std::tuple<ContextTypes...> c;
    
    context(F f, ContextTypes... c)
        : f(f), c(c...) {}

    template <size_t... I, typename... ArgTs>
    void do_call(std::index_sequence<I...>, ArgTs... args)
    {
        f(get<I>(c)..., args...);
    }
    template <typename... ArgTs>
    void operator()(ArgTs... args)
    {
        do_call(std::index_sequence_for<ContextTypes>(), args...);
    }
};

But that would involve writing std::tuple for ARM C 5.

[pan-]

It just requires a small subset of tuple that shouldn't be hard to implement:

template<typename... Ts>
struct Tuple : TupleImpl<std:: index_sequence_for <Ts...>, Ts...>;

template<typename Indexes, typename... Ts>
struct TupleImpl; 

template<size_t... Indexes, typename... Ts>
struct TupleImpl<std::index_sequence<Indexes...>, Ts...> : : TupleLeaf<Indexes, Ts>... { };

template<size_t Index, typename T>
struct TupleLeaf { 
    T value;
    T& get();
};

template<size_t Index, typename T, typename... Ts>
struct nth_element_impl {
    using type = typename nth_element_impl<Index-1, Ts...>::type;
};

template<typename T, typename... Ts>
struct nth_element_impl<0, T, Ts...> {
    using type = T;
};

template<size_t Index, typename... Ts>
using nth_element = typename nth_element_impl<Index, Ts...>::type;

template<size_t index, typename... Ts>
auto get(const Tuple<Ts...>& t) -> nth_element<index, Ts...> { 
    return static_cast<TupleLeaf<index, nth_element<index, Ts...>>>(t).get();
}  

We can do that latter if it is necessary.

[kjbracey]

Don't see any pressing need here - the non-variadic repetition is small and self-contained, and easier to understand.

But I would appreciate any tips on avoiding the bound argument repetition I've just put back, or the (-,C,V,CV) quads on every member function pointer. Those two multiply together nastily.

[pan-]

I think we could use a traits to test the compatibility between the pointer and the function to bind.
Rules are fairly simple:

• ptr const: reject non const member function
• ptr volatile: reject non volatile member function

[kjbracey]

Hmm, I guess maybe you get it nearly for free with is_invocable. (Having paid the cost there).

As I've implemented that now, I'll look at applying it.

[pan-]

It seems to work: https://godbolt.org/z/wGCijo

[kjbracey]

Okay, I've gone back to non-variadic binding, putting back all the type deduction logic as it was. Did it as a separate commit so the interested can still see what didn't work.

If this is the final version, we can squash it all together.

Means an extra 500 lines, but it's still a 5,500 line saving.

[bulislaw]

I generally like the direction, but will leave the detail review for @pan- and @geky

[kjbracey]

@pan-, @geky, this is ready to go.

[pan-]

Looks good to me. We can add optimisations (perfect forwarding can be added to many places) once this is in.

[kjbracey]

Yes, I'll be sending more updates presently.

My immediate priority is to rework "mbed_cxxsupport.h" before it gets locked in for 5.14 - want to get some better structure there. (See #10274 (comment))

[kjbracey]

CI started

[mbed-ci]

Test run: SUCCESS

Summary: 11 of 11 test jobs passed
Build number : 1
Build artifacts

[geky]

Sorry I didn't get a chance to review this, I would general trust @pan- more than me with advanced C++ anyways 😁

Glad these made it in!

I don't know if this is directly related, but someone's broken GitHub's code frequency graph:

[boraozgen]

Are there any examples or tests which use these declarations? I have been struggling to use them to define events with a class method as the handler. Forward declarations seem to be left non-variadic, which makes the compiler to expect one argument in the template. The respective declarations:

mbed-os/events/include/events/Event.h

Lines 34 to 35 in 0db72d0

	template <typename F>
	class Event;

mbed-os/events/include/events/EventQueue.h

Lines 48 to 49 in 0db72d0

	template <typename F>
	class Event;

I found that using mbed::callback with the non-variadic Event type easier anyway. I think some documentation to explain the usage of these constructors would be great for developers like me who are new to modern C++.

[kjbracey]

This PR wasn't introducing any functionality - it was just replacing the existing implementation's multiple 0,1,2,3,4,5 argument binding forms with a variadic equivalent. (I guess the new functionality is that you could now bind 20 arguments...)

You can see examples in the docs here:

https://os.mbed.com/docs/mbed-os/v6.2/apis/scheduling-tutorials.html
https://os.mbed.com/docs/mbed-os/v6.2/apis/eventqueue.html

[kjbracey]

But simplest basic usage for a class method callback would be:

class MyClass {
    void my_event(int);
}

// Somewhere in MyClass:
eventqueue->call_in(5s, this, &MyClass:my_event, 101);

That will call the my_event method in 5 seconds on that event queue, with the argument 101.

[kjbracey]

To make an Event, to avoid having to spell out template parameters, use the helper methods in EventQueue which deduce from arguments, and a helping auto.

auto e = eventqueue->event(this, &MyClass::my_event, 101);

Then e() will queue the event. (Immediately, unless you've set a delay with e.delay()).

That's assuming you want to bind the 101 into the event. If you want to not bind, and specify parameter at call time, then

auto e = eventqueue->event(this, &MyClass::my_event);
e(101);

should work. The variadic stuff should deduce by looking at the prototype of my_event, and the number of binding arguments you provide to EventQueue::event what the resulting function signature of the event is - ie how many remaining arguments you have to pass.

So in the first case e is an Event<void(void)>, in the second it's a Event<void(int)>.

[boraozgen]

Thank you for the detailed explanation. I needed to declare an Event as a class member, which is why I could not use auto. Which is also why I needed to use the constructor (AFAIK).

Therefore I used this approach:

class MyClass
{
    Event<void()> myEvent;
    void myEventHandler();
}

MyClass::MyClass() : myEvent(mbed_event_queue(), mbed::callback(this, &MyClass::myEventHandler))
{
   ...
}

Please correct me if I am wrong.

[kjbracey]

Yes, that also seems fine. I believe in the current implementation they come out as the same thing, because Event relies on Callback internally. If you construct using a callback it uses it directly, else it creates one for you.

(Personally, I've never made much use of Event in my own code - so have little practical experience. I've tended to just use EventQueue.)