lbmht.h File Reference

WARNING: the HyperTopic feature is deprecated and will be removed from a future release. More...

#include "lbm/lbm.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...

Macros
#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 struct 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. More...
typedef void(*	lbm_delete_cb_proc) (int dispatch_thrd, void *clientd)
	Application callback for lbm_hypertopic_rcv_delete(). More...
typedef struct 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. More...
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. More...
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. More...
LBMExpDLL int	lbm_hypertopic_rcv_destroy (lbm_hypertopic_rcv_t *hrcv)
	Clean-up HyperTopic receiver previously created by lbm_hypertopic_rcv_init() More...

Detailed Description

WARNING: the HyperTopic feature is deprecated and will be removed from a future release.

Informatica recommends using normal wildcard receivers with "PCRE" regular expression pattern matching.

All of the documentation and software included in this and any other Informatica Inc. Ultra Messaging Releases Copyright (C) Informatica Inc. 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 Inc.

(C) Copyright 2006,2023 Informatica Inc. 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)

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.

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. 1 - Called by the dispatch thread (after the call to lbm_hypertopic_rcv_delete() returns). 0 - Called directly by the lbm_hypertopic_rcv_delete() function.
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)

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

Add a topic pattern to the set of topics being received by a HyperTopic receiver.

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
	)

Delete a previously added topic from a HyperTopic receiver topic set.

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.
cbinfo	Pointer to callback informatin structure specifying a function to be called when the deletion is complete.

Returns

0 for success, -1 on failure

LBMExpDLL int lbm_hypertopic_rcv_destroy

(

lbm_hypertopic_rcv_t *

hrcv

)

Clean-up HyperTopic receiver previously created by lbm_hypertopic_rcv_init()

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
	)

Initialize a HyperTopic receiver.

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