Destination Publisher objects send messages. More...

Macros
#define	TIB_DEST_PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS_TO_SEND "com.tibco.ftl.client.publisher.release"
	Ownership of outbound messages; boolean. More...

#define	TIB_DEST_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER "com.tibco.ftl.client.publisher.persistence.close.linger"
	Linger duration for persistent destination publisher close operation; double. More...

#define	TIB_DEST_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION "com.tibco.ftl.client.publisher.persistence.retry.duration"
	Retry duration for persistent destination publisher operations; double. More...

#define	TIB_DEST_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT "com.tibco.ftl.client.publisher.max.batch"
	Maximum batch count for non-inline destination publishers; integer. More...

#define	TIB_DEST_PUBLISHER_PROPERTY_INT_SEND_POLICY "com.tibco.ftl.client.publisher.send.policy"
	Destination Publisher send policy; integer. More...

#define	TIB_DEST_PUBLISHER_PROPERTY_STRING_LABEL "com.tibco.ftl.client.publisher.label"
	Property name for a destination publisher label; string. More...

Typedefs
typedef struct __tibDestPublisherId *	tibDestPublisher
	A destination publisher object realizes the message-sending functionality of a destination within a program. More...

Enumerations
enum	tibDestPublisher_SendPolicy { TIB_DEST_PUBLISHER_SEND_INLINE = 0 , TIB_DEST_PUBLISHER_SEND_NON_INLINE = 1 }

Functions
TIB_API void	tibDestPublisher_Close (tibEx e, tibDestPublisher destPublisher)
	Close a destination publisher. More...

TIB_API void	tibDestPublisher_Flush (tibEx e, tibDestPublisher destPublisher)
	Flush the destPublisher. More...

TIB_API int	tibDestPublisher_GetMaxBatchCount (tibEx e, tibDestPublisher destPublisher)
	Returns the maximum batch count of a non-inline destination publisher. More...

TIB_API tibDestPublisher_SendPolicy	tibDestPublisher_GetSendPolicy (tibEx e, tibDestPublisher destPublisher)
	Returns the send policy of a destination publisher. More...

TIB_API void	tibDestPublisher_Send (tibEx e, tibDestPublisher destPublisher, const char *dest, tibMessage message)
	Send a message to a destination. More...

TIB_API void	tibDestPublisher_SendMessages (tibEx e, tibDestPublisher destPublisher, const char destination, tibMessage messages, tibint32_t count)
	Send a batch of messages to a destination. More...

TIB_API void	tibDestPublisher_SendReply (tibEx e, tibDestPublisher destPublisher, tibMessage reply, tibMessage request)
	Send a reply message to a request message. More...

TIB_API tibMessage	tibDestPublisher_SendRequest (tibEx e, tibDestPublisher destPublisher, const char *dest, tibMessage request, tibdouble_t timeout)
	Send a request message to a destination. More...

Detailed Description

Destination Publisher objects send messages.

This file defines destination publisher objects and calls that send messages.

Macro Definition Documentation

◆ TIB_DEST_PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS_TO_SEND

#define TIB_DEST_PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS_TO_SEND "com.tibco.ftl.client.publisher.release"

Ownership of outbound messages; boolean.

When tibfalse or absent, client program code retains ownership of outbound messages that it sends through this destination publisher.

When tibtrue, the FTL library accepts ownership of outbound messages that the client sends through this destination publisher. Client code releases the message object when it invokes the send call; from that moment onward, client code must not reference the message object, because the FTL library can destroy the message object at any time.

Client code can release a message only if client owns the message. In particular, if a dest subscriber does not release its messages to the callback, then the callback must not send it through a publisher that releases messages. (See TIB_DEST_SUBSCRIBER_PROPERTY_BOOL_RELEASE_MSGS_TO_CALLBACK .)

See tibRealm_CreateDestPublisher

◆ TIB_DEST_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER

#define TIB_DEST_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER "com.tibco.ftl.client.publisher.persistence.close.linger"

Linger duration for persistent destination publisher close operation; double.

When a persistence destination publisher is configured for non-inline send, and a call to tibDestPublisher_Close is made while there are still messages waiting to be persisted, the call can be configured to wait for some time before closing the destination publisher. If the linger period elapses, and the messages have not been successfully persisted, the messages will be discarded. Set this property to control the linger behavior of tibDestPublisher_Close . The default value is 30 seconds.

Values:

0 Close the destination publisher immediately.
-1 Close the destination publisher only after it successfully persisted all outstanding messages
n (Any positive double value) Wait for the destination publisher to persist outstanding messages for at most n seconds. Proceed with closing the destination publisher upon success or timeout, whichever comes first.

Closing the realm supersedes and cancels linger behavior.

See tibRealm_CreateDestPublisher

◆ TIB_DEST_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

#define TIB_DEST_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION "com.tibco.ftl.client.publisher.persistence.retry.duration"

Retry duration for persistent destination publisher operations; double.

When tibRealm_CreateDestPublisher tibDestPublisher_Send, or tibDestPublisher_SendMessages cannot access the persistence server (usually because of network failure or quorum unavailability), they can automatically retry the interaction. The value of this property overrides the retry behavior of the server. Supply it to the publisher create call.

Values:

0 No retry. The call raises an exception.
-1 Synchronously retry the interaction until it succeeds. The call returns only upon success.
n (Any positive double value) Retry the interaction for n seconds. Return upon success or raise an exception after timeout.

Closing the destination publisher or the realm supersedes and cancels retry behavior.

See tibRealm_CreateDestPublisher

◆ TIB_DEST_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT

#define TIB_DEST_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT "com.tibco.ftl.client.publisher.max.batch"

Maximum batch count for non-inline destination publishers; integer.

When a persistence destination publisher is configured for non-inline send, this is the maximum number of messages that may be in flight to the persistence service at any given time. When this limit is reached, tibPublisher_Send blocks until some messages can be persisted, or a failure occurs. The default value is 100.

The tibDestPublisher_GetMaxBatchCount call returns the value currently in effect.

See tibRealm_CreateDestPublisher

◆ TIB_DEST_PUBLISHER_PROPERTY_INT_SEND_POLICY

#define TIB_DEST_PUBLISHER_PROPERTY_INT_SEND_POLICY "com.tibco.ftl.client.publisher.send.policy"

Destination Publisher send policy; integer.

Optimize the destination publisher for lower latency or greater throughput. The default behavior depends on the realm configuration.

Values:

TIB_DEST_PUBLISHER_SEND_INLINE Send the message immediately, to reduce latency.
TIB_DEST_PUBLISHER_SEND_NON_INLINE Buffer and batch messages before sending to help improve throughput.

When publishing to a store, and the administrator has configured publisher mode store_confirm_send for the store, the inline send policy causes tibDestPublisher_Send and tibDestPublisher_SendMessages to block until the message(s) have been successfully persisted, or until a failure occurs.

When publishing to a store, and the administrator has configured publisher mode store_confirm_send for the store, the non-inline send policy changes the behavior of tibDestPublisher_Send .

Calls to tibDestPublisher_Send return immediately, unless the maximum batch count has been reached. The message will be persisted in the background. See TIB_DEST_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT .
If a failure occurs in the background, the next call to tibDestPublisher_Send or tibDestPublisher_Flush will raise an exception. When this happens the application must assume that the most recent messages, up to the maximum batch count and including the message passed to tibDestPublisher_Send , have been lost. See TIB_DEST_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT .
When the application calls tibDestPublisher_Close , some messages may not have been persisted. In this case the close call may linger for some time before discarding the messages. See TIB_DEST_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER .
Applications may call tibDestPublisher_Flush to wait for all outstanding messages to be persisted.
If a failure occurs in the background, an advisory will be generated. This is a hint to the application that an error has occurred, and that a call to tibDestPublisher_Flush will raise an exception. See TIB_ADVISORY_NAME_NONINLINE_SEND_LOSS .

The tibDestPublisher_GetSendPolicy call returns the value currently in effect.

See tibRealm_CreateDestPublisher

◆ TIB_DEST_PUBLISHER_PROPERTY_STRING_LABEL

#define TIB_DEST_PUBLISHER_PROPERTY_STRING_LABEL "com.tibco.ftl.client.publisher.label"

Property name for a destination publisher label; string.

It is good practice to include this property in every destination publisher create call. Monitoring data incorporates these labels so administrators can identify and distinguish among publishers. Use labels that reveal the unique role and identity of each publisher within the application program.

If a non-inline persistence destination publisher fails to persist a message, the resulting advisory will include the publisher label. See TIB_ADVISORY_NAME_NONINLINE_SEND_LOSS .

See tibRealm_CreateDestPublisher

Typedef Documentation

◆ tibDestPublisher

typedef struct __tibDestPublisherId* tibDestPublisher

A destination publisher object realizes the message-sending functionality of a destination within a program.

A destination publisher object encapsulates all the information that a program needs to send a stream of messages to a destination. Destination Publisher objects send messages to the persistence service that are then disseminate to interested subscribers.

Programs can use a destination publisher to send messages to a destination. Destinations can be of type queues or topics or map destinations, but destination publishers can only be created on destinations of type queue or topic.

Destination publishers can be of two types

Statically bound to a destination specified during create all see tibRealm_CreateDestPublisher
Unbound destination publisher that was created with a NULL dest during create. and can be used to send messages to any destination during send call.

Enumeration Type Documentation

◆ tibDestPublisher_SendPolicy

enum tibDestPublisher_SendPolicy

Enumerator
TIB_DEST_PUBLISHER_SEND_INLINE	Publish with low latency; integer. If this value is set for property TIB_DEST_PUBLISHER_PROPERTY_INT_SEND_POLICY , then publish calls tibDestPublisher_Send and tibDestPublisher_SendMessages send messages immediately to reduce latency.
TIB_DEST_PUBLISHER_SEND_NON_INLINE	Publish with high throughput; integer. If this value is set for property TIB_DEST_PUBLISHER_PROPERTY_INT_SEND_POLICY , then the publish call tibDestPublisher_Send may batch messages in the background for improved throughput.

Function Documentation

◆ tibDestPublisher_Close()

TIB_API void tibDestPublisher_Close	(	tibEx	e,
		tibDestPublisher	destPublisher
	)

Close a destination publisher.

Closing a destination publisher releases all the resources associated with it.

Closing the publisher may discard messages that have not yet been sent to the persistence service, subject to linger behavior.

Applications may wish to call tibDestPublisher_Flush before closing the publisher

Parameters

e	The exception object captures information about failures.
destPublisher	The call closes this destination publisher.

◆ tibDestPublisher_Flush()

TIB_API void tibDestPublisher_Flush	(	tibEx	e,
		tibDestPublisher	destPublisher
	)

Flush the destPublisher.

Application can call flush after tibDestPublisher_Send() and or tibDestPublisher_SendMessages and messages that are held in destPublisher's internal queues will all be flushed.

This is a synchronous call, and the call will return only after all the messages are flushed, however if the applications has not specified any retry duration then this call will return an exception in the event of a failure.

NOTE: If the destination publisher was created with a TIB_DEST_PUBLISHER_SEND_INLINE send policy see TIB_DEST_PUBLISHER_PROPERTY_INT_SEND_POLICY, then this API is no-op.

Application is responsible to keep track of dests and corresponding messages, so in the event of a failure they can resend those messages.

Parameters

e	The exception object captures information about failures.
destPublisher	The destPublisher object .

◆ tibDestPublisher_GetMaxBatchCount()

TIB_API int tibDestPublisher_GetMaxBatchCount	(	tibEx	e,
		tibDestPublisher	destPublisher
	)

Returns the maximum batch count of a non-inline destination publisher.

Returns the maximum batch count that is in effect for this publisher. Applications may use this call to determine appropriate behavior if a non-inline persistence publisher fails to persist a message.

See TIB_DEST_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT

Parameters

e	The exception object captures information about failures.
destPublisher	The destination publisher.

Returns: The maximum batch count.

◆ tibDestPublisher_GetSendPolicy()

TIB_API tibDestPublisher_SendPolicy tibDestPublisher_GetSendPolicy	(	tibEx	e,
		tibDestPublisher	destPublisher
	)

Returns the send policy of a destination publisher.

Returns the send policy that is in effect for this publisher. Applications may use this call to determine appropriate behavior if a persistence publisher fails to persist a message.

See TIB_DEST_PUBLISHER_PROPERTY_INT_SEND_POLICY

Parameters

e	The exception object captures information about failures.
destPublisher	The destination publisher.

Returns: The send policy.

◆ tibDestPublisher_Send()

TIB_API void tibDestPublisher_Send	(	tibEx	e,
		tibDestPublisher	destPublisher,
		const char *	dest,
		tibMessage	message
	)

Send a message to a destination.

Destination publishers can be of two types

Statically bound to a destination specified during create. see tibRealm_CreateDestPublisher
Unbound destination publisher that was created with a NULL dest during create.

NOTE:

If the destination publisher is statically bound, it's an error to call send with a a different destination.
If the destination publisher passed in here is an unbound destination publisher, it's an error to pass a NULL ('dest') destination.
If the destination publisher is statically bound, a NULL ('dest') destination implies that the send call use the destination publisher's statically bound destination.

Parameters

e	The exception object captures information about failures.
destPublisher	The destPublisher object.
dest	The destination name.
message	The message to send.

◆ tibDestPublisher_SendMessages()

TIB_API void tibDestPublisher_SendMessages	(	tibEx	e,
		tibDestPublisher	destPublisher,
		const char *	destination,
		tibMessage *	messages,
		tibint32_t	count
	)

Send a batch of messages to a destination.

Destination publishers can be of two types

Statically bound to a destination specified during create. see tibRealm_CreateDestPublisher
Unbound destination publisher that was created with a NULL dest during create.

NOTE:

If the destination publisher is statically bound, it's an error to call send with a a different destination.
If the destination publisher passed in here is an unbound destination publisher, it's an error to pass a NULL ('dest') destination.
If the destination publisher is statically bound, a NULL ('dest') destination implies that the send call use the destination publisher's statically bound destination.

Parameters

e	The exception object captures information about failures.
destPublisher	The destPublisher object.
destination	The destination name.
messages	The batch of messages to send.
count	The number of messages in the batch.

◆ tibDestPublisher_SendReply()

TIB_API void tibDestPublisher_SendReply	(	tibEx	e,
		tibDestPublisher	destPublisher,
		tibMessage	reply,
		tibMessage	request
	)

Send a reply message to a request message.

When sending a reply, the destination publisher cannot be statically bound to a destination, since the reply needs to be sent to the 'reply' destination

NOTE: Passing a statically bound destination publisher here will result in an exception.

Parameters

e	The exception object captures information about failures.
destPublisher	The destPublisher object.
reply	The reply message.
request	The request message.

◆ tibDestPublisher_SendRequest()

TIB_API tibMessage tibDestPublisher_SendRequest	(	tibEx	e,
		tibDestPublisher	destPublisher,
		const char *	dest,
		tibMessage	request,
		tibdouble_t	timeout
	)

Send a request message to a destination.

The request/reply API is a convenience API that allow for single request/reply.

The destination publisher object passed to this API can be an unbound publisher or if it's statically bound publisher then destination passed here can be NULL. The request will be sent to the destination specified here or to the statically bound publisher's destination.

Parameters

e	The exception object captures information about failures.
destPublisher	The destPublisher object.
dest	The destination name.
request	The request message.
timeout	The timeout.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ TIB_DEST_PUBLISHER_PROPERTY_BOOL_RELEASE_MSGS_TO_SEND

◆ TIB_DEST_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_CLOSE_LINGER

◆ TIB_DEST_PUBLISHER_PROPERTY_DOUBLE_PERSISTENCE_RETRY_DURATION

◆ TIB_DEST_PUBLISHER_PROPERTY_INT_MAX_BATCH_COUNT

◆ TIB_DEST_PUBLISHER_PROPERTY_INT_SEND_POLICY

◆ TIB_DEST_PUBLISHER_PROPERTY_STRING_LABEL

Typedef Documentation

◆ tibDestPublisher

Enumeration Type Documentation

◆ tibDestPublisher_SendPolicy

Function Documentation

◆ tibDestPublisher_Close()

◆ tibDestPublisher_Flush()

◆ tibDestPublisher_GetMaxBatchCount()

◆ tibDestPublisher_GetSendPolicy()

◆ tibDestPublisher_Send()

◆ tibDestPublisher_SendMessages()

◆ tibDestPublisher_SendReply()

◆ tibDestPublisher_SendRequest()