lbmht.h

Go to the documentation of this file.
00001 /** \file lbmht.h
00002     \brief Ultra Messaging (UM) HyperTopic API
00003         \author M. Garwood - Informatica Corporation 
00004         \version $Id: //UMprod/REL_5_3_6/29West/lbm/src/lib/lbm/lbmht.h#2 $
00005 
00006         The Ultra Messaging (UM) HyperTopic API Description. Included
00007     are types, constants, and functions related to the API. Contents are
00008     subject to change.
00009 
00010     All of the documentation and software included in this and any
00011     other Informatica Corporation Ultra Messaging Releases
00012     Copyright (C) Informatica Corporation. All rights reserved.
00013     
00014     Redistribution and use in source and binary forms, with or without
00015     modification, are permitted only as covered by the terms of a
00016     valid software license agreement with Informatica Corporation.
00017     
00018     Copyright (C) 2006-2014, Informatica Corporation. All Rights Reserved.
00019     
00020     THE SOFTWARE IS PROVIDED "AS IS" AND INFORMATICA DISCLAIMS ALL WARRANTIES 
00021     EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF 
00022     NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR 
00023     PURPOSE.  INFORMATICA DOES NOT WARRANT THAT USE OF THE SOFTWARE WILL BE 
00024     UNINTERRUPTED OR ERROR-FREE.  INFORMATICA SHALL NOT, UNDER ANY CIRCUMSTANCES, BE 
00025     LIABLE TO LICENSEE FOR LOST PROFITS, CONSEQUENTIAL, INCIDENTAL, SPECIAL OR 
00026     INDIRECT DAMAGES ARISING OUT OF OR RELATED TO THIS AGREEMENT OR THE 
00027     TRANSACTIONS CONTEMPLATED HEREUNDER, EVEN IF INFORMATICA HAS BEEN APPRISED OF 
00028     THE LIKELIHOOD OF SUCH DAMAGES.
00029 
00030         The LBM HyperTopic API provides a mechanism to enable the efficient
00031         reception of messages sent over any LBM transport (especially an immediate
00032         messaging transport) where the message topic conforms to a simple
00033         hierarchical wildcard topic structure.
00034 
00035         The hierarchical topic supported by this API has a BNF grammar as follows:
00036         \code
00037         <ht-topic> ::= <ht-prefix> <ht-topic-comps> 
00038                      | <ht-topic-comps>
00039         <ht-topic-comps> ::= <ht-topic-comp> "/" <ht-topic-comps>
00040                            | <ht-topic-comp> "/>"
00041                            | <ht-topic-comp>
00042                            | ">"
00043         <ht-topic-comp> ::= <text>
00044                           | "*"
00045                           | ""
00046         <ht-prefix> ::= <text>
00047         \endcode
00048         The "*" token in the above grammar will match any sequence of characters
00049         excluding a "/".  The ">" token will match any sequence of characters
00050         including a "/" (until the end of the topic string).
00051 
00052         The grammar supports a prefix string that can be applied to effectively
00053         implement a namespace for each instance of a HyperTopic receiver.
00054 
00055         A HyperTopic receiver is initialized using the lbm_hypertopic_rcv_init()
00056         API function.  This function sets the HyperTopic namespace prefix and
00057         an optional event queue to be used for messages received 
00058         on all topics which are part of the HyperTopic namespace.
00059 
00060         The lbm_hypertopic_rcv_add() and lbm_hypertopic_rcv_delete() functions
00061         are used to add and remove topic patterns to the HyperTopic namespace.  
00062         Unlike non-HyperTopic receiver creation and deletion functions, these
00063         functions take the same set of arguments which include a pointer to the
00064         HyperTopic receiver object, the topic pattern, received message callback
00065         function and client data pointer (passed with message to the callback
00066         function.  The lbm_hypertopic_rcv_delete() API function also accepts
00067         an optional designation for a callback function to be called once 
00068         all message callbacks for the topic being deleted have completed.
00069 
00070         The lbm_hypertopic_rcv_destroy() API function should be called to 
00071         de-initialize and clean-up the HyperTopic receiver after all topics
00072         added to the HyperTopic namespace have been deleted.
00073 */
00074 
00075 #ifndef LBMHT_H
00076 #define LBMHT_H
00077 
00078 #if defined(__cplusplus)
00079 extern "C" {
00080 #endif /* __cplusplus */
00081 
00082 #include "lbm/lbm.h"
00083 
00084 #define LBM_HT_BASE_MATCH_LEVEL         0
00085 #define LBM_HT_TOKEN_GLOBNAME           0
00086 #define LBM_HT_TOKEN_GLOBPATH           1
00087 #define LBM_HT_TOKEN_NAME                       2
00088 
00089 #define LBM_HT_INIT_BRANCH_SZ   16
00090 
00091 #define LBM_HT_CBVEC_SZ 16
00092 
00093 /*! \brief HyperTopic receiver object (opaque)
00094 */
00095 typedef struct lbm_hypertopic_rcv_stct lbm_hypertopic_rcv_t;
00096 
00097 /*! \brief Application callback for messages delivered to  HyperTopic receivers.
00098 
00099         Set by lbm_hypertopic_rcv_add(). 
00100         If this application callback is set on an HyperTopic receiver that has
00101         been initialized without an event queue, it is called from the context
00102         thread and is therefore, limited in the API calls that it can make.
00103 
00104         After the callback returns, the message object \a msg is deleted and the
00105         application must not refer to it.  This behavior can be overridden by
00106         calling lbm_msg_retain() from the receive callback before it returns.
00107         It then becomes the application's responsibility to delete the message
00108         object by calling lbm_msg_delete() after the application no longer needs to
00109         refer to the message structure or its contents.
00110 
00111         \note For received application messages, be aware that LBM does not
00112         guarantee any alignment of that data.
00113 
00114         \param hrcv HyperTopic receiver object generating the event.
00115         \param msg Message object containing the receiver event.
00116         \param clientd Client data pointer supplied in lbm_hypertopic_rcv_add().
00117         \return 0 always.
00118 
00119 */
00120 typedef int (*lbm_hypertopic_rcv_cb_proc)(lbm_hypertopic_rcv_t *hrcv, lbm_msg_t *msg, void *clientd);
00121 
00122 /*! \brief Application callback for lbm_hypertopic_rcv_delete().
00123 
00124         Set by lbm_hypertopic_rcv_delete().
00125         Note: This application callback can be made from the context thread, and
00126         is therefore, limited in the LBM API calls that it can make.  The
00127         application is called after all events associated with the delete are
00128         completed.
00129 
00130         \sa lbm_delete_cb_info_t
00131         \param dispatch_thrd Indicates from where the callback is being called.
00132                 This can be useful to the application to avoid deadlock.
00133                 \arg 1 - Called by the dispatch thread (after the call to lbm_hypertopic_rcv_delete() returns).
00134                 \arg 0 - Called directly by the lbm_hypertopic_rcv_delete() function.
00135         \param clientd Client data pointer supplied in the lbm_delete_cb_info_t passed to lbm_hypertopic_rcv_delete().
00136         \return 0 always.
00137 */
00138 typedef void (*lbm_delete_cb_proc)(int dispatch_thrd, void *clientd);
00139 
00140 #define LBM_HT_CBVEC_FLAG_ACTIVE        1
00141 #define LBM_HT_CBVEC_FLAG_DELETED       2
00142 
00143 
00144 #ifdef LBM_HT_INTERNAL
00145 struct htcbvec {
00146         union {
00147                 lbm_hypertopic_rcv_cb_proc rcvproc;
00148                 lbm_delete_cb_proc delproc;
00149         } u;
00150         void *clientd;
00151         int flags;
00152 };
00153 
00154 struct htcbvlist
00155 {
00156         struct htcbvlist *next;
00157         struct htcbvlist *nextactv;
00158         int idx;
00159         struct htcbvec cbvec[LBM_HT_CBVEC_SZ];
00160 };
00161 
00162 struct lbm_hypertopic_rcv_stct
00163 {
00164         mul_mutex_t lock;
00165         lbm_wildcard_rcv_t *wrcv;
00166         lbm_event_queue_t *evq;
00167         lbm_context_t *ctx;
00168         struct htbranch *root;
00169         size_t prelen;
00170         struct htcbvlist *activecbs;
00171 };
00172 
00173 struct htcbnode
00174 {
00175         lbm_hypertopic_rcv_cb_proc rcvproc;
00176         void *clientd;
00177         struct htcbnode *next;
00178 };
00179 
00180 struct htnode
00181 {
00182         char *cname;
00183         int refcnt;
00184         struct htcbnode *cblist;
00185         struct htbranch *next;
00186 };
00187 
00188 struct htbranch
00189 {
00190         int nnodes;
00191         int size;
00192         int idx[LBM_HT_TOKEN_NAME+1];
00193         struct htnode htnodes[1];
00194 };
00195 #endif
00196 
00197 /*! \brief Structure passed to the lbm_hypertopic_rcv_delete() function so that a deletion callback may be called.
00198 */
00199 typedef struct lbm_delete_cb_info_t_stct {
00200     /*! The cancel callback function */
00201     lbm_delete_cb_proc cbproc;
00202     /*! Client Data passed in the deletion callback when called */
00203     void *clientd;
00204 } lbm_delete_cb_info_t;
00205 
00206 /*! \brief Initialize a HyperTopic receiver.
00207     \param hrcvp Pointer to location where the lbm_hypertopic_rcv_t object will be returned.
00208         \param ctx Pointer to the LBM context object associated with the receiver.  
00209         \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
00210         this HyperTopic namespace.
00211         \param evq Optional Event Queue to place message events on when they arrive. If NULL, all messages will be delivered from the context thread. 
00212         \return 0 for success, -1 on failure
00213 */
00214 LBMExpDLL int lbm_hypertopic_rcv_init(lbm_hypertopic_rcv_t **hrcvp, lbm_context_t *ctx, const char *prefix, lbm_event_queue_t *evq);
00215 
00216 /*! \brief Add a topic pattern to the set of topics being received by a HyperTopic receiver.
00217         \param hrcv HyperTopic object created by lbm_hypertopic_rcv_init()
00218         \param pattern Hierarchical topic pattern to add to the HyperTopic group.
00219         \param proc Pointer to a function to call when messages arrive on a topic matched by \a pattern.
00220         \param clientd Pointer to client data that is passed to \a proc when data arrives on the topic matched by \a pattern.
00221         \return 0 for success, -1 on failure
00222 */
00223 LBMExpDLL int lbm_hypertopic_rcv_add(lbm_hypertopic_rcv_t *hrcv, const char *pattern, lbm_hypertopic_rcv_cb_proc proc, void *clientd);
00224 
00225 /*! \brief Delete a previously added topic from a HyperTopic receiver topic set.
00226         \param hrcv HyperTopic object created by lbm_hypertopic_rcv_init()
00227         \param pattern Hierarchical topic pattern to delete from the HyperTopic group.
00228         \param proc Pointer to a function being called when messages arrive from the given \a pattern.
00229         \param clientd Pointer to client data that is being passed to \a proc when data arrives on a topic matched by \a pattern.
00230         \return 0 for success, -1 on failure
00231 */
00232 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);
00233 
00234 /*! \brief Clean-up HyperTopic receiver previously created by lbm_hypertopic_rcv_init()
00235         \param hrcv HyperTopic receiver to be destroyed.
00236         \return 0 for success, -1 on failure
00237 */
00238 LBMExpDLL int lbm_hypertopic_rcv_destroy(lbm_hypertopic_rcv_t *hrcv);
00239 
00240 #if defined(__cplusplus)
00241 }
00242 #endif /* __cplusplus */
00243 
00244 #endif

Generated on Thu Mar 6 13:11:09 2014 for LBM API by  doxygen 1.5.2