lbmht.h File Reference

Ultra Messaging (UM) HyperTopic API. More...

#include "lbm/lbm.h"

Include dependency graph for lbmht.h:

Go to the source code of this file.

Data Structures

struct  lbm_delete_cb_info_t_stct
 Structure passed to the lbm_hypertopic_rcv_delete() function so that a deletion callback may be called. More...

Defines

#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
#define LBM_HT_CBVEC_FLAG_ACTIVE   1
#define LBM_HT_CBVEC_FLAG_DELETED   2

Typedefs

typedef lbm_hypertopic_rcv_stct lbm_hypertopic_rcv_t
 HyperTopic receiver object (opaque).
typedef int(*) lbm_hypertopic_rcv_cb_proc (lbm_hypertopic_rcv_t *hrcv, lbm_msg_t *msg, void *clientd)
 Application callback for messages delivered to HyperTopic receivers.
typedef void(*) lbm_delete_cb_proc (int dispatch_thrd, void *clientd)
 Application callback for lbm_hypertopic_rcv_delete().
typedef lbm_delete_cb_info_t_stct lbm_delete_cb_info_t
 Structure passed to the lbm_hypertopic_rcv_delete() function so that a deletion callback may be called.

Functions

LBMExpDLL int lbm_hypertopic_rcv_init (lbm_hypertopic_rcv_t **hrcvp, lbm_context_t *ctx, const char *prefix, lbm_event_queue_t *evq)
 Initialize a HyperTopic receiver.
LBMExpDLL int lbm_hypertopic_rcv_add (lbm_hypertopic_rcv_t *hrcv, const char *pattern, lbm_hypertopic_rcv_cb_proc proc, void *clientd)
 Add a topic pattern to the set of topics being received by a HyperTopic receiver.
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)
 Delete a previously added topic from a HyperTopic receiver topic set.
LBMExpDLL int lbm_hypertopic_rcv_destroy (lbm_hypertopic_rcv_t *hrcv)
 Clean-up HyperTopic receiver previously created by lbm_hypertopic_rcv_init().


Detailed Description

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:

        <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>
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.


Typedef Documentation

typedef void(*) lbm_delete_cb_proc(int dispatch_thrd, void *clientd)

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.

See also:
lbm_delete_cb_info_t
Parameters:
dispatch_thrd Indicates from where the callback is being called. This can be useful to the application to avoid deadlock.
clientd Client data pointer supplied in the lbm_delete_cb_info_t passed to lbm_hypertopic_rcv_delete().
Returns:
0 always.

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

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 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.
Parameters:
hrcv HyperTopic receiver object generating the event.
msg Message object containing the receiver event.
clientd Client data pointer supplied in lbm_hypertopic_rcv_add().
Returns:
0 always.


Function Documentation

LBMExpDLL int lbm_hypertopic_rcv_add ( lbm_hypertopic_rcv_t hrcv,
const char *  pattern,
lbm_hypertopic_rcv_cb_proc  proc,
void *  clientd 
)

Parameters:
hrcv HyperTopic object created by lbm_hypertopic_rcv_init()
pattern Hierarchical topic pattern to add to the HyperTopic group.
proc Pointer to a function to call when messages arrive on a topic matched by pattern.
clientd Pointer to client data that is passed to proc when data arrives on the topic matched by pattern.
Returns:
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 
)

Parameters:
hrcv HyperTopic object created by lbm_hypertopic_rcv_init()
pattern Hierarchical topic pattern to delete from the HyperTopic group.
proc Pointer to a function being called when messages arrive from the given pattern.
clientd Pointer to client data that is being passed to proc when data arrives on a topic matched by pattern.
Returns:
0 for success, -1 on failure

LBMExpDLL int lbm_hypertopic_rcv_destroy ( lbm_hypertopic_rcv_t hrcv  ) 

Parameters:
hrcv HyperTopic receiver to be destroyed.
Returns:
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 
)

Parameters:
hrcvp Pointer to location where the lbm_hypertopic_rcv_t object will be returned.
ctx Pointer to the LBM context object associated with the receiver.
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.
evq Optional Event Queue to place message events on when they arrive. If NULL, all messages will be delivered from the context thread.
Returns:
0 for success, -1 on failure


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