lbmht.h

Go to the documentation of this file.

/** \file lbmht.h
    \brief Ultra Messaging (UM) HyperTopic API
        \author M. Garwood - Informatica Corporation 
        \version $Id: //UMprod/REL_5_3_6/29West/lbm/src/lib/lbm/lbmht.h#2 $

        The Ultra Messaging (UM) HyperTopic API Description. Included
    are types, constants, and functions related to the API. Contents are
    subject to change.

    All of the documentation and software included in this and any
    other Informatica Corporation Ultra Messaging Releases
    Copyright (C) Informatica Corporation. All rights reserved.
    
    Redistribution and use in source and binary forms, with or without
    modification, are permitted only as covered by the terms of a
    valid software license agreement with Informatica Corporation.
    
    Copyright (C) 2006-2014, Informatica Corporation. All Rights Reserved.
    
    THE SOFTWARE IS PROVIDED "AS IS" AND INFORMATICA DISCLAIMS ALL WARRANTIES 
    EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF 
    NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR 
    PURPOSE.  INFORMATICA DOES NOT WARRANT THAT USE OF THE SOFTWARE WILL BE 
    UNINTERRUPTED OR ERROR-FREE.  INFORMATICA SHALL NOT, UNDER ANY CIRCUMSTANCES, BE 
    LIABLE TO LICENSEE FOR LOST PROFITS, CONSEQUENTIAL, INCIDENTAL, SPECIAL OR 
    INDIRECT DAMAGES ARISING OUT OF OR RELATED TO THIS AGREEMENT OR THE 
    TRANSACTIONS CONTEMPLATED HEREUNDER, EVEN IF INFORMATICA HAS BEEN APPRISED OF 
    THE LIKELIHOOD OF SUCH DAMAGES.

        The LBM HyperTopic API provides a mechanism to enable the efficient
        reception of messages sent over any LBM transport (especially an immediate
        messaging transport) where the message topic conforms to a simple
        hierarchical wildcard topic structure.

        The hierarchical topic supported by this API has a BNF grammar as follows:
        \code
        <ht-topic> ::= <ht-prefix> <ht-topic-comps> 
                     | <ht-topic-comps>
        <ht-topic-comps> ::= <ht-topic-comp> "/" <ht-topic-comps>
                           | <ht-topic-comp> "/>"
                           | <ht-topic-comp>
                           | ">"
        <ht-topic-comp> ::= <text>
                          | "*"
                          | ""
        <ht-prefix> ::= <text>
        \endcode
        The "*" token in the above grammar will match any sequence of characters
        excluding a "/".  The ">" token will match any sequence of characters
        including a "/" (until the end of the topic string).

        The grammar supports a prefix string that can be applied to effectively
        implement a namespace for each instance of a HyperTopic receiver.

        A HyperTopic receiver is initialized using the lbm_hypertopic_rcv_init()
        API function.  This function sets the HyperTopic namespace prefix and
        an optional event queue to be used for messages received 
        on all topics which are part of the HyperTopic namespace.

        The lbm_hypertopic_rcv_add() and lbm_hypertopic_rcv_delete() functions
        are used to add and remove topic patterns to the HyperTopic namespace.  
        Unlike non-HyperTopic receiver creation and deletion functions, these
        functions take the same set of arguments which include a pointer to the
        HyperTopic receiver object, the topic pattern, received message callback
        function and client data pointer (passed with message to the callback
        function.  The lbm_hypertopic_rcv_delete() API function also accepts
        an optional designation for a callback function to be called once 
        all message callbacks for the topic being deleted have completed.

        The lbm_hypertopic_rcv_destroy() API function should be called to 
        de-initialize and clean-up the HyperTopic receiver after all topics
        added to the HyperTopic namespace have been deleted.
*/

#ifndef LBMHT_H
#define LBMHT_H

#if defined(__cplusplus)
extern "C" {
#endif /* __cplusplus */

#include "lbm/lbm.h"

#define LBM_HT_BASE_MATCH_LEVEL         0
#define LBM_HT_TOKEN_GLOBNAME           0
#define LBM_HT_TOKEN_GLOBPATH           1
#define LBM_HT_TOKEN_NAME                       2

#define LBM_HT_INIT_BRANCH_SZ   16

#define LBM_HT_CBVEC_SZ 16

/*! \brief HyperTopic receiver object (opaque)
*/
typedef struct lbm_hypertopic_rcv_stct lbm_hypertopic_rcv_t;

/*! \brief Application callback for messages delivered to  HyperTopic receivers.

        Set by lbm_hypertopic_rcv_add(). 
        If this application callback is set on an HyperTopic receiver that has
        been initialized without an event queue, it is called from the context
        thread and is therefore, limited in the API calls that it can make.

        After the callback returns, the message object \a msg is deleted and the
        application must not refer to it.  This behavior can be overridden by
        calling lbm_msg_retain() from the receive callback before it returns.
        It then becomes the application's responsibility to delete the message
        object by calling lbm_msg_delete() after the application no longer needs to
        refer to the message structure or its contents.

        \note For received application messages, be aware that LBM does not
        guarantee any alignment of that data.

        \param hrcv HyperTopic receiver object generating the event.
        \param msg Message object containing the receiver event.
        \param clientd Client data pointer supplied in lbm_hypertopic_rcv_add().
        \return 0 always.

*/
typedef int (*lbm_hypertopic_rcv_cb_proc)(lbm_hypertopic_rcv_t *hrcv, lbm_msg_t *msg, void *clientd);

/*! \brief Application callback for lbm_hypertopic_rcv_delete().

        Set by lbm_hypertopic_rcv_delete().
        Note: This application callback can be made from the context thread, and
        is therefore, limited in the LBM API calls that it can make.  The
        application is called after all events associated with the delete are
        completed.

        \sa lbm_delete_cb_info_t
        \param dispatch_thrd Indicates from where the callback is being called.
                This can be useful to the application to avoid deadlock.
                \arg 1 - Called by the dispatch thread (after the call to lbm_hypertopic_rcv_delete() returns).
                \arg 0 - Called directly by the lbm_hypertopic_rcv_delete() function.
        \param clientd Client data pointer supplied in the lbm_delete_cb_info_t passed to lbm_hypertopic_rcv_delete().
        \return 0 always.
*/
typedef void (*lbm_delete_cb_proc)(int dispatch_thrd, void *clientd);

#define LBM_HT_CBVEC_FLAG_ACTIVE        1
#define LBM_HT_CBVEC_FLAG_DELETED       2


#ifdef LBM_HT_INTERNAL
struct htcbvec {
        union {
                lbm_hypertopic_rcv_cb_proc rcvproc;
                lbm_delete_cb_proc delproc;
        } u;
        void *clientd;
        int flags;
};

struct htcbvlist
{
        struct htcbvlist *next;
        struct htcbvlist *nextactv;
        int idx;
        struct htcbvec cbvec[LBM_HT_CBVEC_SZ];
};

struct lbm_hypertopic_rcv_stct
{
        mul_mutex_t lock;
        lbm_wildcard_rcv_t *wrcv;
        lbm_event_queue_t *evq;
        lbm_context_t *ctx;
        struct htbranch *root;
        size_t prelen;
        struct htcbvlist *activecbs;
};

struct htcbnode
{
        lbm_hypertopic_rcv_cb_proc rcvproc;
        void *clientd;
        struct htcbnode *next;
};

struct htnode
{
        char *cname;
        int refcnt;
        struct htcbnode *cblist;
        struct htbranch *next;
};

struct htbranch
{
        int nnodes;
        int size;
        int idx[LBM_HT_TOKEN_NAME+1];
        struct htnode htnodes[1];
};
#endif

/*! \brief Structure passed to the lbm_hypertopic_rcv_delete() function so that a deletion callback may be called.
*/
typedef struct lbm_delete_cb_info_t_stct {
    /*! The cancel callback function */
    lbm_delete_cb_proc cbproc;
    /*! Client Data passed in the deletion callback when called */
    void *clientd;
} lbm_delete_cb_info_t;

/*! \brief Initialize a HyperTopic receiver.
    \param hrcvp Pointer to location where the lbm_hypertopic_rcv_t object will be returned.
        \param ctx Pointer to the LBM context object associated with the receiver.  
        \param prefix Namespace prefix for the HyperTopic receiver.  The prefix string constrains the topic namespace to topics that begin with the specified prefix only.  This parameter may be set to NULL if no prefix is to be defined for
        this HyperTopic namespace.
        \param evq Optional Event Queue to place message events on when they arrive. If NULL, all messages will be delivered from the context thread. 
        \return 0 for success, -1 on failure
*/
LBMExpDLL int lbm_hypertopic_rcv_init(lbm_hypertopic_rcv_t **hrcvp, lbm_context_t *ctx, const char *prefix, lbm_event_queue_t *evq);

/*! \brief Add a topic pattern to the set of topics being received by a HyperTopic receiver.
        \param hrcv HyperTopic object created by lbm_hypertopic_rcv_init()
        \param pattern Hierarchical topic pattern to add to the HyperTopic group.
        \param proc Pointer to a function to call when messages arrive on a topic matched by \a pattern.
        \param clientd Pointer to client data that is passed to \a proc when data arrives on the topic matched by \a pattern.
        \return 0 for success, -1 on failure
*/
LBMExpDLL int lbm_hypertopic_rcv_add(lbm_hypertopic_rcv_t *hrcv, const char *pattern, lbm_hypertopic_rcv_cb_proc proc, void *clientd);

/*! \brief Delete a previously added topic from a HyperTopic receiver topic set.
        \param hrcv HyperTopic object created by lbm_hypertopic_rcv_init()
        \param pattern Hierarchical topic pattern to delete from the HyperTopic group.
        \param proc Pointer to a function being called when messages arrive from the given \a pattern.
        \param clientd Pointer to client data that is being passed to \a proc when data arrives on a topic matched by \a pattern.
        \return 0 for success, -1 on failure
*/
LBMExpDLL int lbm_hypertopic_rcv_delete(lbm_hypertopic_rcv_t *hrcv, const char *pattern, lbm_hypertopic_rcv_cb_proc proc, void *clientd, lbm_delete_cb_info_t *cbinfo);

/*! \brief Clean-up HyperTopic receiver previously created by lbm_hypertopic_rcv_init()
        \param hrcv HyperTopic receiver to be destroyed.
        \return 0 for success, -1 on failure
*/
LBMExpDLL int lbm_hypertopic_rcv_destroy(lbm_hypertopic_rcv_t *hrcv);

#if defined(__cplusplus)
}
#endif /* __cplusplus */

#endif

---