Updates to Function design

This commit adds several updates to the Function implementation

* bind_first and bind_last both work
* APIs changed to snake_case
* atomic_incr and atomic_decr are now used instead of Cortex-M3+ primitives
* The first bits of documentation have been added

Author: bremoran

core-util/v2/detail/allocators.hpp

@@ -38,6 +38,23 @@ class ContainerAllocator : public mbed::util::ExtendablePoolAllocator {
     }
 };
 
+#if YOTTA_CONFIG_CORE_UTIL_FUNCTIONAL_FUNCTOR_SIZE
+#define FUNCTOR_SIZE YOTTA_CONFIG_CORE_UTIL_FUNCTIONAL_FUNCTOR_SIZE
+#else
+/*
+ * Optimization note: This size was chosen to allow a Function to bind a DNS response.
+ * 4 bytes for the vtable pointers
+ * 4 bytes for the base Function
+ * 128/8 bytes for an IPv6 address
+ * 4 bytes for a char* pointer.
+ * 4 bytes of padding to round out to 8-byte alignment.
+ *
+ * This size should be optimized further by examining application requirements.
+ */
+#define FUNCTOR_SIZE (4 + 4 + (128/8) + 4 + 4)
+#endif
+
+
 extern ContainerAllocator StaticFPAllocator;
 extern ContainerAllocator MemberFPAllocator;
 extern ContainerAllocator FunctorFPAllocator;

core-util/v2/detail/capture.hpp

@@ -40,16 +40,13 @@ struct generator<0, S...> {
 } // namespace index
 
 template <typename FunctionType, ContainerAllocator & Allocator, typename... CapturedTypes>
-class CapturedArguments;
+class CaptureFirst;
 
 template <typename ReturnType, typename... ArgTypes, ContainerAllocator & Allocator, typename... CapturedTypes>
-class CapturedArguments <ReturnType(ArgTypes...), Allocator, CapturedTypes...>
+class CaptureFirst <ReturnType(ArgTypes...), Allocator, CapturedTypes...>
         : public FunctionInterface <ReturnType(ArgTypes...)> {
 public:
-    // CapturedArguments(Function<ReturnType(CapturedTypes..., ArgTypes...)> & f, CapturedTypes&&... CapturedArgs) :
-    //     f(f), storage(CapturedArgs...)
-    // {}
-    CapturedArguments(const std::tuple<CapturedTypes...>& t, Function<ReturnType(CapturedTypes..., ArgTypes...)>& f):
+    CaptureFirst(const std::tuple<CapturedTypes...>& t, Function<ReturnType(CapturedTypes..., ArgTypes...)>& f):
         f(f), storage(t)
     {}
 
@@ -61,13 +58,13 @@ class CapturedArguments <ReturnType(ArgTypes...), Allocator, CapturedTypes...>
         return f(forward<CapturedTypes>(std::get<S>(storage))..., forward<ArgTypes>(Args)...);
     }
 
-    virtual ContainerAllocator * getAllocator() {
+    virtual ContainerAllocator * get_allocator() {
         return & Allocator;
     }
 protected:
     /*
      * Future Optimization Note: It is possible to reduce memory consumption and call
-     * overhead by making CapturedArguments inherit from each of the FunctionInterface
+     * overhead by making CaptureFirst inherit from each of the FunctionInterface
      * types, rather than just from FunctionInterface.
      *
      * In this case, however, a smarter allocator would help
@@ -76,19 +73,73 @@ class CapturedArguments <ReturnType(ArgTypes...), Allocator, CapturedTypes...>
     std::tuple<CapturedTypes...> storage;
 };
 
-template <typename FunctionType, typename... ToRemove> struct RemoveArgs {};
+template <typename FunctionType, ContainerAllocator & Allocator, typename... CapturedTypes>
+class CaptureLast;
+
+template <typename ReturnType, typename... ArgTypes, ContainerAllocator & Allocator, typename... CapturedTypes>
+class CaptureLast <ReturnType(ArgTypes...), Allocator, CapturedTypes...>
+        : public FunctionInterface <ReturnType(ArgTypes...)> {
+public:
+    CaptureLast(Function<ReturnType(ArgTypes..., CapturedTypes...)> & f, CapturedTypes&&... CapturedArgs) :
+        f(f), storage(CapturedArgs...)
+    {}
+
+    virtual ReturnType operator () (ArgTypes&&... Args) {
+        return idxcall(typename index::generator<sizeof...(CapturedTypes)>::type(), forward<ArgTypes>(Args)...);
+    }
+    template <size_t... S>
+    inline ReturnType idxcall(index::sequence<S...>,  ArgTypes&&... Args) {
+        return f(forward<ArgTypes>(Args)..., forward<CapturedTypes>(std::get<S>(storage))...);
+    }
+
+    virtual ContainerAllocator * get_allocator() {
+        return & Allocator;
+    }
+protected:
+
+    Function<ReturnType(ArgTypes..., CapturedTypes...)> & f;
+    std::tuple<CapturedTypes...> storage;
+};
+
+template <typename FunctionType, typename... ToRemove> struct RemoveFirstArgs {};
 
 template <typename ReturnType, typename... ArgTypes>
-struct RemoveArgs <ReturnType(ArgTypes...)> {
+struct RemoveFirstArgs <ReturnType(ArgTypes...)> {
     typedef Function<ReturnType(ArgTypes...)> type;
 };
 
 template <typename ReturnType, typename RemovedArg, typename... ArgTypes, typename ToRemove0, typename... ToRemove>
-struct RemoveArgs <ReturnType(RemovedArg, ArgTypes...), ToRemove0, ToRemove...> {
+struct RemoveFirstArgs <ReturnType(RemovedArg, ArgTypes...), ToRemove0, ToRemove...> {
     static_assert(std::is_same<RemovedArg, ToRemove0>::value, "Type mismatch in argument removal");
-    typedef typename RemoveArgs<ReturnType(ArgTypes...), ToRemove...>::type type;
+    typedef typename RemoveFirstArgs<ReturnType(ArgTypes...), ToRemove...>::type type;
 };
 
+template <typename FunctionType0, typename FunctionType1, typename... RemoveTypes> struct RemoveLastArgs;
+
+template <typename ReturnType, typename... Types, typename... RemoveTypes>
+struct RemoveLastArgs <ReturnType(Types...), ReturnType(), RemoveTypes...> {
+    using type = void;
+};
+
+template <typename ReturnType, typename... Types0, typename Transfer1, typename... Types1, typename... RemoveTypes>
+struct RemoveLastArgs <ReturnType(Types0...), ReturnType(Transfer1, Types1...), RemoveTypes...> {
+    using type = typename std::conditional<
+        std::is_same<std::tuple<Types1...>,std::tuple<RemoveTypes...> >::value,
+        Function<ReturnType(Types0..., Transfer1)>,
+        typename RemoveLastArgs<ReturnType(Types0..., Transfer1), ReturnType(Types1...), RemoveTypes...>::type
+    >::type;
+};
+
+template <typename ReturnType, typename... ArgTypes, typename... ParentTypes, typename... CapturedTypes>
+Function<ReturnType(ArgTypes...)> bind_last(Function<ReturnType(ArgTypes...)> &&, Function<ReturnType(ParentTypes...)>& f, CapturedTypes... CapturedArgs) {
+    using CaptureFP = CaptureLast<ReturnType(ArgTypes...), FunctorFPAllocator, CapturedTypes...>;
+    static_assert(sizeof(CaptureFP) <= FUNCTOR_SIZE, "Size of bound arguments is too large" );
+    CaptureFP * newf = reinterpret_cast<CaptureFP *>(detail::FunctorFPAllocator.alloc());
+    new(newf) CaptureFP(f,forward<CapturedTypes>(CapturedArgs)...);
+    return Function<ReturnType(ArgTypes...)>(static_cast<FunctionInterface<ReturnType(ArgTypes...)>*>(newf));
+}
+
+
 } // namespace detail
 } // namespace functional
 #endif // FUNCTIONAL_DETAIL_CAPTURE_HPP

core-util/v2/detail/functor.hpp

@@ -35,7 +35,7 @@ class FunctorContainer <F, ReturnType(ArgTypes...), Allocator> : public Function
     virtual ReturnType operator () (ArgTypes&&... Args) {
         return f(detail::forward<ArgTypes>(Args)...);
     }
-    virtual ContainerAllocator * getAllocator() {
+    virtual ContainerAllocator * get_allocator() {
         return &Allocator;
     }
 

core-util/v2/detail/interface.hpp

@@ -16,7 +16,7 @@
 #ifndef FUNCTIONAL_V2_DETAIL_INTERFACE_HPP
 #define FUNCTIONAL_V2_DETAIL_INTERFACE_HPP
 
-#include "cmsis.h"
+#include "core-util/atomic_ops.h"
 namespace functional {
 namespace detail {
 template <typename FunctionType>
@@ -33,23 +33,17 @@ class FunctionInterface <ReturnType(ArgTypes...)> {
 public:
     FunctionInterface() : refcnt(0) {}
     virtual ReturnType operator () (ArgTypes&&... Args) = 0;
-    bool inc() {
-        uint32_t tmp;
-        do {
-            tmp = __LDREXW(&refcnt) + 1;
-        } while (__STREXW(tmp, &refcnt));
-        return true;
+    virtual ContainerAllocator *get_allocator() = 0;
+    inline uint32_t inc()
+    {
+        return mbed::util::atomic_incr(&refcnt, 1ul);
     }
-    bool dec() {
-        uint32_t tmp;
-        do {
-            tmp = __LDREXW(&refcnt) - 1;
-        } while (__STREXW(tmp, &refcnt));
-        return tmp == 0;
+    inline uint32_t dec()
+    {
+        return mbed::util::atomic_decr(&refcnt, 1ul);
     }
-    virtual ContainerAllocator *getAllocator() = 0;
 protected:
-    volatile uint32_t refcnt;
+    uint32_t refcnt;
 };
 
 } // namespace detail

core-util/v2/detail/member.hpp

@@ -34,7 +34,7 @@ class MemberContainer <C, ReturnType(ArgTypes...)> : public FunctionInterface <R
     virtual ReturnType operator () (ArgTypes&&... Args) {
         return (obj->*fp)(forward<ArgTypes>(Args)...);
     }
-    ContainerAllocator * getAllocator() {
+    ContainerAllocator * get_allocator() {
         return & MemberFPAllocator;
     }
 

core-util/v2/detail/static.hpp

@@ -33,7 +33,7 @@ class StaticContainer <ReturnType(ArgTypes...)> : public FunctionInterface <Retu
     virtual ReturnType operator () (ArgTypes&&... Args) {
         return fp(forward<ArgTypes>(Args)...);
     }
-    virtual ContainerAllocator * getAllocator() {
+    virtual ContainerAllocator * get_allocator() {
         return & StaticFPAllocator;
     }
 

core-util/v2/functional.hpp

@@ -1,5 +1,5 @@
 /* mbed Microcontroller Library
- * Copyright (c) 2006-2015 ARM Limited
+ * Copyright (c) 2006-2016 ARM Limited
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,15 +18,15 @@
 
 /**
  * \file functional.hpp
- * \brief A library that provides function containers, allocated by arbitrary allocators
+ * \brief A library that provides a ```std::function```-like interface for containing reference to callables.
  *
- * # Function
- * Function is the primary API for functional.hpp
- * Function derives from a smart pointer to a functor.
- * Function contains almost entirely inline APIs
- *
- * Functor is a callable class.
+ * The primary API for containing and referring to callables is ```Function```. APIs in the ```detail``` namespace
+ * should not be invoked directly.
  *
+ * In order to maintain compatibility with existing code, ```Function``` is intended to be duck-type compatible with
+ * the ```FunctionPointer``` family of classes, but it is intentionally not named the same way. A family of
+ * compatibility classes is provided to support conversion from ```FunctionPointer``` code to ```Function```.
+ * These compatibility classes will be deprecated in an upcoming release.
  */
 
 #include <string.h>
@@ -35,7 +35,7 @@
 #include <new>
 #include <utility>
 #include <type_traits>
-
+#include "core-util/atomic_ops.h"
 
 namespace functional {
 template <typename FunctionType>
@@ -52,11 +52,36 @@ class Function;
 #include "detail/capture.hpp"
 
 namespace functional {
-
+/**
+ * Superficially, ```Function``` is intented to appear similar to ```std::function```. However, ```Function``` has a
+ * number of key differences. ```Function``` uses reference counting to limit the copying of large callable objects,
+ * such as lambdas with large capture lists or ```Function```s with large or many arguments. ```Function``` also uses
+ * pool allocation so that objects can be created in interrupt context without using ```malloc()```. These choices are
+ * to overcome two specific limitations of ```std::function```
+ *
+ * 1. Copy-constructing a functor requires copy-constructing its member objects. In the case of lambdas, this means
+ * copy-constructing the lambda captures. lambda captures are not guaranteed to have reentrant copy constructors, so
+ * lambdas cannot be copy-constructed in interrupt context. Therefore, functors must be created in dynamic memory and
+ * only pointers to functors can be used.
+ * 2. Due to 1. creating a functor requires dynamic memory allocation, however malloc is not permitted in interrupt
+ * context. As a result functors must be pool allocated.
+ * 3. In order to simplify memory management of functors and due to 1. and 2., functors are reference-counted.
+ */
 template <typename ReturnType, typename... ArgTypes>
 class Function <ReturnType(ArgTypes...)> {
 public:
+    /**
+     * The empty constructor.
+     * Since ```Function``` only contains a single pointer, only a null assignment is necessary.
+     */
     Function() : ref(nullptr) {}
+    Function(detail::FunctionInterface<ReturnType(ArgTypes...)> *f) {
+        ref = f;
+        if (ref) {
+            ref->inc();
+        }
+    }
+
     Function(ReturnType (*f)(ArgTypes...)) {
         typedef detail::StaticContainer<ReturnType(ArgTypes...)> staticFP;
         staticFP * newf = reinterpret_cast<staticFP *>(detail::StaticFPAllocator.alloc());
@@ -82,6 +107,7 @@ class Function <ReturnType(ArgTypes...)> {
         *this = func;
     }
 
+
     //Optimization Note: use template metaprogramming to select one of three allocator pools
     template <typename F>
     Function(const F &f) {
@@ -97,33 +123,59 @@ class Function <ReturnType(ArgTypes...)> {
         *this = func;
     }
     Function(const Function & f): ref(f.ref) {
-        ref && ref->inc();
+        if(ref) {
+            ref->inc();
+        }
     }
 
     template <typename... CapturedTypes, typename... ParentArgTypes>
     Function(std::tuple<CapturedTypes...>& t, Function<ReturnType(ParentArgTypes...)>& f) {
-        typedef typename detail::CapturedArguments<ReturnType(ArgTypes...), detail::FunctorFPAllocator, CapturedTypes...> CaptureFP;
-        static_assert(sizeof(CaptureFP) <= 40, "Size of bound arguments is too large" );
+        typedef typename detail::CaptureFirst<ReturnType(ArgTypes...), detail::FunctorFPAllocator, CapturedTypes...> CaptureFP;
+        static_assert(sizeof(CaptureFP) <= FUNCTOR_SIZE, "Size of bound arguments is too large" );
         CaptureFP * newf = reinterpret_cast<CaptureFP *>(detail::FunctorFPAllocator.alloc());
         new(newf) CaptureFP(t, f);
         ref = newf;
         ref->inc();
     }
 
+    // Optimization note: This should be changed to use the same constructor as bind_last.
     template<typename... CapturedTypes>
-    typename detail::RemoveArgs<ReturnType(ArgTypes...), CapturedTypes...>::type bind(CapturedTypes... CapturedArgs) {
+    typename detail::RemoveFirstArgs<ReturnType(ArgTypes...), CapturedTypes...>::type bind_first(
+        CapturedTypes... CapturedArgs)
+    {
         std::tuple<CapturedTypes...> t(detail::forward<CapturedTypes>(CapturedArgs)...);
-        typename detail::RemoveArgs<ReturnType(ArgTypes...), CapturedTypes...>::type f(t,*this);
+        typename detail::RemoveFirstArgs<ReturnType(ArgTypes...), CapturedTypes...>::type f(t,*this);
+        return f;
+    }
+
+    template<typename... CapturedTypes>
+    typename detail::RemoveLastArgs<ReturnType(),ReturnType(ArgTypes...),CapturedTypes...>::type bind_last(CapturedTypes... CapturedArgs)
+    {
+        using ReturnFP = typename detail::RemoveLastArgs<ReturnType(),ReturnType(ArgTypes...),CapturedTypes...>::type;
+        static_assert(std::is_same<ReturnFP, functional::Function<void(int,int)> >::value, "oops");
+        ReturnFP f(detail::bind_last(ReturnFP(), *this, detail::forward<CapturedTypes>(CapturedArgs)...));
         return f;
     }
 
-    ~Function() {
-        ref && ref->dec() && ref->getAllocator()->free(ref);
+    ~Function()
+    {
+        if (ref) {
+            if (ref->dec() == 0) {
+                ref->get_allocator()->free(ref);
+            }
+        }
     }
-    Function & operator = (const Function & rhs) {
-        ref && ref->dec() && ref->getAllocator()->free(ref);
+    Function & operator = (const Function & rhs)
+    {
+        if (ref) {
+            if (ref->dec() == 0) {
+                ref->get_allocator()->free(ref);
+            }
+        }
         ref = rhs.ref;
-        ref && ref->inc();
+        if(ref) {
+            ref->inc();
+        }
     }
     inline ReturnType operator () (ArgTypes&&... Args) {
         return (*ref)(detail::forward<ArgTypes>(Args)...);

source/v2/functional.cpp

@@ -53,12 +53,6 @@
 #define FUNCTORFP_GROWBY FUNCTORFP_INITIAL
 #endif
 
-#if YOTTA_CONFIG_CORE_UTIL_FUNCTIONAL_FUNCTOR_SIZE
-#define FUNCTOR_SIZE YOTTA_CONFIG_CORE_UTIL_FUNCTIONAL_FUNCTOR_SIZE
-#else
-#define FUNCTOR_SIZE (sizeof(MemberContainer<UnknownClass,void()>) + sizeof(void*) * 3)
-#endif
-
 namespace functional {
 namespace detail {
 const UAllocTraits_t NeverFreeTrait = {.flags = UALLOC_TRAITS_NEVER_FREE};