Port an MBED design to non-MBED - Phase 5: OO Callbacks Simplified

I'm playing with object oriented firmware for embedded controllers.

In this blog I review object oriented callbacks. How to invoke the correct function of the correct object.

The goal of this callback API is to allow "something" to call a function of an object.

This is powerful. An object can have rich context. Performing an operation on it takes a lot of bookkeeping out of your program.

In my examples, callbacks are used when timers (timeouts) fire and when interrupts happen.

You can hook a particular object, and one of its methods to an interrupt or timeout. And when that triggers, it calls the method on that object.

I kept it simple as that. No more context, no parameters.

MBED in pre-5 versions tried to make it as flexible as possible, but that resulted in several thousand lines of templated code.

Since version 5 they have taken a different approach. I took it more to the extreme by just dealing with this single scenario above. Focus.

I am using object pointers cast to uint32_t values. Then cast those back to object pointers later. Some people will frown.

I've used the same template constructs of pre-version5 MBED:

template <typename F>
class Callback;

template <typename R>
class Callback<R()> {

// ...
}

Constructors and destructors. It supports direct creation with a known object and method, or the option to attach object and method later.

The last constructor allows to attach an object, instead of an object pointer cast to an uint32_t.

public:
    /** Create a Callback with a static function
     *  @param func     Static function to attach
     */
    Callback(R(*func)() = 0)
    {
        if (!func) {
            memset(this, 0, sizeof(Callback));
        } else {
            generate(func);
        }
    }

    /** Attach a Callback
     *  @param func     The Callback to attach
     */
    Callback(const Callback<R()> &func)
    {
        if (func._ops) {
            func._ops->move(this, &func);
        }
        _ops = func._ops;
    }

    /** Destroy a callback
     */
    ~Callback()
    {
        if (_ops) {
            _ops->dtor(this);
        }
    }

    /** Create a Callback with a member function
     *  @param obj      Pointer to object to invoke member function on
     *  @param method   Member function to attach
     */
    template<typename T, typename U>
    Callback(U *obj, R(T::*method)())
    {
        generate(method_context<T, R(T::*)()>(obj, method));
    }

private:
    // Dynamically dispatched operations
    const struct ops {
        R(*call)(const void *);
        void (*move)(void *, const void *);
        void (*dtor)(void *);
    } *_ops;

And as last, the methods and members that help with remembering what object  and method to call, and then invoking that ...

public:
// ...
    /** Call the attached function
     */
    R call() const
    {
        return _ops->call(this);
    }

    /** Test if function has been attached
     */
    operator bool() const
    {
        return _ops;
    }
private:
    // Generate operations for function object
    template <typename F>
    void generate(const F &f)
    {
        static const ops ops = {
            &Callback::function_call<F>,
            &Callback::function_move<F>,
            &Callback::function_dtor<F>,
        };

        memset(this, 0, sizeof(Callback));
        new (this) F(f);
        _ops = &ops;
    }

    // Wrappers for functions with context
    template <typename O, typename M>
    struct method_context {
        M method;
        O *obj;

        method_context(O *obj, M method)
            : method(method), obj(obj) {}

        R operator()() const
        {
            return (obj->*method)();
        }
    };

    // Function attributes
    template <typename F>
    static R function_call(const void *p)
    {
        return (*(F *)p)();
    }

    template <typename F>
    static void function_move(void *d, const void *p)
    {
        new (d) F(*(F *)p);
    }

    template <typename F>
    static void function_dtor(void *p)
    {
        ((F *)p)->~F();
    }
// ...
}

... and a helper template (I vastly reduced the ones available in MBED to 1):

/** Create a callback class with type infered from the arguments
 *
 *  @param obj      Optional pointer to object to bind to function
 *  @param method   Member function to attach
 *  @return         Callback with infered type
 */
template<typename T, typename U, typename R>
Callback<R()> callback(U *obj, R(T::*method)())
{
    return Callback<R()>(obj, method);
}

I will have to do a follow up post that shows the difference between the constructors that take a class and method, and those that take an object and method.

For now, it suffices too say that both can do the same.

But the first one requires the callback method to be static and know some internals.

The latter works with common member functions and is object-aware by nature.

/* mbed Microcontroller Library
 * Copyright (c) 2006-2015 ARM Limited
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */