object_monitor.c

/*
 * object_monitor.c
 *
 * $Id$
 *
 * functions and data structures for cooperating code to monitor objects.
 *
 * WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!
 * WARNING!                                                       WARNING!
 * WARNING!                                                       WARNING!
 * WARNING!         This code is under active development         WARNING!
 * WARNING!         and is subject to change at any time.         WARNING!
 * WARNING!                                                       WARNING!
 * WARNING!                                                       WARNING!
 * WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!
 */

#include <net-snmp/net-snmp-config.h>
#include <net-snmp/net-snmp-includes.h>
#include <net-snmp/agent/net-snmp-agent-includes.h>
#include <net-snmp/library/container.h>
#include <net-snmp/library/snmp_assert.h>

#include "net-snmp/agent/object_monitor.h"

#if ! defined TRUE
#  define TRUE 1
#elsif TRUE != 1
error "TRUE != 1"
#endif
/**************************************************************************
 *
 * Private data structures
 *
 **************************************************************************/
    /*
     * individual callback info for an object
     */
    typedef struct monitor_info_s {

   /** priority for this callback */
    int             priority;

   /** handler that registred to watch this object */
    netsnmp_mib_handler *watcher;

   /** events that the watcher cares about */
    unsigned int    events;

   /** callback function */
    netsnmp_object_monitor_callback *cb;

   /** pointer to data from the watcher */
    void           *watcher_data;

    struct monitor_info_s *next;

} monitor_info;

/*
 * list of watchers for a given object
 */
typedef struct watcher_list_s {

   /** netsnmp_index must be first! */
    netsnmp_index  monitored_object;

    monitor_info   *head;

} watcher_list;

/*
 * temp holder for ordered list of callbacks
 */
typedef struct callback_placeholder_s {

    monitor_info   *mi;
    netsnmp_monitor_callback_header *cbh;

    struct callback_placeholder_s *next;

} callback_placeholder;


/**************************************************************************
 *
 * 
 *
 **************************************************************************/

/*
 * local statics
 */
static char     need_init = 1;
static netsnmp_container *monitored_objects = NULL;
static netsnmp_monitor_callback_header *callback_pending_list;
static callback_placeholder *callback_ready_list;

/*
 * local prototypes
 */
static watcher_list *find_watchers(oid * object, size_t oid_len);
static int      insert_watcher(oid *, size_t, monitor_info *);
static int      check_registered(unsigned int event, oid * o, int o_l,
                                 watcher_list ** pWl, monitor_info ** pMi);
static void     move_pending_to_ready(void);


/**************************************************************************
 *
 * Public functions
 *
 **************************************************************************/

/*
 * 
 */
void
netsnmp_monitor_init(void)
{
    if (!need_init)
        return;

    callback_pending_list = NULL;
    callback_ready_list = NULL;

    monitored_objects = netsnmp_container_get("object_monitor:binary_array");
    if (NULL != monitored_objects)
        need_init = 0;
    monitored_objects->compare = netsnmp_compare_netsnmp_index;
    monitored_objects->ncompare = netsnmp_ncompare_netsnmp_index;
    
    return;
}


/**************************************************************************
 *
 * Registration functions
 *
 **************************************************************************/

/**
 * Register a callback for the specified object.
 *
 * @param object  pointer to the OID of the object to monitor.
 * @param oid_len length of the OID pointed to by object.
 * @param priority the priority to associate with this callback. A
 *                 higher number indicates higher priority. This
 *                 allows multiple callbacks for the same object to
 *                 coordinate the order in which they are called. If
 *                 two callbacks register with the same priority, the
 *                 order is undefined.
 * @param events  the events which the callback is interested in.
 * @param watcher_data pointer to data that will be supplied to the
 *                     callback method when an event occurs.
 * @param cb pointer to the function to be called when an event occurs.
 *
 * NOTE: the combination of the object, priority and watcher_data must
 *       be unique, as they are the parameters for unregistering a
 *       callback.
 *
 * @return SNMPERR_NOERR registration was successful
 * @return SNMPERR_MALLOC memory allocation failed
 * @return SNMPERR_VALUE the combination of the object, priority and
 *                        watcher_data is not unique.
 */
int
netsnmp_monitor_register(oid * object, size_t oid_len, int priority,
                         unsigned int events, void *watcher_data,
                         netsnmp_object_monitor_callback * cb)
{
    monitor_info   *mi;
    int             rc;

    netsnmp_assert(need_init == 0);

    mi = calloc(1, sizeof(monitor_info));
    if (NULL == mi)
        return SNMPERR_MALLOC;

    mi->priority = priority;
    mi->events = events;
    mi->watcher_data = watcher_data;
    mi->cb = cb;

    rc = insert_watcher(object, oid_len, mi);
    if (rc != SNMPERR_SUCCESS)
        free(mi);

    return rc;
}

/**
 * Unregister a callback for the specified object.
 *
 * @param object  pointer to the OID of the object to monitor.
 * @param oid_len length of the OID pointed to by object.
 * @param priority the priority to associate with this callback.
 * @param wd pointer to data that was supplied when the
 *                     callback was registered.
 * @param cb pointer to the function to be called when an event occurs.
 */
int
netsnmp_monitor_unregister(oid * object, size_t oid_len, int priority,
                           void *wd, netsnmp_object_monitor_callback * cb)
{
    monitor_info   *mi, *last;

    watcher_list   *wl = find_watchers(object, oid_len);
    if (NULL == wl)
        return SNMPERR_GENERR;

    last = NULL;
    mi = wl->head;
    while (mi) {
        if ((mi->cb == cb) && (mi->priority == priority) &&
            (mi->watcher_data == wd))
            break;
        last = mi;
        mi = mi->next;
    }

    if (NULL == mi)
        return SNMPERR_GENERR;

    if (NULL == last)
        wl->head = mi->next;
    else
        last->next = mi->next;

    if (NULL == wl->head) {
        CONTAINER_REMOVE(monitored_objects, wl);
        free(wl->monitored_object.oids);
        free(wl);
    }

    free(mi);

    return SNMPERR_SUCCESS;
}

/**************************************************************************
 *
 * object monitor functions
 *
 **************************************************************************/

/**
 * Notifies the object monitor of an event.
 *
 * The object monitor funtions will save the callback information
 * until all varbinds in the current PDU have been processed and
 * a response has been sent. At that time, the object monitor will
 * determine if there are any watchers monitoring for the event.
 *
 * NOTE: the actual type of the callback structure may vary. The
 *       object monitor functions require only that the start of
 *       the structure match the netsnmp_monitor_callback_header
 *       structure. It is up to the watcher and monitored objects
 *       to agree on the format of other data.
 *
 * @param cbh pointer to a callback header.
 */
void
netsnmp_notify_monitor(netsnmp_monitor_callback_header * cbh)
{

    netsnmp_assert(need_init == 0);

    /*
     * put processing of until response has been sent
     */
    cbh->private = callback_pending_list;
    callback_pending_list = cbh;

    return;
}

/**
 * check to see if a registration exists for an object/event combination
 *
 * @param event the event type to check for
 * @param o     the oid to check for
 * @param o_l   the length of the oid
 *
 * @returns TRUE(1) if a callback is registerd
 * @returns FALSE(0) if no callback is registered
 */
int
netsnmp_monitor_check_registered(int event, oid * o, int o_l)
{
    return check_registered(event, o, o_l, NULL, NULL);
}

/**
 * Process all pending callbacks
 *
 * NOTE: this method is not in the public header, as it should only be
 *       called in one place, in the agent.
 */
void
netsnmp_monitor_process_callbacks(void)
{
    netsnmp_assert(need_init == 0);
    netsnmp_assert(NULL == callback_ready_list);

    if (NULL == callback_pending_list) {
        DEBUGMSGT(("object_monitor", "No callbacks to process"));
        return;
    }

    DEBUGMSG(("object_monitor", "Checking for registered " "callbacks."));

    /*
     * move an pending notification which has a registered watcher to the
     * ready list. Free any other notifications.
     */
    move_pending_to_ready();

    /*
     * call callbacks
     */
    while (callback_ready_list) {

        /*
         * pop off the first item
         */
        callback_placeholder *current_cbr;
        current_cbr = callback_ready_list;
        callback_ready_list = current_cbr->next;

        /*
         * setup, then call callback
         */
        current_cbr->cbh->watcher_data = current_cbr->mi->watcher_data;
        current_cbr->cbh->priority = current_cbr->mi->priority;
        (*current_cbr->mi->cb) (current_cbr->cbh);

        /*
         * release memory (don't free current_cbr->mi)
         */
        if (--(current_cbr->cbh->refs) == 0) {
            free(current_cbr->cbh->monitored_object.oids);
            free(current_cbr->cbh);
        }
        free(current_cbr);

        /*
         * check for any new pending notifications
         */
        move_pending_to_ready();

    }

    netsnmp_assert(callback_ready_list == NULL);
    netsnmp_assert(callback_pending_list = NULL);

    return;
}

/**************************************************************************
 *
 * COOPERATIVE helpers
 *
 **************************************************************************/
/**
 * Notifies the object monitor of a cooperative event.
 *
 * This convenience function will build a
 * ::netsnmp_monitor_callback_header and call
 * netsnmp_notify_monitor().
 *
 * @param event the event type
 * @param  o pointer to the oid of the object sending the event
 * @param o_len    the lenght of the oid
 * @param o_steal set to true if the function may keep the pointer
 *                  to the memory (and free it later). set to false
 *                  to make the function allocate and copy the oid.
 * @param object_info pointer to data supplied by the object for
 *                    the callback. This pointer must remain valid,
 *                    will be provided to each callback registered
 *                    for the object (i.e. it will not be copied or
 *                    freed).
 */
void
netsnmp_notify_cooperative(int event, oid * o, size_t o_len, char o_steal,
                           void *object_info)
{
    netsnmp_monitor_callback_cooperative *cbh;

    netsnmp_assert(need_init == 0);

    cbh = SNMP_MALLOC_TYPEDEF(netsnmp_monitor_callback_cooperative);
    if (NULL == cbh) {
        snmp_log(LOG_ERR, "could not allocate memory for "
                 "cooperative callback");
        return;
    }

    cbh->hdr.event = event;
    cbh->hdr.object_info = object_info;
    cbh->hdr.monitored_object.len = o_len;

    if (o_steal) {
        cbh->hdr.monitored_object.oids = o;
    } else {
        cbh->hdr.monitored_object.oids = snmp_duplicate_objid(o, o_len);
    }

    netsnmp_notify_monitor((netsnmp_monitor_callback_header *) cbh);
}

/** @cond */
/*************************************************************************
 *************************************************************************
 *************************************************************************
 * WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!
 * WARNING!                                                       WARNING!
 * WARNING!                                                       WARNING!
 * WARNING!         This code is under active development         WARNING!
 * WARNING!         and is subject to change at any time.         WARNING!
 * WARNING!                                                       WARNING!
 * WARNING!                                                       WARNING!
 * WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING! WARNING!
 *************************************************************************
 *************************************************************************
 *************************************************************************
 */
static watcher_list *
find_watchers(oid * object, size_t oid_len)
{
    netsnmp_index oah;

    oah.oids = object;
    oah.len = oid_len;

    return (watcher_list *)CONTAINER_FIND(monitored_objects, &oah);
}

static int
insert_watcher(oid * object, size_t oid_len, monitor_info * mi)
{
    watcher_list   *wl = find_watchers(object, oid_len);
    int             rc = SNMPERR_SUCCESS;

    if (NULL != wl) {

        monitor_info   *last, *current;

        netsnmp_assert(wl->head != NULL);

        last = NULL;
        current = wl->head;
        while (current) {
            if (mi->priority == current->priority) {
                /*
                 * check for duplicate
                 */
                if (mi->watcher_data == current->watcher_data)
                    return SNMPERR_VALUE; /** duplicate! */
            } else if (mi->priority > current->priority) {
                break;
            }
            last = current;
            current = current->next;
        }
        if (NULL == last) {
            mi->next = wl->head;
            wl->head = mi;
        } else {
            mi->next = last->next;
            last->next = mi;
        }
    } else {

        /*
         * first watcher for this oid; set up list
         */
        wl = SNMP_MALLOC_TYPEDEF(watcher_list);
        if (NULL == wl)
            return SNMPERR_MALLOC;

        /*
         * copy index oid
         */
        wl->monitored_object.len = oid_len;
        wl->monitored_object.oids = malloc(sizeof(oid) * oid_len);
        if (NULL == wl->monitored_object.oids) {
            free(wl);
            return SNMPERR_MALLOC;
        }
        memcpy(wl->monitored_object.oids, object, sizeof(oid) * oid_len);

        /*
         * add watcher, and insert into array
         */
        wl->head = mi;
        mi->next = NULL;
        rc = CONTAINER_INSERT(monitored_objects, wl);
        if (rc) {
            free(wl->monitored_object.oids);
            free(wl);
            return rc;
        }
    }
    return rc;
}

/**
 * @internal
 * check to see if a registration exists for an object/event combination
 *
 * @param event the event type to check for
 * @param o     the oid to check for
 * @param o_l   the length of the oid
 * @param pWl   if a pointer to a watcher_list pointer is supplied,
 *              upon return the watcher list pointer will be set to
 *              the watcher list for the object, or NULL if there are
 *              no watchers for the object.
 * @param pMi   if a pointer to a monitor_info pointer is supplied,
 *              upon return the pointer will be set to the first
 *              monitor_info object for the specified event.
 *
 * @returns TRUE(1) if a callback is registerd
 * @returns FALSE(0) if no callback is registered
 */
static int
check_registered(unsigned int event, oid * o, int o_l,
                 watcher_list ** pWl, monitor_info ** pMi)
{
    watcher_list   *wl;
    monitor_info   *mi;

    netsnmp_assert(need_init == 0);

    /*
     * check to see if anyone has registered for callbacks
     * for the object.
     */
    wl = find_watchers(o, o_l);
    if (pWl)
        *pWl = wl;
    if (NULL == wl)
        return 0;

    /*
     * check if any watchers are watching for this specific event
     */
    for (mi = wl->head; mi; mi = mi->next) {

        if (mi->events & event) {
            if (pMi)
                *pMi = mi;
            return TRUE;
        }
    }

    return 0;
}

/**
 *@internal
 */
inline void
insert_ready(callback_placeholder * new_cbr)
{
    callback_placeholder *current_cbr, *last_cbr;

    /*
     * insert in callback ready list
     */
    last_cbr = NULL;
    current_cbr = callback_ready_list;
    while (current_cbr) {

        if (new_cbr->mi->priority > current_cbr->mi->priority)
            break;

        last_cbr = current_cbr;
        current_cbr = current_cbr->next;
    }
    if (NULL == last_cbr) {
        new_cbr->next = callback_ready_list;
        callback_ready_list = new_cbr;
    } else {
        new_cbr->next = last_cbr->next;
        last_cbr->next = new_cbr;
    }
}

/**
 *@internal
 *
 * move an pending notification which has a registered watcher to the
 * ready list. Free any other notifications.
 */
static void
move_pending_to_ready(void)
{
    /*
     * check to see if anyone has registered for callbacks
     * for each object.
     */
    while (callback_pending_list) {

        watcher_list   *wl;
        monitor_info   *mi;
        netsnmp_monitor_callback_header *cbp;

        /*
         * pop off first item
         */
        cbp = callback_pending_list;
        callback_pending_list = cbp->private; /** next */

        if (0 == check_registered(cbp->event, cbp->monitored_object.oids,
                                  cbp->monitored_object.len, &wl,
                                  &mi)) {

            /*
             * nobody watching, free memory
             */
            free(cbp);
            continue;
        }

        /*
         * Found at least one; check the rest of the list and
         * save callback for processing
         */
        for (; mi; mi = mi->next) {

            callback_placeholder *new_cbr;

            if (0 == (mi->events & cbp->event))
                continue;

            /*
             * create temprory placeholder.
             *
             * I hate to allocate memory here, as I'd like this code to
             * be fast and lean. But I don't have time to think of another
             * solution os this will have to do for now.
             *
             * I need a list of monitor_info (mi) objects for each
             * callback which has registered for the event, and want
             * that list sorted by the priority required by the watcher.
             */
            new_cbr = SNMP_MALLOC_TYPEDEF(callback_placeholder);
            if (NULL == new_cbr) {
                snmp_log(LOG_ERR, "malloc failed, callback dropped.");
                continue;
            }
            new_cbr->cbh = cbp;
            new_cbr->mi = mi;
            ++cbp->refs;

            /*
             * insert in callback ready list
             */
            insert_ready(new_cbr);

        } /** end mi loop */
    } /** end cbp loop */

    netsnmp_assert(callback_pending_list == NULL);
}


#if defined TESTING_OBJECT_MONITOR
/**************************************************************************
 *
 * (untested) TEST CODE
 *
 */
void
dummy_callback(netsnmp_monitor_callback_header * cbh)
{
    printf("Callback received.\n");
}

void
dump_watchers(netsnmp_index *oah, void *)
{
    watcher_list   *wl = (watcher_list *) oah;
    netsnmp_monitor_callback_header *cbh = wl->head;

    printf("Watcher List for OID ");
    print_objid(wl->hdr->oids, wl->hdr->len);
    printf("\n");

    while (cbh) {

        printf("Priority = %d;, Events = %d; Watcher Data = 0x%x\n",
               cbh->priority, cbh->events, cbh->watcher_data);

        cbh = cbh->private;
    }
}

void
main(int argc, char **argv)
{

    oid             object[3] = { 1, 3, 6 };
    int             object_len = 3;
    int             rc;

    /*
     * init
     */
    netsnmp_monitor_init();

    /*
     * insert an object
     */
    rc = netsnmp_monitor_register(object, object_len, 0,
                                  EVENT_ROW_ADD, (void *) 0xdeadbeef,
                                  dummy_callback);
    printf("insert an object: %d\n", rc);

    /*
     * insert same object, new priority
     */
    netsnmp_monitor_register(object, object_len, 10,
                             EVENT_ROW_ADD, (void *) 0xdeadbeef,
                             dummy_callback);
    printf("insert same object, new priority: %d\n", rc);

    /*
     * insert same object, same priority, new data
     */
    netsnmp_monitor_register(object, object_len, 10,
                             EVENT_ROW_ADD, (void *) 0xbeefdead,
                             dummy_callback);
    printf("insert same object, same priority, new data: %d\n", rc);

    /*
     * insert same object, same priority, same data
     */
    netsnmp_monitor_register(object, object_len, 10,
                             EVENT_ROW_ADD, (void *) 0xbeefdead,
                             dummy_callback);
    printf("insert same object, same priority, new data: %d\n", rc);


    /*
     * dump table
     */
    CONTAINER_FOR_EACH(monitored_objects, dump_watchers, NULL);
}
#endif /** defined TESTING_OBJECT_MONITOR */

/** @endcond */