Event-Driven API Design with Callbacks

From One-to-One to One-to-Many: The Observer Pattern

The core idea is to decouple the source of an event (the Subject) from the entities that need to react to it (the Observers). The Subject doesn't need to know anything about the Observers; it only knows that it must maintain a list of registered listeners and notify them when something happens.

This diagram illustrates the general principle. A "Library" (our Subject) can invoke a "Callback function" (our Observer) that resides in the main application, creating a reverse flow of control that is incredibly flexible.

An event-driven API based on this pattern needs to provide three key features:

1. Registration: A function for Observers to register their callback. (register_listener)
2. Deregistration: A function for Observers to unregister their callback. (unregister_listener)
3. Triggering: An event that causes the Subject to iterate through its list of registered callbacks and invoke them.

A First Implementation: A Simple Button Notifier

Let's design a minimal system: a Button module that can notify multiple listeners when it's "pressed".

We'll start with an array of function pointers to store the registered callbacks.

// button.h

#define MAX_LISTENERS 5

// Define the callback function pointer type
typedef void (*button_callback_t)(void);

// API functions
void button_init(void);
int button_register_callback(button_callback_t cb);
void button_deregister_callback(button_callback_t cb);
void button_press(void); // This is our event trigger

The implementation in button.c would manage this array.

• button_register_callback finds a NULL slot in the array and stores the new callback.
• button_deregister_callback finds the matching callback and sets its slot to NULL.
• button_press iterates through the array and calls every non-NULL function pointer.

This approach is simple, but it has limitations. The fixed-size array isn't scalable, and more importantly, the callback void (*cb)(void) is not very useful—the listener has no context. Which button was pressed? What state should the listener update?

The resource below builds a similar, but more realistic, event loop for network programming. Its design is very clear and directly applies here.

A Professional Implementation for Embedded Systems

The simple array-based approach works, but for production systems like the ones you build, a more robust and scalable solution is needed. Let's study a professional implementation of the Observer pattern designed specifically for embedded C.

This pattern addresses key challenges:

• Scalability: Uses a linked list instead of a fixed-size array to manage listeners.
• Type Safety & Context: Provides a clever and efficient way for a listener to access its own data within the callback using the container_of macro, a common technique in the Linux kernel and other low-level software.
• Encapsulation: Bundles callback information into a struct.

The following video provides an excellent walkthrough of this advanced pattern. It's highly relevant to your work in automotive middleware.

Pitfalls and Advanced Considerations

Designing a robust event-driven system requires careful attention to potential issues. Given your experience with safety-critical systems, these points will be particularly relevant.

1. Dangling Callbacks (Use-After-Free)

This is the most common and dangerous pitfall.

• Problem: An observer is deallocated or goes out of scope, but it has not been deregistered from the subject. When the subject later tries to invoke the callback, it calls a dangling pointer, leading to a crash or undefined behavior.
• Solution: Enforce strict ownership rules. The owner of an observer object is responsible for deregistering it before the object is destroyed. This is often done by pairing registration and deregistration in the object's create/destroy or init/deinit functions.

2. Modification During Notification

• Problem: What happens if, during a notification loop, one of the callbacks tries to register or deregister another callback? This can corrupt the list of observers you are currently iterating over.
• Solutions:
  1. Forbid it: The simplest solution. Use a flag to prevent modifications during notification and assert if a violation occurs.
  2. Make a copy: Before the notification loop, copy the list of observers. Iterate over the copy. New registrations/deregistrations will affect the original list and will be reflected in the next event trigger.
  3. Use a safe iterator: A more complex solution where the list data structure and iteration logic are designed to handle additions/removals during traversal.

The "Patterns in C" article discusses the first solution, which is often sufficient and promotes a simpler system design.

#include <stdint.h>
#include <stdbool.h>

// Forward declarations
struct ObserverNode;
struct CollisionWarningSystem;
struct EventDataRecorder;

// 1. Callback function pointer type
// It takes a pointer to the observer node and the event data.
typedef void (*object_detected_cb_t)(struct ObserverNode* node, uint32_t object_id, float distance_m);

// 2. Generic ObserverNode struct for a linked list
typedef struct ObserverNode {
    struct ObserverNode* next; // For linked list
    object_detected_cb_t on_object_detected;
} ObserverNode_t;

// 3. The Subject: RadarSensor
typedef struct {
    uint32_t sensor_id;
    ObserverNode_t* listeners_head; // Head of the observer linked list
} RadarSensor_t;

// 4. The Observers
typedef struct CollisionWarningSystem {
    ObserverNode_t observer; // Embedded observer node
    bool is_active;
    int warning_level;
} CollisionWarningSystem_t;

typedef struct EventDataRecorder {
    ObserverNode_t observer; // Embedded observer node
    uint32_t log_buffer[1024];
    size_t log_index;
} EventDataRecorder_t;

// 5. Public API for the RadarSensor
void radar_register_listener(RadarSensor_t* sensor, ObserverNode_t* listener);
void radar_deregister_listener(RadarSensor_t* sensor, ObserverNode_t* listener);
void radar_notify_object_detected(RadarSensor_t* sensor, uint32_t object_id, float distance_m);

/*
// --- Example callback implementations (stubs) ---
// Using the container_of macro (assumed to be defined elsewhere)
#define container_of(ptr, type, member) ((type *)((char *)(ptr) - offsetof(type, member)))

void cws_on_object_detected(ObserverNode_t* node, uint32_t object_id, float distance_m) {
    CollisionWarningSystem_t* self = container_of(node, CollisionWarningSystem_t, observer);
    if (self->is_active && distance_m < 20.0) {
        // printf("CWS: Warning! Object %u at %.1fm!\n", object_id, distance_m);
        self->warning_level = 10;
    }
}

void edr_on_object_detected(ObserverNode_t* node, uint32_t object_id, float distance_m) {
    EventDataRecorder_t* self = container_of(node, EventDataRecorder_t, observer);
    if (self->log_index < 1024) {
        // self->log_buffer[self->log_index++] = object_id;
        // printf("EDR: Logged object %u\n", object_id);
    }
}
*/

Conclusion

You have now moved from a simple one-to-one callback to designing a one-to-many event notification system, a fundamental architecture for any complex, modular software.

Key Takeaways:

• The Observer pattern decouples event producers (Subjects) from consumers (Observers), enabling extensible and maintainable code.
• An event-driven API is built around functions for registration, deregistration, and a trigger mechanism.
• The Subject manages a list of callbacks, typically using a dynamic data structure like a linked list for scalability.
• Passing context to callbacks is crucial. This can be done with an explicit void* user_data parameter or more elegantly with the container_of macro pattern common in embedded and kernel C.
• Robustness requires careful lifetime management of observers to prevent dangling callbacks and handling modification during notification.

Preview of the Next Lesson:
In this lesson, you saw two ways to provide context to a callback: the container_of macro and passing a data-filled Request struct. The next lesson, "Pass context-specific data to a callback function using a void pointer," will focus entirely on the latter pattern. We will explore the power and flexibility of using a void* context pointer, analyze its type-safety trade-offs, and see how it enables callbacks to work with arbitrary application-specific data structures.