NAME¶
ggAddObserver,
ggDelObserver,
ggNotifyObservers,
ggClearPublisher - Simple observer framework
SYNOPSIS¶
#include <ggi/gg.h>
typedef int (ggfunc_observer_update)(void *arg, int flag, void *data);
struct gg_observer {
ggfunc_observer_update *update;
void *arg;
GG_LIST_ENTRY(gg_observer) _others;
};
struct gg_publisher {
GG_LIST_HEAD(gg_observer_list, gg_observer) observers;
};
#define INIT_PUBLISHER(pub) GG_LIST_INIT(&((pub)->observers))
struct gg_observer * ggAddObserver(struct gg_publisher *,
ggfunc_observer_update *, void *);
void ggDelObserver(struct gg_observer *);
void ggNotifyObservers(struct gg_publisher *, int, void *);
void ggClearPublisher(struct gg_publisher *);
DESCRIPTION¶
The observer pattern is very useful and commonly found in many software
packages, even if not explicitly called that way. The problem is that every
different software will often use a particular implementation of this pattern,
depending on a specific use-case. So usually everybody prefers to roll its
own. LibGG observers are defined as part of the forth-coming api
infrastructure, as light-weight cooperation model between libraries. The model
is very simple:
struct gg_publisher defines a channel on which observers can be
registered. An observer is simply an opaque value and a callback receiving
that value as first argument, a flag, and an opaque channel-specific message.
The idea is that if you known the observable you're listening on, you know the
semantics behind the flag and message. When the observable is triggered, all
observers' callbacks will be fired.
ggAddObserver registers a new observer on a publisher.
ggDelObserver unregisters the given observer from its publisher and frees
it.
ggNotifyObservers triggers all observers update functions for that
publisher. The flag and message will be given to the observers' update
callbacks. An observer
*must not* call
ggDelObserver on itself
in the update function to unregister. Instead it must return a non-zero value.
- ggClearPublisher frees all observers registered on
the publisher.
- If at least one is left, then there is probably a logical
error in the observer code, since it must already have been notified
somehow of the publisher going down, and unregistered all callbacks
before.
RETURN VALUES¶
ggAddObserver returns a newly constructed observer hook. Normally, the
caller will keep a reference to it to call if he needs to call
ggDelObserver later.
EXAMPLE¶
#include <ggi/gg.h>
#include <stdio.h>
int update(void* o, int f, void *d) {
printf("update called for observer %p, flag=%i, data=%p\n", o, f ,d);
if (o == 1) {
return 1; /* unregister */
}
return 0;
}
int main() {
struct gg_publisher pub;
struct gg_observer *o1, *o2;
INIT_PUBLISHER(&pub);
o1 = ggAddObserver(&pub, update, (void*)1);
o2 = ggAddObserver(&pub, update, (void*)2);
ggNotifyObservers(&pub, 0, NULL);
ggNotifyObservers(&pub, 1, NULL);
ggClearPublisher(&pub);
return 0;
}