Use std::function vs. plain C-style function pointer for callbacks

[ismintis]

By using std::function, you allow C++ clients of your libs to bind C++ instance-member functions to your callbacks.

std::function is flexible enough to support both static-style and instance-member functions so you can get the best of both worlds. The static/instance invocation nature is encapsulated, so invocation via a std::function is just the normal ( ) semantics.

I, like you, have been doing quite a bit of C++ with ESP32. As such, I have adopted the std::function style for all my callbacks. It's very liberating (and natural OO) to use my instance-member functions as callbacks since those callbacks enjoy access to the state of the instance they belong to.

I have attached HttpServer[.h/cpp] and standalone example HttpServer example showing class static and instance member functions being used as callbacks. The files have ".txt" extensions so they would be able to be added to this note.

See the HttpServer::addPathHandler(...) and related code for references and handling of the std::function.

I left the argument and variable names in HttpServer the same, for less code changes. But, since std::function is not a pointer, then the naming convention of pXXX in the code no longer applies.

The rationale for putting http_req_resp_cb_t in PathHandler was due to declaration order/dependency and I didn't want to change more than the min to show the std::function working. One perspective is http_req_resp_cb_t should live on HttpServer as this is the main type clients will interact with and the PathHandler is really a behind-the-scenes support type for HttpServer.

ex_kolban_ws_w_std_func.cpp.txt
HttpServer.cpp.txt
HttpServer.h.txt

The example web requests are:
http://assigned-ip/c_style_cb
http://assigned-ip/static_cb
http://assigned-ip/instance_cb

Thanks again for your contributions and have good holidays!

[nkolban]

Thank you kind sir. Let me study std::function for a little bit. I'm sure you are right and we'll adopt the changes but want to examine myself in case I am asked about the changes. Again, thank YOU for your interest and contributions to the project.

[ismintis]

Let me qualify my last note as to usage of std::function. For simple callbacks of 0-n args (where n is a debatable number) I use std::function and a typedef to describe the callback signature. When n get's high (again debatable what n is), I use a new C++ type. The rationale for that scenario is:

1. having functions with too many args often means I'm missing a level of encapsulation
2. I will often need to add args later as functionality expands and its easier to maintain a simple type that encapsulates all the args than change main objects API's.
3. Arg order is problematic (ie. complex and confusing and often suffer from arg transposition) as n is high
4. It is easier for a client to aggregate the args in an existing type vs. having to funnel it into a single invoker of my function (note that usually means the client creates an aggregate type themselves anyway :)
5. It is easy to assign default values in the aggregate arg type whereas you get limited in a drawn out C++ function signature.
6. By adding new args to the type I can assign default values so existing code can generally still compile/function "as is" and the client can decide on their end if those default are appropriate vs. breaking an API contract.
7. The arg type can export constructors for common combinations of args and this makes end clients lives easier and the intent of the args more clear
8. Depending on complexity of args, I can have helper methods to set the args, or use something like a builder-pattern
9. Sometimes it is useful to have assertions or other validation-like behavior on the new arg type so that the client can do error handling pre-calling my API; note this allows the client then to use factory patterns etc.. to construct the arg type instance.

I see some of your API's use a type to encapsulate args and other use C-style function callback. The above thinking usually helps me decide on what mechanism to use, and thus, not only aids my design but makes my codes intent and evolution more predictable.

[nkolban]

I think the use of std::function seems to hold promise. It is very much in the vein of good and modern C++ programming and I can't find any fault in your thinking. However, lets hold off on placing it in the code base. My thinking goes as follows ... the primary consumers of ESP32 ESP-IDF are themselves C programmers and I'm having a hard time at best trying to get past the fear of C to C++ rather than introducing advanced C++. I have had enough concerns expressed to me over the use of std::string as opposed to just malloced char* data. We also have a growing number of Arduino programmers who are using the classes who don't know C from C++ and simply see the world as Arduino API. While you could easily convince me that std::function would arguably be a great solution for callback functions, I'm not yet seeing an imperative to switch over to it. If you wish to garner any further up-votes for the notion I'll be delighted to go with popular demand ... however in the absence of any further information, my gut is saying the change would currently be negatively perceived. Again, I am for sure not saying you are wrong and it feels like your C++ skills far exceed mine ... so no need to try and persuade me on technical merits ... rather I want to hear from other users that consumption would not be negatively impacted.

[ismintis]

No problems, you know and support the community using your code, so you need to figure out what is best.  As you say, let the community speak.

API's are tough to get right. Getting more people to use them upfront and keeping them stable is nearly always the right choice.

C -> C++ is tough for even experienced programmers. Initially struct-style classes with C-style API's are familiar to C folks, so again, maybe less C++ specifics upfront.

The path from Arduino to multi-core chips, threaded/task-based coding, richer libs and FreeRTOS is a pretty big hurdle itself.  I did a bunch of Arduino and Raspberry PI to see "what is was all about" so I have familarity with those ecosystems and their user bases.  From what I saw with the bulk of Arduino folks working with simplified language, runtimes, tools, sketches, etc..., they will have an interesting time moving to such richer environments.

Even jumping from C on the 8266 to FreeRTOS/ESP32 takes a bit of time.  I do understand the desire to limit language features in the API until folks are ready for it or request it. Hopefully, the more folks use C++ with MCU's, the more they will want to use C++ language features.  

In regards to using straight C-style function callbacks, you just can't use C++ in its intended OO sense (aka no instance member functions).  This was, for me at least, one of the biggest issues with using IDF's "C" and FreeRTOS API's with C++; you end up having to make your C++ callback functions static.
 
There is another approach to consider that can solve this issue. It is a pattern the FreeRTOS's xTaskCreate(..) uses. Basically you have an optional void* context argument in the function signature. The registration API allows for you to optionally pass the pointer to that context. When the callback is invoked, the registered void* context is passed back as an argument in the callback function.

This pattern is familiar to C and C++ programmers. For the C++ folks, this allows them to register a static dispatch function. They register "this" in the callback registration as the context. In the static function callback they cast the void* context to the instance and then simply call (dispatch to) the instance-member function.

I have included two trivial classes: SimpleClient and SimpleServer that demonstrate the pattern. SimpleClient has the main(). I meant to mention this approach in my previous notes as yet another established pattern for callback function API flexibility.

SomeClient.cpp.txt
SomeClient.h.txt
SomeServer.cpp.txt
SomeServer.h.txt

Thanks again for considering such ideas!

[sremberg]

Thanks for your examples, thats exactly what I needed.
I created a pull request for this update: nkolban/ESP32_BLE_Arduino#10
so neil can decide whether it's understandable and still easy enough for c programmers...
Alternatively you can use my fork...

[anhvu100]

Using std::function is almost transparent for consumer of the library and they don't even need to change their existing code. In fact, there are many existing libraries such as AsyncTCP or ESP8266WebServer that already used std::function for years so there should be no problem with most Arduino developer.

[fweiss]

First off, great library, Neil!

I have a slightly different take on this issue. I would like to use C++ lambdas for callbacks. Using std::function would support this as well. I created a small wrapper for BLECharacteristicCallbacks so I could use lamdbas for the callbacks. As the OP points out, it's natural in callbacks to refer to an instance member of the object whose state is involved in the callback. The C++ lambdas, the captures part provides for this linkage. Code example at https://github.com/fweiss/esp32-ble-blink

As for the issue of C vs C++, I side with C++, but understand the case for dumbing down to C for beginners. I don't like the fact that Espressif didn't go with C++ for their APIs, but I think they felt they needed to to capture the market. However, for larger projects, C++ and a good IDE like Eclipse are, IMO essential. But I'm surely preaching to the choir.

So yes, I'd like to see the BLECharacteristicCallbacks and related classes deprecated in favor of std::function and lamdba-style callbacks.

[az-z]

@yaoyogi thank you for the detailed and helpful explanation and examples. I'm one of those Arduino->C->C++ users. And exactly as you point out, i'm having a lot of fun with the transition.

I wonder, what the approach might be if we need to create a timer?
e.g :

TimerHandle_t xTimerCreate
                 ( const char * const pcTimerName,
                   const TickType_t xTimerPeriod,
                   const UBaseType_t uxAutoReload,
                   void * const pvTimerID,
                   TimerCallbackFunction_t pxCallbackFunction );

pxCallbackFunction | The function to call when the timer expires. Callback functions must have the prototype defined by TimerCallbackFunction_t, which is:
void vCallbackFunction( TimerHandle_t xTimer );

API mandates the callback signature. So how can we pass the "this" here?

the workflow is rather simple: each device has its own timer. Device's callback resets the eventgroup's bit after the timer expires.

thank you in advance