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