ggAddObserver

Section: GGI (3) Updated: 2005-08-26 Local index Up

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;
}

This document was created by man2html, using the manual pages.
Time: 21:46:53 GMT, April 16, 2011